Documentation/CharHighlight

Interoperability discussion:
MS Word has two different settings that can control character backgrounds. The main character toolbar sets "highlighting" (which only allows 17 choices - 16 colours plus none), while a more general option allowing all colours is "shading". LibreOffice really only has UI and internal settings that correspond with shading (up until trying to accommodate MS in 2013 anyway).

Question: If both highlighting and shading are defined, which one is displayed? Answer: Simple - highlighting. (including from a paragraph style - which has priority even over directly applied shading.) True in both MS Word and LO. [Character styles in Word apparently cannot hold highlight settings.]

Question: why can't LO just import/export everything as highlight - since it has the priority and MS UI handles it? Answer: It is limited to 16 colours - so colour distinctions can be lost. [The default in LO 5.0 is to export any changed colours as highlight.]

Question: why can't LO just import/export everything as shading - since the two settings do the same job? Answer: The main problem is MS Word. The tool Microsoft uses to highlight text doesn't remove shading. So any markup done by a LO user is seen as "permanent" - a bit like a pen is permanent compared to a pencil and eraser.) (MS Word CAN white-out the shading with the "Borders and Shading" paragraph tool, which really isn't that hard to discover in modern versions.) [The default in LO 7.0 is to export any changed colours as shading.]

Question? why can't LO also use two different tools to control character background? Answer: We don't really want to copy all of Microsoft's mistakes. It is also very confusing for a user to have two tools that (seem to) do the same thing.

Background
The blog post from the author is good reading

2013

 * Add a new character attribute (RES_CHRATR_HIGHLIGHT). (character highlight can't be set via UI. It's a next step to add a highlight option.)
 * If has highlight, then paint that, otherwise paint background (RES_CHRATR_BACKGROUND).

2015

 * user setting option to Export as highlighting or shading. Highlighting is the default. (SvtFilterOptions FILTERCFG_CHAR_BACKGROUND_TO_HIGHLIGHTING)
 * UI: when LO changes the background colour, RES_CHRATR_HIGHLIGHT is invalidated.

2020

 * ESC decides to default exporting as shading in LO 7.0.

Observations

 * LO also applies highlight as a priority over shading - even at the paragraph and character style level. Nice. Perfect.
 * Word does not seem to accept highlight in character styles - only paragraph styles and direct formatting. LO accepts highlighting in all three. FIXED.
 * LO DOES export highlight in paragraph styles. So it can be important to allow style settings to be cancelled with COL_TRANSPARENT. [import and export of COL_TRANSPARENT was broken. FIXED]
 * (NOTE TO SELF: Old Word 2003 spams those values directly in docx, and doesn't save in style).

Questions
What would happen if we import "none" instead of ignoring it? [FIXED]
 * It will enable us to cancel a highlight set in a style. bug 137683
 * Nothing bad. None is COL_TRANSPARENT which matches the default.  Yes, it will be explicitly set, but if LO changes the background, it will also be reset (at least if it was already explicitly set). So there are already lots of examples of highlight being set so that it is ignored.
 * HOWEVER: Exporting ignores COL_TRANSPARENT. So while it may look better on initial import, it won't round-trip. Therefore exporting needs to be fixed first.

What would happen if we export "none" instead of ignoring it? [FIXED]
 * We easily set NONE just to get rid of highlighting. So exporting indiscriminately will cause a lot of spam-y entries. Otherwise nothing bad.

What would happen if we delete/remove/clear the highlight setting for COL_TRANSPARENT when the background colour is changed in LO?
 * Can't (easily) be done at the UI level - since we aren't directly dealing with the actual attributes, we have to send an "overriding" value of COL_TRANSPARENT.
 * So the checking needs to be done at export time [DONE], not via dialog properties (unless using some kind of grabbag concept...)

Can we stop importing highlight into Character styles, since Word ignores it? [FIXED]
 * We should stop importing it. [reuse bug 138345 for that]
 * We also need to make sure we don't export a highlight for character styles. bug 138345

Can we stop importing highlight into paragraph styles too?
 * No - because a character style shading and direct format shading can override a para-style shading, but not a highlight.

Can we stop exporting highlight into paragraph styles too?
 * Yes. [bug 131920 has link to abandoned patch]
 * Anything that imports as highlight will always export as highlight. So don't worry about what is imported.
 * Thus, we are only talking about LO design and exporting. So we need to take into account overrides from both character styles and directly applied COL_AUTO.
 * Doing this also enables a COL_AUTO to override both the paragraph and character style setting.
 * MS Word has no ability to adjust the character shading OR highlight in styles - so MS can mostly be taken out of the picture - except that direct highlight tool can't override the paragraph charBackground, but in that case it is a paragraph property, so it should be more natural to look for the removal tool under paragraph - which is where it is found BTW.
 * [Not done since default is now to export as background anyway. But still could be done if desired, or if default again becomes highlight.]

What still needs to be worked on?
 * default to "compatibility" palette for char background for MS Format documents. [not worth the effort unless default is highlight]
 * rather difficult to do - currently only a single implementation that handles everything across sw/sc/sd/etc. [svx/source/tbxctrls/tbcontrl.cxx and svx/source/tbxctrls/PaletteManager.cxx]
 * need to add a structure to save more than one officecfg::Office::Common::UserColors::PaletteName - enum special_none, special_charHighlight
 * need to figure out some way to connect this special palette to only SW Parastyle, and direct-character uses of the ColorWindow.
 * only if MS formatted document - don't want to be seen restricting other formats
 * only reset hint on initial document load - or probably better only as default value. User needs to be able to set their own choice, AT LEAST for the document or application-loaded session.
 * another complication: DOCX ST_HighlightColor documentation indicate slightly different colours than the implemented palette based on SPRM (DOC) specifications: darkBlue - 00008b (not 000080), darkCyan - 008b8b (not teal 008080), darkRed - 8b0000 (not 800000), darkGreen = 006400 (not Green 008000), lightGray - D3D3D3 (not c0c0c0), darkGray - A9A9A9 (not 808080). Plus the color-words are not accurate in some cases.
 * always export the highlight colours as highlight, regardless of user setting? [no - removal tool is not that obscure any more in modern Word. Plus, that would make LO inconsistent in how to remove it's formatting, and perhaps cause import/spam-y export issues. Plus DOCX's apparently has a different palette than DOC. Sigh]