Bug 155269 - Chapter numbering mech silently changes para style numeric outline-level
Summary: Chapter numbering mech silently changes para style numeric outline-level
Status: UNCONFIRMED
Alias: None
Product: LibreOffice
Classification: Unclassified
Component: Writer (show other bugs)
Version:
(earliest affected)
7.5.3.2 release
Hardware: All All
: medium normal
Assignee: Not Assigned
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2023-05-12 22:46 UTC by R. Bingham
Modified: 2023-05-16 15:41 UTC (History)
3 users (show)

See Also:
Crash report or crash signature:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description R. Bingham 2023-05-12 22:46:29 UTC
Version: 7.5.3.2 (X86_64) / LibreOffice Community
Build ID: 9f56dff12ba03b9acd7730a5a481eea045e468f3
CPU threads: 8; OS: Windows 10.0 Build 19045; UI render: Skia/Vulkan; VCL: win
Locale: en-US (en_US); UI: en-US
Calc: CL Jumbo

Discovered this issue while developing an OTT having several dozen custom styles across paragraph, frame, and page. My desired OTT functionality includes power-user usage of both:

+ various Writer effects dependent on the outline-level mechanism, particularly the [Insert->Field->More fields->Document tab->Chapter->Chapter name], and 

+ use of the [Tools->Chapter number] mechanism for both auto chapter number prepend insertion by style name and by explicit field invocation [More fields->Document tab->Chapter->Chapter number].

Observed increasing erratic behaviors of the Chapter_name variables set of 10, 1 for each outline-level.
Observed increasing erratic behaviors of the Chapter_numbering mechanism and variables set of 10, 1 for each element of the Chapter_number text-string and erratic behavior of the Automatic Numbering (auto-chapter_number text-string insertion) mechanism.

In a purpose-created, compact diagnostic ODT, I tripped over the following reproducible sequences:

Start with fresh File->New (Default OTT) diagnostic ODT.

In Navigator->Styles->Paragraph, examine and record the numeric outline-levels of some paragraph styles you will play with in the [Tools->Chapter number] feature. For the Default OTT, that feature comes pre-loaded with the 'Heading <n>' styles. Just in case there is some hardcoded relationship to built-in para styles, create some custom styles inheriting from Default having a sample of numeric outline-level values + none (TextBody).

Open the [Tools->Chapter number] feature UI. This UI, unfortunately for user confusion with Outline&List numeric level, uses the term "Levels." I will use the term Element here, each Element (of 10 total) having in turn a numeric index (1--10) and several property slots such as [Number:], [Paragraph style:], [Before:] and [After:]. Explaining my rational for Element that will take several paragraphs, so I defer that.

Notice that with the Default OTT, the [Tools->Chapter number] feature is pre-loaded with the "Heading <n>" paragraph styles such that the ascending Element numeric index matches the numeric <n> value of the pre-load "Heading <n>" family para styles.

Make one or more changes to any of the 10 Elements' [Paragraph style:] property. Examples :

+ (A) move an incumbent style name in, say Element[4] [Paragraph style:] to, say Element7] [Paragraph style:]. You do this by going to Element[7] and selecting the style name of what is in Element[4] from the [Paragraph style:] picklist. You should see the change in the Preview area.

+ (B) remove (evict) some incumbent style name entirely from the 10-Element set of [Paragraph style:] styles. You do this by [Paragraph style:] < - [None] for some chosen Element index.

+ (C) add a para style not already in the incumbent style name set, either a Writer built-in or one of your new custom styles, to an Element [Paragraph style:] style slot, say Element[2], possibly displacing an incumbent style name.

OK-close  the [Tools->Chapter number] UI.

In Navigator again examine the outline-levels of the paragraph styles you just manipulated above in [Tools->Chapter number] Element [Paragraph style:] properties.

My observation is this:

The [Tools->Chapter number] feature SILENTLY CHANGES the numeric outline-level of the para styles just manipulated such that after OK-close those outline-levels == the numeric value of the index of the Element where that para style name has been set in [Paragraph style:].
+ For example (A), the new numeric outline-level for the re-located style is now 7.
+ For example (B),  the new numeric outline-level for the evicted style is now TextBody.
+ For example (C),  the new numeric outline-level for the net-added style is now 2.

