Documentation/Numbering

Interoperability discussion:
Numbering lists are very different between LibreOffice and MS Word.

Terminology (for this document anyway):
 * listStyle: the numbering style that defines the 9/10 level's indentation, numbering characters etc. Undefined listLevel = use first level. DOCX=numId, DOC=sprmPIlfo,LO=RES_PARATR_NUMRULE/RES_PARATR_LIST_ID.
 * listLevel: which level of the listStyle is applied. DOCX=iLvl, DOC=sprmPIlvl, LO=RES_PARATR_LIST_LEVEL. Requires listStyle to have any effect.
 * outlineLevel: defines the items/indentation used to build a TableOfContents, PDF outline, (anything else?), etc. Usually (but not necessarily in MS) matches the listLevel. Has NO IMPACT AT ALL on numbering. DOCX=outlineLvl, DOC=sprmPOutLvl, LO=RES_PARATR_OUTLINELEVEL.

Recent Changes

 * outlineLevel was not exported to DOC until 7.2, and DOCX sometime after 3.5 with NONE only being exported since 7.2. (RTF only exports outlineLevel for Chapter Numbering styles.)
 * LO 7.3 fills in a lot of inheritance and chapter numbering gaps for DOC and DOCX import based on the research in this document.
 * LO 7.3 brought the listLevel property to paragraph styles. tdf#62032

Chapter Numbering / OutlineLevel
LibreOffice has a rather goofy anomaly, where something called Chapter Numbering (Tools menu) controls a special listStyle that is not available to the user (called Outline). The Heading 1-10 paragraph styles are assigned to this by default. The settings cannot be controlled by Styles - Lists, but only by Tools - Chapter Numbering (or Format - Bullets and Numbering). In addition, normal inheritance does not apply to the special Chapter Numbering styles, so any sub-styles do not inherit the outlineLevel, listLevel, or listStyle from a parent ChapterNumbering. [MS Word does not have any of these bizarre anomalies.]
 * implication: import: identify the best fit for the special Chapter Numbering style, and then run through all the styles to see if any of them inherit from it. If so, copy outlineLevel, listLevel, and listStyle.
 * implication: export: ?nothing? (LO sets explicit outline:none, listlevel0, liststyleNONE on subStyles, so as long as cancelling-NONEs are exported, it should be fine.)
 * implication: anything marked as chapter numbering cannot (easily) share the same listStyle with another style or paragraph. That's really bad for import interoperability.

Prior to LO 7.3, LibreOffice can ONLY apply listLevel as direct formatting, not in a style (except via ChapterNumbering).
 * implication: import: until now, we needed to copy the list level as direct formatting to every paragraph.
 * But now some of that code should be reviewed to remove spamming unnecessary attributes. [WAIT WITH THIS. Otherwise 7.2's poor support for inherited numbering will not be able to read DOC/X files created by 7.3.]
 * implication: Chapter Numbering might no longer have any value?

Question: Why can't we just leave chapter numbering empty on import? It is causing an incredible amount of grief. Answer: It certainly would avoid almost all import problems. However, it is nice for an original ODT to be able to keep it's Chapter Numbering settings when saved to a foreign format, so we pay a high price to achieve that.

Question: Does Chapter Numbering give us anything that cannot be achieved with a normal style? Answer: Only automatic listLevel, but that means the answer is now "no" in 7.3.

Question: Since MS Word doesn't have Chapter Numbering, and many numId's can define an "Outline numbering list", which numId should be imported as Chapter Numbering? Answer: Good question. DOC format seems to look for the numId that has the most outline levels defined (using only Heading X styles). 7.3 DOCX, uses a weighted algorithm that prioritizes numId 1, then one using Heading styles, then the one with the most outline levels.] If the listLevel and outlineLevel don't match, then that listStyle is automatically disqualified. Ideally it would also be disqualified if it shared an in-use abstract list, or if the text directly applied that listStyle.

Question: Does Word not have any anomalies then? Answer: It seems to have one in DOCX, although not documented. Only ONE style can hold a listLevelX per numId. So if Heading 3 and myHeading3 both are on the same numId (which doesn't define pStyle) and both specify listLevel 2, then only the first one processed will actually have listLevel 2. [Doesn't seem to be true for Word 2003 DOCX, so likely not a problem in DOC either -untested.]

LO has 10 listLevels, while Word only has 9
LibreOffice has level 0-9 as listLevels. MS Word has listLevels 0-8, as well as level 9 which is not-a-numbered-list.
 * implication: no big deal - we just treat the 10th level items as not numbered if anyone ever gets down that far. The user needs to fix that up then. (Better than pretending to be level 9, right? Actually, best policy is probably to just leave things as they are...)
 * implication: Not being able to cancel a style numbering in LO will probably become a pain. (Although no-setting is the same as the first level, so cancelling and specifying first level are equivalent - so no big deal. Cancelling numbering altogether is best done elsewhere anyway.)
 * NOTE: outlineLevel in LO is DIFFERENT. 0 = Body Text, and 1-10 are Outline Levels. MS Word's outlineLevel rules are the same as listLevel.

Abstract lists and actual lists

 * MS Word's numbering is broken into two pieces. The bulk of the definition is in the abstract list - where all of the formatting is defined. The actual list (with potential numbering restarts and formatting overrides) points to an abstract list.
 * LO's numbering is broken into three pieces.
 * At the highest level is the ListId. Although it doesn't contain any formatting information, it most closely relates to abstractNum in that it defines a single numbering sequence that can be shared by multiple numRules. It doesn't quite seem to be able to exist by itself though? It basically overrides a numRule - letting multiple numRules share the same numbering sequence.
 * numRule - closely approximates a merger of MS numId and abstractNum. It holds the formatting information, and can provide a listId if the paragraph doesn't.
 * numFormat - is equivalent to a single level in MS's abstractNum.

Question: Since a numId can be assigned to Chapter Numbering, can we use a listId to group numRule "Outline" with the corresponding WW8NumX numRule? Better answer? Just use "Outline" everywhere instead of numId X when it is assignable to chapter numbering. That seems to work fine, and avoids listId complications. [But this violates LO internal rules about the proper use of "Outline".]

numId 0
In DOCX, numId 0 has special meaning. It says "this paragraph/style is not numbered" and is used to cancel inherited numbering. [abstractNum can be (and usually starts at) 0 however]. In RTF, numId 0 has no special meaning. RTF doesn't appear to have any numbering inheritance, so all numbering is directly applied to the paragraph, so no cancelling is required.