Bug 141128 - Does Bullets and Numbering toolbar define "different paragraph levels" - as the online help claims?
Summary: Does Bullets and Numbering toolbar define "different paragraph levels" - as t...
Status: RESOLVED FIXED
Alias: None
Product: LibreOffice
Classification: Unclassified
Component: Writer (show other bugs)
Version:
(earliest affected)
7.2.0.0.alpha0+
Hardware: All All
: medium normal
Assignee: sdc.blanco
URL:
Whiteboard: target:7.2.0 target:7.5.0 target:7.4....
Keywords:
Depends on: 146762
Blocks: Bullet-Number-Outline-Lists 139667
  Show dependency treegraph
 
Reported: 2021-03-20 16:22 UTC by sdc.blanco
Modified: 2022-08-07 19:15 UTC (History)
3 users (show)

See Also:
Crash report or crash signature:
Regression By:


Attachments
Tab and Shift+Tab do not change outline levels for PS in Chapter Numbering (9.22 KB, application/vnd.oasis.opendocument.text)
2021-03-25 14:16 UTC, sdc.blanco
Details

Note You need to log in before you can comment on or make changes to this bug.
Description sdc.blanco 2021-03-20 16:22:27 UTC
According to: https://help.libreoffice.org/7.2/en-US/text/swriter/main0206.html

    "The Bullets and Numbering bar contains functions to modify 
     the structure of numbered paragraphs, including changing the order of 
     paragraphs and defining different paragraph levels."

This description has been present since 2004, when the help page was first checked-in.

Question 1: Does the Bullets and Numbering bar define "different paragraph levels" (as stated in the help page)?

Question 2: If not, then how should it be designated?

The same help page sometimes refers to "numbering level" or times to "level in the numbering or bullets hierarchy" or "level in a numbering or bullets hierarchy"

I believe it is referring to text:level.

https://docs.oasis-open.org/office/OpenDocument/v1.3/cs02/part3-schema/OpenDocument-v1.3-cs02-part3-schema.html#attribute-text_level

Perhaps the expression should be:

"level in its list hierarchy"  (and used consistently on that page, and elsewhere).
Comment 1 sdc.blanco 2021-03-20 21:56:51 UTC
(In reply to sdc.blanco from comment #0)
> "level in its list hierarchy"
Point of clarification:  The main reason for proposing "hierarchy" is "smallest possible change" principle.  It is already used in this and other help pages(e.g., https://help.libreoffice.org/7.2/en-US/text/swriter/01/05130004.html). 

Here is another possibility, illustrated by rewriting the first bullet point on this (incorrect) help page: https://help.libreoffice.org/7.2/en-US/text/swriter/guide/insert_tab_innumbering.html

   "To move a paragraph down one hierarchical level in the list outline,
    click at the beginning of the paragraph, then press Tab."

cc: Mike K., Regina H. - grateful for your input on this issue.
Comment 2 sdc.blanco 2021-03-23 15:52:05 UTC
The immediate motivation for this ticket is the need to correct a mistake in: https://help.libreoffice.org/7.2/en-US/text/swriter/guide/insert_tab_innumbering.html

because it is the final "blocker" for bug 139667.

In relation to immediate need (first question to UXEval):  

I propose:

(a) that "list level" be used to replace "chapter level" in the three places where it appears (in the just-cited help page).
(b) the title of that page becomes: Changing the List Level of List Paragraphs

NB.  the term "list level" does not appear anywhere in the online "help". It is barely mentioned in the "Writer's Guide 6.4" - I could only find it on p. 264, and used in a way that suggests inadequate conceptual understanding.

This is why I bring this seemingly "trivial" question about "list level" to UXEval.

In relation to further development, if "list level" is accepted, then (second question/proposal to UXEval):

Modify this ticket/summary to become an enhancement request to develop a standard terminology (also in the UI) for how to discuss "lists" and "list levels" in relation to "outline" in relation to "list level".

The choice of terminology is tricky here -- because of potential confusion with "outline level" (which is unrelated). (See bug 140178, comment 13).


I would propose:

A. introduce the term "list outline" (to differentiate it from "outline level")
to refer to the relation to between "list level" and "list outline". Then help (and UI) could refer to the "the list level of a paragraph in a list outline"

B. In the Bullets and Numbering dialog UI: change "Level" to "List Level" in the Position and Customize tabs (to emphasize its meaning and differentiate from Outline Level in Paragraph dialog)

C.  Define "list level" and "list outline" in the Glossary.

D.  Decide whether the word "hierarchy" or "hierarchical" should be used in relation to lists, or if it is possible/acceptable to just use "list outline" (with a glossary definition).  (my opinion: see if "hierarch*" can be avoided).

At present, the words "list" and "level" , "outline", and "hierarchy" do not appear anywhere in the General Glossary ( https://help.libreoffice.org/7.2/en-US/text/shared/00/00000005.html )

E.  Update help pages to use the list terminology correctly/consistently, ideally with links to the Glossary definitions (see comment 0 for current examples that speak about level in the numbering or bullets hierarchy).

F. Consider adding some List Styles that are "outlines". 

Technically all the list styles are outlines already, because there are attributes for all levels.  The present workaround, as known (bug 140752), is to simply choose an Outline from the Outline tab in B&N dialog for a list paragraph with a list style applied, and your list style will be "updated" with that Outline. But maybe that bug will be fixed, and then it might be a nice feature to have some List styles predefined with "standard?" outlines.

G. I stop here -- there are probably more useful adjustments to be made...but maybe these suggestions are enough to motivate and inspire further development and clarification of the List UI (and terminology).
Comment 3 Dieter 2021-03-23 18:04:52 UTC
(In reply to sdc.blanco from comment #0)
> According to:
> https://help.libreoffice.org/7.2/en-US/text/swriter/main0206.html
> 
>     "The Bullets and Numbering bar contains functions to modify 
>      the structure of numbered paragraphs, including changing the order of 
>      paragraphs and defining different paragraph levels."

To reduce my answer to your original question: I agree, that "paragraph levels" is wrong here. It should be "list levels" (or what term ever will be used here, if a consistent terminology is established)
Comment 4 sdc.blanco 2021-03-25 10:13:09 UTC
(In reply to Dieter from comment #3)
> I agree, that "paragraph levels" is wrong here. It should be "list levels" (or 
> what term ever will be used here, if a consistent terminology is established)
So I propose that the introductory paragraph that explains the Bullets and Numbering bar in https://help.libreoffice.org/7.2/en-US/text/swriter/main0206.html should be:

"The Bullets and Numbering bar contains functions to modify the structure of list paragraphs, including changing their order and list level."

That description does not indicate promoting/demoting levels operate different with paragraphs assigned in chapter numbering, but then neither do the descriptions for the individual commands on the toolbar.
Comment 5 Mike Kaganski 2021-03-25 10:16:07 UTC
Please test it with Chapter Numbering. It should define both paragraph style and outline level of the paragraph (which of course depends on the style) then.
Comment 6 sdc.blanco 2021-03-25 10:26:51 UTC
(In reply to Mike Kaganski from comment #5)
> Please test it with Chapter Numbering. 
What does "it" refer to?

(meanwhile, I can confirm -- as I tried to indicate in comment 4 -- that demote/promote level does a beautiful job of changing the paragraph style of headings specified in the Chapter Numbering dialog.)

Are you suggesting that this is what "different paragraph levels" was trying to indicate in main0206.html?
Comment 7 Mike Kaganski 2021-03-25 12:31:53 UTC
(In reply to sdc.blanco from comment #6)
> (In reply to Mike Kaganski from comment #5)
> > Please test it with Chapter Numbering. 
> What does "it" refer to?

toolbar :-) - thank you for reminding me the need to be precise!

> (meanwhile, I can confirm -- as I tried to indicate in comment 4 -- that
> demote/promote level does a beautiful job of changing the paragraph style of
> headings specified in the Chapter Numbering dialog.)
> 
> Are you suggesting that this is what "different paragraph levels" was trying
> to indicate in main0206.html?

Possibly; and sorry for missing the mention of that in comment 4. I suspect those words might refer to this functionality - but it needs to me more explicit. It is indeed confusing ATM.
Comment 8 sdc.blanco 2021-03-25 12:50:07 UTC
@Mike, @Heiko  - immediate needs in this ticket:

(a) make changes labeled (a) and (b) in comment 2.
(b) make change to main0206.html as proposed in comment 4

Ok?
Comment 9 Mike Kaganski 2021-03-25 13:05:38 UTC
(In reply to sdc.blanco from comment #8)
> @Mike, @Heiko  - immediate needs in this ticket:
> 
> (a) make changes labeled (a) and (b) in comment 2.
> (b) make change to main0206.html as proposed in comment 4

OK.

I propose also 
(b.1.)

... For chapter numbering, it promotes and demotes chapters, changing heading styles according to the new chapter level.

Or something like that.
Comment 10 sdc.blanco 2021-03-25 13:28:26 UTC
(In reply to Mike Kaganski from comment #5)
> I propose also 
> ... For chapter numbering, it promotes and demotes chapters, changing
> heading styles according to the new chapter level.
Agree that it should be there, just not in this patch.

Reason: 
Notice in https://help.libreoffice.org/7.2/en-US/text/swriter/main0206.html that each item on the toolbar help page has a description of commands and link to a page that only discusses the "list" function of these commands.  Many of these pages need to elaborated to discuss the behavior for paragraph styles with chapter numbering.  (imo) this should be changed all at once => new ticket to update Bullets and Numbering toolbar and its subpages to reflect behavior with chapter numbering paragraphs.
Comment 11 sdc.blanco 2021-03-25 13:29:05 UTC
(In reply to Mike Kaganski from comment #7)
> It is indeed confusing ATM.
Maybe there should be a "Chapter Numbering" toolbar

Current situation:

  1. Existing help page for Bullet and Numbering toolbar does not 
     indicate that the commands can be used for Chapter Numbering as well.

  2. Existing Bullet and Numbering toolbar does not appear when cursor is
     on a PS that is listed in the Tools > Chapter Numbering dialog, if 
     the heading has "None" for its value in "Numbering".

     Implication: not possible to use toolbar to change level of
        headings, if they do not have numbers.

  3. Tab and Shift+Tab do not change the Outline Level of Heading PS.

  4. The Promote/Demote Level commands do change outline level (ps) of headings.
      (while the same command changes "list level" for list paragraphs)


Suggestions

  1.  When cursor is in a ps that is specified in Chapter Numbering (CN),
      then have a CN toolbar popup (similar to B&N toolbar), that would have 
      promote/demote but would NOT have the "Add to List" and "Bullets and 
      Numbering" dialog and "Toggle Ordered/Unordered List" buttons.

  2.  Tab and Shift+Tab should work with PS specified in CN dialog.

  3.  B&N toolbar should not popup with paragraphs in CN dialog.

  4.  No opinion about whether Promote/Demote Level should be differentiated.
      (but could keep same .uno, and use TargetUrl) so that there could be
      a "Promote List Level" and "Promote Outline Level" to make the UI more
      explicit about what is happening).
Comment 12 sdc.blanco 2021-03-25 14:16:17 UTC
Created attachment 170739 [details]
Tab and Shift+Tab  do not change outline levels for PS in Chapter Numbering

(In reply to sdc.blanco from comment #11)
>   3. Tab and Shift+Tab do not change the Outline Level of Heading PS.
I would like to modify this statement.  Sometimes WFM. Sometimes not. Attached is a "not" case, which arose from experimenting in using heading and Tab. Sorry no STR. 

But another reliable case of "not" is:

1. New document
2. Make a Heading 1 (or 2) PS and enter text.
3. Tab (at front of paragraph), no change in Level.
Comment 13 Heiko Tietze 2021-03-25 17:46:07 UTC
(In reply to sdc.blanco from comment #8)
> @Mike, @Heiko  - immediate needs in this ticket:

While I believe this renaming is over-engineering and most users are either not reading the difference or adverse slow down searching for the familiar term, I always appreciate consistency and think learning a new term is worth the change.
Comment 14 Commit Notification 2021-03-25 22:45:32 UTC
Seth Chaiklin committed a patch related to this issue.
It has been pushed to "master":

https://git.libreoffice.org/help/commit/c32400c5c4408d450ec11569ee28b0894c7392e9

tdf#141128 repair description of Bullets and Numbering bar
Comment 15 Commit Notification 2021-03-25 22:55:58 UTC
Seth Chaiklin committed a patch related to this issue.
It has been pushed to "master":

https://git.libreoffice.org/help/commit/6f068cc382d085ade3ef7177cc06859fcce1cf2c

tdf#139667 tdf#141128 (tdf#124582 tdf#135895) num. lists,levels,styles
Comment 16 Heiko Tietze 2022-01-12 08:22:04 UTC
Seth, resolve fixed?
Comment 17 sdc.blanco 2022-02-18 19:36:28 UTC
Finishing this bug involves at least:

1) maybe include a mention about chapter headings (see comment 5) at beginning of [1], and consider whether additional adjustments are needed in [1] after bug 147107 is finished.  (or whether a new bug should be filed for improving documentation about how to manually modify chapter headings, because [1] is written in relation to lists, not chapter headings.)

2) depending on what happens with bug 146762, adjustments will be needed in [2]

[1] https://help.libreoffice.org/7.4/en-US/text/swriter/main0206.html

[2] https://help.libreoffice.org/7.4/en-US/text/swriter/guide/insert_tab_innumbering.html
Comment 18 sdc.blanco 2022-05-24 22:16:00 UTC
(In reply to sdc.blanco from comment #17)
> Finishing this bug involves at least:
> 
> 1) maybe include a mention about chapter headings (see comment 5) at
> beginning of [1].
Done in:

https://git.libreoffice.org/help/commit/000df5aded9b5cbe2488dc2e9c9406c6b56767c5

as part of bug 147107
Comment 19 sdc.blanco 2022-06-16 15:20:10 UTC
(In reply to sdc.blanco from comment #17)
> depending on what happens with bug 146762, adjustments will be needed in
https://help.libreoffice.org/7.4/en-US/text/swriter/guide/insert_tab_innumbering.html

https://gerrit.libreoffice.org/c/help/+/135988
Comment 20 Commit Notification 2022-06-19 11:41:54 UTC
Seth Chaiklin committed a patch related to this issue.
It has been pushed to "master":

https://git.libreoffice.org/help/commit/ccf86626a70ee1c7c3b0f3b94a4406328b8116fe

tdf#146762, tdf#141128 correction for new tab insert behavior
Comment 21 Commit Notification 2022-06-19 11:43:21 UTC
Seth Chaiklin committed a patch related to this issue.
It has been pushed to "libreoffice-7-4":

https://git.libreoffice.org/help/commit/d188c4d9e6f35d85346157dd2842890d452738e5

tdf#146762, tdf#141128 correction for new tab insert behavior
Comment 22 sdc.blanco 2022-06-19 12:31:03 UTC
Further updates to help were also made in:
commit 000df5aded9b5cbe2488dc2e9c9406c6b56767c5 
https://gerrit.libreoffice.org/c/help/+/132870

Now the help in relation to Bullet and Numbering bar makes clear reference to "outline level" (in relation to paragraph styles assigned in the Chapter Numbering dialog) and "list level" to paragraphs assigned a list id. These changes address the questions raised in the OP (and subsequent questions along the way), so closing this ticket as FIXED.