This in turn, in a document having chapter_number and outline-level schemes under development experimentation, silently breaks the functionality of all other Writer features dependent on an independently stable numeric outline-level scheme, such as default index tables and, wait for it, [Chapter name]. Of particular note is that if you evict one of the pre-load 'Heading <n>' styles, that style gets silently demoted to outline-level TextBody. 

There is nothing in the user-facing documentation which states that the numeric index value of an Element is hardcoded as the same integer variable as the outline level of a paragraph style definition, including the "non-level" of TextBody. In fact, all of the configured Element[index] [Paragraph style:] styles could have the same numeric outline-level going in, an Element's numeric index value can be different from the [Paragraph style:] style numeric outline-level going in, or the Element [Paragraph style:] styles could have no outline level at all (TextBody). There is no documentation indication that the [Tools->Chapter number] feature forcibly changes the outline-level of an evicted style, potentially leaving that outline-level different from when the style was taken in to the [Tools->Chapter number] feature during an experiment.

The lack of such documentation notice suggests there is no reason for the user to expect the [Chapter number] feature to use or touch a para style numeric outline-level property. Why? Because the [Chapter number] feature behaves as if it uses the style NAME, not style outline-level, in the [Paragraph style:] property to recognize when to increment the integer counter of a given Element for prep of the chapter-number text string, when to do Automatic Numbering prepending.

Now why might a user NOT observe this issue? Because in simple [Tools->Chapter number] schemes, and indeed in the [Tools->Chapter number] "Heading <n>" pre-load, the Element index numeric value HAPPENS to match the para style outline-level numeric value. As long as the user NEVER changes an Element [Paragraph style:] property, they will never have the potential for a silent change in a para style outline-value.

From a user's POV, in a complex document all heck breaks loose for unknown reasons.

It is difficult to believe this silent change of outline-levels is intended behavior.

I notice other cases 129270, 129669, 140846. A recurring theme seems to be confusion on if, conflation of, as noted above, that the numeric index value of an Element is hardcoded as the same integer variable as the outline level of a paragraph style definition, including the "non-level" of TextBody. 

Regards.
Comment 1 m_a_riosv 2023-05-12 23:27:28 UTC
Please could you post in our forum https://ask.libreoffice.org/c/english/5.
There are people with a deep acknowledge of Writer, maybe it is not a bug but the way how styles are used.

In any case, here or there, a sample file, it's needed to test what's happen.
Comment 2 Mike Kaganski 2023-05-13 06:52:37 UTC
There is *no* separate "chapter numbering" and "outline" schemes in Writer. Outline is strictly equal to chapter. This feature was named "Outline numbering", before "helpfully" renamed "for convenience" of those who don't know what "outline" is - see bug 107573.

