Bug 143197 - Writer: hidden link between list and chapter numbering
Summary: Writer: hidden link between list and chapter numbering
Status: NEW
Alias: None
Product: LibreOffice
Classification: Unclassified
Component: Writer (show other bugs)
(earliest affected) release
Hardware: All All
: medium minor
Assignee: Not Assigned
Depends on:
Blocks: Heading-Numbering
  Show dependency treegraph
Reported: 2021-07-05 09:56 UTC by ajlittoz
Modified: 2023-03-18 14:35 UTC (History)
9 users (show)

See Also:
Crash report or crash signature:

TOC discrepancy caused by list numbering (11.84 KB, application/vnd.oasis.opendocument.text)
2021-07-05 09:56 UTC, ajlittoz

Note You need to log in before you can comment on or make changes to this bug.
Description ajlittoz 2021-07-05 09:56:51 UTC
Created attachment 173363 [details]
TOC discrepancy caused by list numbering

While answering https://ask.libreoffice.org/en/question/316962/two-methods-of-chapter-numbering/?comment=317018#post-id-317018, Mike Kaganski and myself discovered an unsuspected "interference" between list numbering and chapter numbering.

When you click on the "numbered list" drop-down menu and select any numbering, the choice you make here not only results in numbering the current paragraph but also modifies Tools>Chapter Numbering configuration if the current paragraph is styled Heading n.

I understand this is a convenience for newbies not reading the Writer Guide and not taking the time to study how styles work. Indeed, numbering is one of the most complex feature in Writer because it involves two different style categories, but this behaviour adds to the confusion.

Also, there is no one-to-one correspondence between list numbering and chapter numbering.

Format>Bullets & Numbering, Customize tab

The "Number" menu offers Bullet, Graphics and Linked graphics items.

Tools>Chapter Numbering, Customize tab

The Bullet, Graphics and Linked graphics choices are impossible.

Many of the list configuration in the toolbar drop-down menu, including those in the `Outline` tab, show layouts with bullets. These do not translate to chapter numbering.

When you generate the TOC, this results in a discrepancy between the heading and the TOC entry.

When users mix list and chapter numbering, this always results in unmanageable mess because Writer gets confused about which numbering to apply. Here the confusion is created by the Writer implementation itself.

Though I understand the rationale for offering the feature to newbies in order to reduce the "access cost", I suggest to remove it because it causes difficult to diagnose errors.

List and chapter numbering should be separate and have been kept so for long. We here have a dubious feature which tries to mitigate the interaction by modifying Chapter Numbering without make users aware of it.

If list numbering a heading was a mistake, already numbered headings are modified. If chapter numbering was heavily customised, everything must be reconfigured manually!
Comment 1 Roman Kuznetsov 2021-07-25 17:31:03 UTC
>When users mix list and chapter numbering, this always results in unmanageable mess because Writer gets confused about which numbering to apply

For what user do it?

Can you say shortly what's problem?