So basically, what you describe is not a bug, but a simple user confusion (caused by bug 107573).
Comment 3 R. Bingham 2023-05-14 22:41:42 UTC
(In reply to Mike Kaganski from comment #2)

Ah, ah! This is good.

Reviewing bugs 129270, 129668, 129669 and 140846 I see continuing *conceptual* confusion even among the LO Dev Team.

If this is "simple user confusion" then tell me why does it persist for this feature?

Noting the MK comment https://bugs.documentfoundation.org/show_bug.cgi?id=140846#c4 (LOL, LOL) about good intentions, I suggest a  part of the confusion persistence is that through incremental behavior and UI changes over the years in response to point bugs or enhancement requests regards levels, etc., those Dev Team responses, perhaps at best only lightly analyzed for conceptual and user experience consistency, have created a divergence between observed functional behavior (implementation) and observed *presentation* (the UI).

Users are responding to that disagreement with confusion and will continue that confusion until that divergence is reconciled away.

Let us see how this plays out in the present issue. This will be long because I am setting up user POV experience and mental-model concepts.

Mental-model of Styles

From a statement somewhere in the user-facing documentation (UFD), LO Writer is a **style** oriented document creation app. Most if not all visible document objects have an associated style-object that governs the textual and graphical presentation of the object. That association is a link to a style-object global to the document. We wave away nuances and complications from visible-object-local, anonymous style-object clones created by per-visible-object manual interventions. In theory, a change to a global style-object affects all linked document-visible objects (practice a different matter). Global style-objects have an existence observedly independent of being applied to any visible document object. A user can access the global style-objects for understanding, for config maintenance or to create new via Navigator. Here we focus on style-object sub-types (as presented in user POV Navigator UI they are peer sub-types) Paragraph and List. From observation, functionally List seems an enhancement on, or perhaps a wrapper of, Paragraph.

[Paragraph Style] (PS) feature
From observation, the PS tabbed-widget UI presents as the fullest-featured way to initially define/configure/update the properties of a PS-object. One of the PS style-object properties prominently managed via the UI is a sub-object identified as tab[Outline&List]->Outline->[Outline level:]. The value-assignment picklist for this sub-object offers 11 values: an ordered list of integer values 1 -- 10 and a mysterious non-integer "Text Body."

From observation, [Outline level:] seems important to the update behavior of the Document field variable Chapter->name, and perhaps other Writer features. Indeed, fiddling the value of [Outline level:] in global PS Foo changes how Chapter->name updates when scan-encountering paragraphs of PS Foo.

Note the "sequential scan" mental model of how the document text is processed.

[List Style] (LS) feature
From observation, the LS tabbed-widget UI presents as the fullest-featured way to initially define/configure/update the properties of a List style-object. Two tabs of that UI (tabs [Position] and [Customize]) present something visually on the left labeled a "Level." This Level thingy appears to be an integer-valued (1 -- 10) index for identifying a *set* of properties that instruct the construction of a sub-string of the final List-feature text output string prepended to visible, List style-object-linked paragraphs in the document. So 10 possible property sets in all. From observation, this integer index orders a rank relationship for resetting an implied numerical counter associated with each property set, and ordering the sub-string output from property sets in ascending integer value for (presumably language dependent) left-to-right concatenation in to the final List-feature output text string.

From observation, the LS->Level integer-values domain and the PS->[Outline level:] integer-values domain are mutually independent. That is, fiddling the PS->[Outline level:] value of a para assigned a list-style in PS->tab[Outline&List]->[Apply List Style]->[List style:] or manually set to a LS context does not seem to change what the LS feature does in presentation of the para text. LS->[Level] does not seem to be an explicitly exposed or picklist settable property of a given List style-object in the model of PS->[Outline level:]. Rather, the LS UI display index seems to only serve as an internal, organizing index for the List style-object feature.

OTOH, fiddling PS->tab[Outline&List]->[Apply List Style]->[List style:] picklist value *does* change the List-feature textual presentation.

So now we have the PS->[Outline&List] strongly presented as a config manager one of two features that involve some concept of mutually independent sets of **levels**. We have at least one Writer feature (field variable Chapter->name) which cares ONLY about [Outline level:], meaning most importantly for this narrative, it does NOT care about the *name* of the Paragraph style applied to a give para.

Now examine the [Tools->Chapter Numbering] (TCN) tabbed-widget UI.

[Chapter Numbering feature]
Right away the Numbering and Position tabs are strikingly similar to the LS->Customize and Position tabs, especially the former.   Those two tabs present something visually on the left labeled a "Level." The TCN "Level" thingy appears to be an integer-valued (1 -- 10) index for identifying a *set* of properties that instruct the construction of a sub-string of the final TCN-feature text output string prepended to each instance of a scan-encountered paragraph having a PS with the same name as in the property picklist slot of [Numbering]->[Paragraph style:]. So 10 possible property sets in all. From observation, this TCN integer index orders a rank relationship for resetting an implied numerical counter associated with each property set, and ordering the sub-string output from property sets in ascending integer value for (presumably language dependent) left-to-right concatenation in to the final List-feature output text string.

You might note how much of the above description is a copy/paste from LS feature.

My challenge to the Dev Team:

Explain how a user not yet stung could possibly mental model the TCN is anything *other* than an advanced version of the LS feature? Looks (UI) like a List duck, walks (generates sub-strings for a concatenated final text string output) List duck, quacks (prepends its final text string output) like a List duck. INCLUDING that bit about mutually independent sets of **levels** among the multiple List duck families and the Paragraph duck family.

RTFM? Hmmm... cite the pages.

Further, explain why you will not be bombarded with bug reports when stung users encounter that this TCN feature will silently slam the previously-understood-to-be-mutually-independent [Outline level:] value of any para style name brought new in to the feature as a [Paragraph style:], encounter that if an incumbent para style name is re-located between TCN "levels" that the [Outline level:] value of that para style will be silently slammed yet again, or encounter that if an incumbent para style name is evicted from the TCN feature config, that para style's [Outline level:] will be silently slammed to "Text Body." Nothing tells the user that in addition to PS->[Outline level:], TCN is *also* a manager of [Outline level:] value settings for paragraph styles.

NO. THING.

Having ranted that, I propose the following thought experiment:

(1) Ignore how TCN is currently implemented backstage, ignore the current entanglement with [PS]->[Outline level:].

(2) Focus on how a user observes the feature to work today, the key functionality of (mental model) during an internal scan-processing of the document text of how the TCN feature decides when to trigger a sub-string integer-counter increment, trigger a higher numeric index counter reset, and then quack (prepend to a para) the feature's output text string and quack an update to one of those 10 string-value variables of that same output text string. That trigger function is based on para style NAME recognition of the style applied to a scanned para. For the user, "levels" are meaningless for para style name recognition--you have a bag of para style names collected from the 10 [Paragraph style:] property slots and one of them triggers. As with List, TCN integer "levels" serve to internally organize property sets. The only para style property that is input to this processing is the recognition trigger on [Paragraph style:] NAME.

(3) Magic wand, I poof [Outline level:] to disappear from the GUI. Ignoring the deleterious effect on [Chapter->name] and perhaps other features, my challenge to the Dev Team is explain how TCN as described in (2) would not still work as the user expects.

(4) If you cannot so describe, you have a path forward from the painted-in corner in which you are now trapped.

I would then propose:

TCN is to be re-positioned as an advanced version of List, and as with List, has its own independent integer (could be alphabetic!) index scheme of organizing property sets with an ordered index value for constructing its output text strings. No conceptual connection to that [Outline level:] property of para styles, thus freeing that property from TCN inteference.

Part of the user-base re-training migration for this re-position is to leave the men Tools->[Chapter Number] path in place while also adding TCN to List Styles in Navigator as yet another List style-object AND re-work menu path Format->Bullets and Numbering to be:

Format->Bullets and Numbering->
  ->[List styles general: Bullets and Numbering]
  ->[List styles advanced: Chapter Numbering]

See also my suggestion of starting thought on novice, general and advance modes of the UI in 155054 Comment 5 to mitigate the conflicts between the needs of general users and power-users.
  
The feature of Chapter->name available in a variable or an array variable needs a mechanism. Could usefully be an option property in TCN to capture the text of the triggering para for update to the Chapter name array variable. However, I am reluctant to restrict Chapter name capture to just TCN as TCN by definition should not trigger on para styles of unnumbered chapters. Consider a book form with Indexes of contents, illustrations, tables, a Dedication, a Forward, an Introduction, a Prologue, numbered chapters, and an Epilogue, an Appendix or two or three, a Glossary, a Concordance, and Indexes of footnotes. Many, many unnumbered chapters. The [Outline level:] mechanism does usefully work for Chapter name as long as it is independent of TCN interference. However, Chapter name capture by para style name trigger as TCN does is an alternate or additional design to consider.

For a reallllllllllllllllly advanced concept for configuring TCN and possibly Chapter name, look at the Assign Styles UI of the Index configurator. For TCN, that UI concept would enable multiple PS names to trigger a given sub-string index property set rather than the very limiting one para style name property slot in the current design. Instead of [Paragraph style:], the UI would have (as the Index confgurator does) a button opening a variation on the Index Assign Styles UI.

Regards.
Comment 4 QA Administrators 2023-05-15 03:18:00 UTC Comment hidden (obsolete)
Comment 5 R. Bingham 2023-05-16 15:41:26 UTC
(In reply to R. Bingham from comment #3)
> (In reply to Mike Kaganski from comment #2)

Just be clear in the thought experiment, by '[Outline level:] to disappear from the GUI' I mean disappear as a user-configurable property in the [Paragraph Style] tabbed-widget.

Regards.