Mike, or may be you can?
Comment 2 ajlittoz 2021-07-26 08:30:43 UTC
(In reply to Roman Kuznetsov from comment #1)
> For what user do it?

I can't tell. Mixing chapter numbering and list numbering (i.e. activating heading numbering with toolbar button) is a common newbie error. Likely caused by a Word habit.

> Can you say shortly what's problem?

Chapter numbering is a dedicated implicit "list style" not accessible outside headings (for safety). It is controlled from Tools>Chapter Numbering.

If user activates list numbering for his/her headings, list numbering takes precedence in text but is not disabled in Tools>Chapter Numbering. Thus, we end up with two numberings on headings. We're totally in undefined land (outside Writer specification). Numbering may or may not be right. It depends on the mess created by user and his/her (in)consistency (whether all headings receive list numbering or only part of them). There is no visual clue about it. TOC will be inconsistent either.

The fact that the drop-down menu in the toolbar for numbering modifies chapter numbering without warning user (even in the documentation) is faulty because:

- it maintains user confusion about the fact that chapter numbering should be independent from list numbering
- it resets possible user customisation of chapter numbering
- some list numbering modes are impossible as chapter numbering and degenerate into nonsensical configuration
- it doesn't encourage to correctly use Tools>Chapter Numbering

IMHO (but I'm biased by my expertise in Writer usage), Format>Bullets & Numbering, i.e. default lists without list styles, is a dangerous feature. It is offered to facilitate conversion for people coming from Word but it allows too easily to format lists and people stop there.

Default lists are hard to control and modifying format of already existing lists is very difficult because "independent" lists all use the same default list style. Writer is forced to contorted tricks to allow this instead of the neat behaviour of pure list styles.

> Mike, or may be you can?

Comment 3 Mike Kaganski 2021-07-26 11:15:28 UTC
I agree that using F12 as kind of shortcut for a different "Chapter Numbering" feature is bad. It (a) depends on correct initial work with the document, and if a newbie already did something incorrect with numbering, or used externally imported file type, the result would be unexpected; and  (b) it promotes F12 (which is a direct formatting function).

I would vote to disable this shortcut.
Comment 4 ajlittoz 2021-07-27 08:18:29 UTC
Disabling the shortcut is not sufficient in the case of Chapter Numbering because you can still damage the document through the toolbar button and menu.

A safer approach would be to check if the current paragraph style is bound to chapter numbering internal list style. If it is, some kind of warning should be presented to user explaining why the change is rejected.
Comment 5 Heiko Tietze 2022-05-12 10:32:46 UTC
I miss the expectation. You have H1 with a latin numbers, H2 uses lower case arabic characters as numbering with only 1 sublevel, and H3, H4 none. Changing via Tools > Chapter Numbering (CN) or Format > B&N is not different unless you apply an unordered list (bullets), which can't be used in CN. If I use bullets on H3 it's not taken into the ToC, however MSO does that. The round-trip shows both bullet on the heading and in the ToC after updating the ToC the whole entry is missing!

No question that this function is difficult in general. But we don't make it easier to access if we remove a shortcut. So how about bending the B&N function to CN in case of a heading? We could keep the buttons and show some kind of familiar dialog (ideally the dialog still shows list of presets filtered for CN, see bug 120905).

The user expectation is to click a button and the software handles the internals. Meaning B&N is done as list style for ordinary paragraphs and as CN in case of headings. So UX-wise we rather remove the CN dialog than B&N.
Comment 6 ajlittoz 2022-05-15 08:51:08 UTC
(In reply to Heiko Tietze from comment #5)

I can't answer for the average user. I consider myself as an expert in using Writer and I have clean ideas about typography (or I hope so).

The most difficult step for a newbie is to understand what defines in list in Writer and what makes lists different from each other. A list is characterised by a =list style=.

Paragraphs associated with the same list style are members of the same logical list. Numbering may be restarted but all paragraphs nevertheless belong in the same list. All will share the same numbering format (though the item text can look different is the list style is associated with several paragraph styles).

Several logical lists are necessarily associated with different list styles.

One of these is chapter numbering. For safety, its list style is "internal" (not listed in the side style pane) and therefore cannot be selected in paragraph style configuration dialog. This eliminates a cause of confusion. You must assign the paragraph style to an outline level in the specific chapter numbering dialog.

What about the direct-format lists created with F12 or toolbar buttons?

Obviously, the clean list style mechanism has been tweaked to facilitate newbie access to the feature. Contrary to explicitly styled lists, numbering appearance can be changed item per item. All items are not part of a single logical list and numbering can be changed from Format>Bullets & Numbering without affecting all items, showing that they are split into "independent" lists though they apparently share the same "style".

Compared to the rigorous definition of list through styles, this can even confuse a newbie if a list was made "erratically" (items initially entered, then some text with another list, then back to add more items to the first list) as a modification of numbering properties will not show up on the full "visual list" but only on the part where the cursor is.

The F12/toolbar button method may look like an easy way of creating lists, but most newcomers/Word-switchers don't understand the underlying principle (to be honest, it took me years to develop a satisfactory mental model, though I read thoroughly the available documentation) and this makes even more difficult to tune lists. The F12 method is acceptable only for one-shot short documents.

Unfortunately you can't request people reading first a dull caveat doc (to be created) before using Writer. I fear there is no real solution to the problem of list UI and "intuitiveness".

>So UX-wise we rather remove the CN dialog than B&N.

No. Chapter numbering is separate from list numbering (the style is "internal") and must remain so to avoid subtle problems.

Also, CN had additional properties I'd like to see forwarded to lists. The most valuable for me is the possibility to attach specific paragraph styles to different levels. But this reverses the logic for list configuration. Presently you attach a list style to a paragraph style, while my wish requires to attach paragraph styles to a list style. This could break compatibility with existing documents.
Comment 7 sdc.blanco 2022-05-15 09:26:17 UTC
(In reply to ajlittoz from comment #0)
> List and chapter numbering should be separate and have been kept so for long. 
ummm....the Bullets and Numbering Bar appears for both list paragraphs and for numbered paragraphs registered in Tools > Chapter Numbering (i.e., they are not separated there). 

Have suggested (bug 148673 comment 5) making separate toolbars for list paragraphs and paragraphs that appear in Chapter Numbering (Outline) (for reasons being discussed here, even if it seems redundant).
Comment 8 Eyal Rozenberg 2022-05-17 21:58:34 UTC
I don't understand what the bug is. Is that the interaction of list style and Outline Numbering (which is misnamed Chapter Numbering) in undefined? Is it the currently implemented behavior? Is it something in the ToC?

I opened the document; it is not clear what's wrong with it. Under the heading "Level 3" in there it says "Note the bullet" - but there's no bullet. Even regardless of that, the document does not indicate what the bug is. The ToC seems to match the content outside the ToC.

Version: / LibreOffice Community
Build ID: d9b33ed6644203141fdb0776c291425c2bc9f5ac
CPU threads: 4; OS: Linux 5.10; UI render: default; VCL: gtk3
Locale: en-IL (en_IL); UI: en-US

> I fear there is no real solution to the problem of list UI and "intuitiveness".

There certainly won't be a real solution if this matter is not properly discussed and summarized in a cogent document. It seems from your comments that no such official document exists, but perhaps others can enlighten us with a link. Although TBH that might be outside the scope of this bug.
Comment 9 Heiko Tietze 2022-05-18 05:52:40 UTC
The actual issue is that PS (paragraph style) can be assigned to a LS (list style), which is typically done for outline headings, see comment 6. If users change the LS, eg. per right-click List > Numbering Style, it results in an unexpected state. 

The ticket aims for a discussion whether the command Toggle Ordered List (shortcut F12) should become disabled on headings (has to be done for all kind of LS). The dedicated LS for headings is Chapter Numbering (CN) offering a subset of LS attributes with a fix style ID.

My take: since the restriction to CN does not work well I wouldn't go further and block LS but step back and use only LS. Effectively it is the same - however the initial "creation" of the LS could be done per F12 and would become an edit function later.

The ultimate question is: can we make the chapter numbering comfortable to use and easy to understand at the same time without too much restriction?
Comment 10 ajlittoz 2022-05-18 08:26:32 UTC
@Heiko Tietze is spot on the point.

Mixing list style direct formatting approach with chapter numbering results in an undefined state.

I like the present Chapter Numbering dedicated configuration despite its restriction on the type of "numbering" (no bullet). What I criticize is the possibility to interfere through F12 which messes up the CN configuration and creates inconsistencies.

One of these inconsistencies is

>Under the heading "Level 3" in there it says "Note the bullet" - but there's no bullet.

where saving the file "renormalized" what I tweaked (apologies, I didn't check that save-close-open roundtrip kept everything as I forced them). I forced a bullet "numbering" on levels 3 and 4. Bullets shows up in the headings (Heading 3 and 4 paragraph styles) but were not transferred to the TOC (Contents 3 and 4 paragraph styles).

>The ultimate question is: can we make the chapter numbering comfortable to use and easy to understand at the same time without too much restriction?

From my point of view, chapter numbering is quite comfortable to use but I am no longer a reference for newbie opinion. I haven't used Word for years and I don't remember how chapter numbering is implemented there, whether as a variant of list numbering or some other mechanism.

Merging list and chapter numbering is appealing but we must keep in mind the differences (perhaps artificial?):

- a list style may be attached to many paragraph styles, and this paragraph style will be used on all levels.
- a single paragraph style may be attached to a chapter numbering level through the CN configuration dialog
- the internal chapter numbering style cannot be attached to any paragraph style outside the CN dialog, enforcing the single style rule

For my advanced uses of Writer (which are likely not those of the majority of users), I'd like:

- to be able to differentiate paragraph styles per list level (CN→LS extension)
- to have also bullets in CN (LS→CN extension)

I don't think that assigning CN to several paragraph styles at the same level is a "good" extension because it may look weird. Outline formatting must remain homogeneous for obvious aesthetic reasons. But if uniformity calls for making CN an explicit user-accessible list style like Numbering 123, I won't object. It'll user responsibility to avoid ugly look.

Whatever the evolution of LS/CN, the most important goal is to avoid any unexpected state which would confuse user.
Comment 11 Heiko Tietze 2022-05-19 12:36:10 UTC
What we have in mind is probably the same. I'm trying to save users from knowing about a special LS for outlines. It should feel as much as possible like numbering. That's why I would keep F12/Numbering On and block everything what shouldn't be used (and prevent using this LS on ordinary paragraphs).

If we remove F12 and keep CN as a different way to number paragraphs users will stay confused and rather do some DF with bold weight and large size than using a heading style.
Comment 12 Eyal Rozenberg 2022-05-19 12:58:10 UTC
(In reply to Heiko Tietze from comment #11)
> That's why I would keep F12/Numbering On and block everything what shouldn't be used (and prevent using this LS on ordinary paragraphs).

What about imported documents? Are you certain they don't end up having paragraphs in that state-which-shouldn't-be-used?
Comment 13 Regina Henschel 2022-05-20 17:54:40 UTC
I consider the current behavior as bug. If you apply an anonymous list style to the heading it changes the defined chapter numbering and might produce the bullet/image problem (see bug 106983). If you apply a named list style, it changes this single heading to be inside a list and then sets this list style at the list. That is not consistent.

ODF 1.3 has in 16.36<text:outline-style> the rule, "An outline style is a list style that is applied to all headings within a text document where the heading's paragraph style does not define a list style to use itself."

Setting a list style in the paragraph style of a heading is valid in ODF. The heading need not be inside a list. Word shows the so defined numbering. But LibreOffice has not implemented it and does not show the numbering. LibreOffice always generates a list, when applying a named list style or by selecting a named list style in the "Outline & List" tab of the paragraph properties.

I suggest the following approach to help users generate clear document structures:
Using an anonymous list style should be disabled for those paragraphs that have a style bound to chapter numbering. 
When applying a named list to such a paragraph, there should be a warning that this will create a list and hide the chapter numbering settings.

On the "Outline & List" tab in the paragraph properties, the list style is disabled if the style is bound to chapter numbering. I'm not sure whether to disable applying a named list style by double-click in those cases.