Bug 152605 - Change "heading level" to "outline level" in UI and help pages for Writer (see comment 14)
Summary: Change "heading level" to "outline level" in UI and help pages for Writer (se...
Status: RESOLVED FIXED
Alias: None
Product: LibreOffice
Classification: Unclassified
Component: Writer (show other bugs)
Version:
(earliest affected)
7.6.0.0 alpha0+
Hardware: All All
: medium enhancement
Assignee: sdc.blanco
URL:
Whiteboard: target:7.6.0
Keywords:
Depends on: Clarify-Chapter-Heading-Outline-Level
Blocks: Heading-Numbering
  Show dependency treegraph
 
Reported: 2022-12-20 02:40 UTC by sdc.blanco
Modified: 2023-08-13 14:16 UTC (History)
8 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 sdc.blanco 2022-12-20 02:40:04 UTC
Summary:  Change "outline level" to "heading level" in UI and help pages.

Some reasons:

1. More meaningful in relation to numbering in Tools > Chapter Numbering
    For example, see [1] where "heading level" should replace "outline level"
2. Better consistency in help pages, which often refer to chapter heading,
   where "heading level" for a chapter heading, fits better than the (current) 
   "outline level".
    See for example [2] (which is already using "heading level" somewhat)
3. Makes more sense that (default) "Heading n" is assigned to
   "heading level" n, rather than the (current) "outline level".
4. Avoids confusion with lists, which also use "outline"
    See [3] and [4] for relevant comments.

In sum: Main idea (hypothesis) is that using the label "heading level" to refer to Tools > Chapter Number > Numbering tab > Level will (a) make the meaning/significance of "level" more transparent, including its relation to numbering of headers, and (b) allow improvements in the help pages to better communicate the connection between heading and heading level, while (c) reducing confusion with the use of "outline" in connection with lists.

----
[1] https://help.libreoffice.org/7.6/en-US/text/swriter/01/06060100.html
[2] https://help.libreoffice.org/7.6/en-US/text/swriter/guide/chapter_numbering.html
[3] https://bugs.documentfoundation.org/show_bug.cgi?id=107573#c15
[4] https://bugs.documentfoundation.org/show_bug.cgi?id=83071#c21
Comment 1 Heiko Tietze 2022-12-20 13:09:30 UTC
"Outline level" is used in many ui files and labels. "Outline Numbering" was changed to "Chapter Numbering" for bug 107573 (with the rejected request to revert in bug 141452).

It would be quite some effort to replace all the occurrences of "outline level". And the benefit is IMO little if not misleading since headings are just list attributes.

My take: WF. Open for discussion.
Comment 2 Adolfo Jayme Barrientos 2022-12-21 06:22:30 UTC
Bugs like this have routinely been filed by different people noting the inadequacy of the change made back in bug 107572 (which had a laughable rationale), and will keep on being filed as long as we don’t solve it
Comment 3 sdc.blanco 2022-12-22 12:00:09 UTC
(In reply to Heiko Tietze from comment #1)
> It would be quite some effort to replace all the occurrences of "outline
> level". 
Amount of effort is a matter of taste. I count 8 .ui files, and 4 string files, where the only change is to find "outline" and replace with "heading" - often in only a few places in each file. iow, seems manageable (to me), plus I am willing to do the work - if the idea seems worthwhile.  Therefore, the discussion can be considered solely in terms of the "value of the change", rather than a tradeoff between "value of change" vs "amount of work".

> And the benefit is IMO little if not misleading since headings are
> just list attributes.
And list attributes are just some assembly code. Point is that levels of abstraction are often used to refer to objects, so that persons do not need to know lower levels of implementation details. 

Benefit is that, at least in English, authors think of headings as headings, not as list attributes. Also, LO uses the word "Heading" for the default PS used in Chapter Numbering. So "heading level" can be understood as an attribute assigned to a PS (which is often named  "Heading" or if a custom PS is made, it is thought about as a "heading").  The connection between "heading level" and a heading PS seems more immediate and obvious than the connection between "outline level" and a heading PS.
Comment 4 sdc.blanco 2022-12-22 12:05:56 UTC
(In reply to Adolfo Jayme Barrientos from comment #2)
> Bugs like this have routinely been filed by different people noting the
> inadequacy of the change made back in bug 107572 (which had a laughable
> rationale), and will keep on being filed as long as we don’t solve it
This OP is not concerned with the change to Chapter Numbering (bug 107573).

fwiw - this proposal was motivated by problems in: https://help.libreoffice.org/7.6/en-US/text/swriter/guide/chapter_numbering.html, which is supposed to be a guide for how to use the Chapter Numbering dialog.

A. Notice the first (for me, almost incomprehensible) sentence in that guide:

   "You can modify the heading hierarchy or assign a level in the hierarchy 
   to a custom paragraph style."

If the proposed change is accepted, then I would write the first sentence as:  

 Use the Chapter Numbering dialog to assign heading levels to paragraph styles.

B.  Notice also the following sentence in the last section of that guide page

"2.  Click the heading level that you want to assign to the custom paragraph style in the Level list."

iow, "heading level" is already used in help (suggesting that it is a "natural" (unconscious) understanding of the meaning of the dialog). Anyway, if this OP is rejected, then "heading level" should be changed to "outline level" to be consistent with current terminology.
Comment 5 V Stuart Foote 2022-12-22 19:01:25 UTC
(In reply to sdc.blanco from comment #4)
> (In reply to Adolfo Jayme Barrientos from comment #2)

Yes, abbreviated "Chapter Numbering" label change of bug 107573 was a poor decision, "Chapter and Outline Numbering" would have been better replacement for "Outline Numbering"

That said, the adjustments (UI and help) here to use "heading level" are all reasonable, 

Doers decide, so thank you Seth!

+1
Comment 6 Heiko Tietze 2023-01-06 09:54:39 UTC
(In reply to V Stuart Foote from comment #5)
> Yes, abbreviated "Chapter Numbering" label change of bug 107573 was a poor
> decision, "Chapter and Outline Numbering" would have been better replacement
> for "Outline Numbering"

To my understanding we do not talk about "Chapter Numbering" but "Outline Level" as found in paragraph properties > outline & list.

There was some discussion whether to call it outline or chapter, for example bug 107573 comment 3, bug 141452 comment 0. But the feature was never called "Heading Numbering".

We do have 

In the Chapter Numbering dialog: Level > 1..10
In Paragraph properties: Outline > Outline Level = Level 1..10

The term "Heading" comes in play with the paragraph style. So rather changing "outline level" to "heading level" it would be just "level".
Comment 7 Olivier Hallot 2023-01-06 10:48:13 UTC
(In reply to Heiko Tietze from comment #6)
(snip)
> We do have 
> 
> In the Chapter Numbering dialog: Level > 1..10
> In Paragraph properties: Outline > Outline Level = Level 1..10
> 
> The term "Heading" comes in play with the paragraph style. So rather
> changing "outline level" to "heading level" it would be just "level".

The command is in Tools menu, so as newbie user exploring the software, I'd ask "Level" of what?
Comment 8 Eyal Rozenberg 2023-01-07 21:34:53 UTC
(In reply to V Stuart Foote from comment #5)
> Yes, abbreviated "Chapter Numbering" label change of bug 107573 was a poor
> decision, "Chapter and Outline Numbering" would have been better replacement
> for "Outline Numbering"

I disagree. I mean, it would have been a slight improvement, but adding the word  "Chapters" is not the way to go:

* "Heading and Outline Numbering" is the most, shall we say, explanatory and easy-to-understand - but rather long;
* "Outline Numbering" and "Heading Numbering" each have their benefits, and none of them is perfect IMHO. I would be willing to live with any of them, so I'm ok with the change suggested here.
* "Chapter Numbering" is entirely inappropriate, confusing and even silly, see my explanation in bug 141452. 

... and the above goes for "XXX level" just as it does for "XXX numbering".

sdc.blanco, please note that while bug 141452 asked for going back "Outline Numbering", that was only because that had been the previous name. I said I wouldn't mind it being "Heading Numbers" in bug 141452c26, at the bottom. So I would encourage you (and others) to reopen that bug and support it (perhaps changing the title to say Heading/Outline numbering).
Comment 9 Heiko Tietze 2023-01-12 14:39:35 UTC
We discussed the topic in the design meeting. 

The paragraph dialog uses "Outline & List" in the tab label, "Outline" as frame label, and "Outline level" for the dropdown label. We must not change only one and make things more complicated.

* Heading & List, Heading, Heading level - seems to be wrong
* Chapter & List, Chapter, Chapter level - follows the "Chapter numbering" dialog but is wrong here
* "Outline & List", "Outline", "Level" - might work but is not much of an improvement

And any change could have consequences at other dialogs too. The recommendation is therefore to keep outline. As commented before: the doer / OP decides.
Comment 10 sdc.blanco 2023-01-14 13:11:39 UTC
(In reply to Heiko Tietze from comment #9)
> We must not change only one and make things more complicated.
What are the complications that you (or design meeting) see in making such a change? 

In Paragraph Dialog, I would leave "Outline & List" tab label, and "Outline" (frame label) unchanged, but change "Outline Level" to "Heading Level".
 
> And any change could have consequences at other dialogs too.
Speculation, not an argument or reason. 

fwiw, I see only two relevant dialogs that are affected.
 - Paragraph dialog (just discussed)
 - Table of Contents (etc.) dialog (where I would propose "Outline" -> "Heading")

More relevant (imo) is Olivier's comment 7 which reflects about how Benjamin users will discover the meaning of outline level -- including implications for existing help pages (see comment 4 for an example). The main motivation in OP is to make it easier to explain the meaning of "outline/heading" level in the help pages.  If that suggestion does not seem persuasive, then I will just repair the already existing problems in the help pages (such as noted in comment 4), and leave it at that. 

Will ask Mike Kaganski if his experience with AskLibre gives any insight to possible difficulties with "outline level"...
Comment 11 Mike Kaganski 2023-01-14 13:45:45 UTC
I disagreed with bug 107573 decision; I explained my PoV in bug 141452 comment 21; I disagree with more replacements of correct terms with something resembling vague ideas that some casual users seem to be familiar with.
Comment 12 sdc.blanco 2023-01-17 13:26:00 UTC
Thanks for the concise, lucid comment 11, Mike.

(In reply to Mike Kaganski from Bug 141452 comment #21)
> We have currently just a mess, with more proposals coming to make it worse.
+1 for your objective to achieve terminological clarity and consistency.

In that connection, a couple of clarification questions:

1. iiuc “heading level” should not be used anywhere in LO interface and help pages.

2. (from Bug 141452 comment #21)
> Outline … must be used in Navigator instead of the "Headings".
“Headings” is a valid label  (If Headings = "Paragraph with Outline level")

If Navigator was changed, then should "Headings" be changed to "Outline" in the cross-reference dialog as well?  (seems appropriate to have the same label in both cases).
Comment 13 sdc.blanco 2023-01-27 14:24:17 UTC
(In reply to sdc.blanco from comment #12)
> (In reply to Mike Kaganski from Bug 141452 comment #21)
> > We have currently just a mess, with more proposals coming to make it worse.
> ... a couple of clarification questions:
> 
> 1. iiuc “heading level” should not be used anywhere in LO interface and help
> pages.
Answering my own question, I believe the answer should be "yes" -- Is that right @Mike?

which implies that in relation to UI:

"heading level" -> "outline level" in extended tips for 
sw/uiconfig/swriter/ui/flddocumentpage.ui
sw/uiconfig/swriter/ui/tocindexpage.ui

and for error message in:

sw/inc/AccessibilityCheckStrings.hrc

(there are also some "comments" in source code that use "heading level", which are not proposed for change here)

And then there are about 11 help pages that use "heading level", which should be changed to "outline level".

Have changed bug summary to reflect this change.
Comment 14 sdc.blanco 2023-02-09 13:39:31 UTC
As Adolfo (comment 2) noted, there is often confusion about headings, chapters, etc, which deserves to be addressed. 

The motivating interest for the OP was to establish/implement a consistent (documented) LO meaning in the UI and help pages, so that users can follow / understand the terminology.

Bug 141452 comment #21 gives some clear definitions for the meaning of "heading", "chapter" and "outline level".

"heading" = any paragraph (style) with outline level 1 or greater
"chapter" = any paragraph (style) with outline level 1
"outline level" = a paragraph property specified in the Outline & List tab

It seems worthwhile to make sure that the UI and help pages use that terminology consistently.

Implications of definitions.

- "Heading level" and "chapter level" are not useful terms and should be removed/replaced/rewritten in the UI and help.

- Where possible, "level" should be changed to "outline level" in the UI and help, to make it clear/unambiguous when "outline level" is meant (because there is also "list level"). 

Here is a first attempt to address those two implications.  

https://gerrit.libreoffice.org/c/core/+/146622

This patch should make the intention more concrete. 
But this bug is still unconfirmed, and I will not push it without getting feedback.
Comment 15 sdc.blanco 2023-02-11 17:05:28 UTC
This exercise -- of looking at how heading level and chapter level appear in help and and UI -- has made me see that Tools > Chapter Numbering would be better named Tools > Heading Numbering.  Hence the following trial balloon...bug 153549
Comment 16 Commit Notification 2023-02-11 23:32:12 UTC
Seth Chaiklin committed a patch related to this issue.
It has been pushed to "master":

https://git.libreoffice.org/core/commit/6f15382790e2e758ef7328a62341b30c655aced1

tdf#152605  change "heading level" to "outline level" in UI

It will be available in 7.6.0.

The patch should be included in the daily builds available at
https://dev-builds.libreoffice.org/daily/ in the next 24-48 hours. More
information about daily builds can be found at:
https://wiki.documentfoundation.org/Testing_Daily_Builds

Affected users are encouraged to test the fix and report feedback.
Comment 17 Commit Notification 2023-02-12 02:40:27 UTC
Seth Chaiklin committed a patch related to this issue.
It has been pushed to "master":

https://git.libreoffice.org/core/commit/496b1b3179ca096dea1fd91ab2408c02f16b06cf

tdf#152605 "heading level"->"outline level" and other tip corrections

It will be available in 7.6.0.

The patch should be included in the daily builds available at
https://dev-builds.libreoffice.org/daily/ in the next 24-48 hours. More
information about daily builds can be found at:
https://wiki.documentfoundation.org/Testing_Daily_Builds

Affected users are encouraged to test the fix and report feedback.
Comment 18 Commit Notification 2023-02-13 01:24:16 UTC
Seth Chaiklin committed a patch related to this issue.
It has been pushed to "master":

https://git.libreoffice.org/help/commit/12f4174031afc80e9d6ac387336e0185646f6977

tdf#152605 update UI label changes
Comment 19 Heiko Tietze 2023-02-13 09:43:54 UTC
(In reply to sdc.blanco from comment #14)
> "Heading" = any paragraph (style) with outline level 1 or greater
> "Chapter" = any paragraph (style) with outline level 1
> "Outline level" = a paragraph property specified in the Outline & List tab

And "Outline" is the more generic term for both Heading and Chapter. (This makes it a bit confusing.)
Comment 20 sdc.blanco 2023-02-13 17:55:00 UTC
(In reply to Heiko Tietze from comment #19)
> And "Outline" is the more generic term for both Heading and Chapter. (This
> makes it a bit confusing.)
Correct. But afaict, there is no need to use "Outline" in the help pages or the UI, which is a good thing, because it avoids introducing that ambiguity in those places.
Comment 21 Commit Notification 2023-02-13 19:36:10 UTC
Seth Chaiklin committed a patch related to this issue.
It has been pushed to "master":

https://git.libreoffice.org/core/commit/382e5a506e8c12e5c7af86d2fa018d00064f89d3

tdf#152605 (tdf#137968) "heading level" -> "outline level"

It will be available in 7.6.0.

The patch should be included in the daily builds available at
https://dev-builds.libreoffice.org/daily/ in the next 24-48 hours. More
information about daily builds can be found at:
https://wiki.documentfoundation.org/Testing_Daily_Builds

Affected users are encouraged to test the fix and report feedback.
Comment 22 Commit Notification 2023-02-18 03:04:08 UTC
Seth Chaiklin committed a patch related to this issue.
It has been pushed to "master":

https://git.libreoffice.org/help/commit/19870562065899332b16070b6724d628f8d1cb80

tdf#152605, tdf#137281 change "heading level" to "outline level"
Comment 23 sdc.blanco 2023-02-19 21:34:25 UTC
(In reply to sdc.blanco from comment #14)
> "chapter" = any paragraph (style) with outline level 1
Executive Summary:

1. Some developers advance the view that "chapter" is a heading with outline level 1 -- and that understanding has guided work on this ticket.

2. Analysis of the ODF Spec (shown below in Appendix) suggests/reveals that this definition is only appropriate in relation to indices. 

3. There is another meaning of "chapter" in the ODF spec that corresponds to what we are calling "heading" here.  

4. No immediate conclusions or implications are drawn from this analysis, beyond the friendly suggestion that the UI / help terminology does not necessary have to mirror the ODF spec.  

5. I will continue to work with the definitions given here, and still believe that a limited, well-defined terminology in UI and help is the way to go -- but it is possible that "chapter" (also in the context of ToC/Index) is not a good word choice (see previous point), and perhaps the UX team (and everyone else) can think a little more freely about appropriate technical terminology for the UI.

APPENDIX

1. In ODF spec, chapter as "heading with outline level 1" is true in relation to 19.818 text:index-scope [1] (i.e., when making ToC and other indices). 
(This "definition" can be seen in BZ in bug 112301 comment 2 and bug 141452 comment 21.)

2. But chapter has another meaning in the ODF spec that is not limited to outline level = 1 -- where the critical portion is quoted as follows:

---------------
7.3.8 <text:chapter>
The <text:chapter> element is usable within the following elements:  ... <text:h> 5.1.2, [2]
---------------------

In short: text:chapter is used within text:h.

3. And just to keep it confusing (because of an apparent contradiction), here is a definition that puts heading inside of a "chapter"

-----------------
5.1.2 <text:h>

The <text:h> element represents a heading in a document. Headings define the division structure for a document. A chapter or section begins with a heading and extends to the next heading at the same or higher level. [3]
----------------

I call it "apparent" contradiction because <text:chapter> is the XML used to display the heading content and number, where the heading has an outline level. This implements what is described as a "chapter" (from a heading to next heading at same or higher level).  

This is consistent with the observed behavior in many places in LO where the word "chapter" in the UI operates with what we are calling "headings" (e.g., bug  153560, bug 153561).

NB.  This meaning of "chapter" here is different from the definition in 19.818 text:index-scope

4. Finally, there is no child element in 3.4 <office:text> that appears to be relevant for implementing chapters. The relevant child element is <text:h> [4], as just discussed in points 2 and 3.

[1] https://docs.oasis-open.org/office/OpenDocument/v1.3/cs02/part3-schema/OpenDocument-v1.3-cs02-part3-schema.html#__RefHeading__1418944_253892949

[2] https://docs.oasis-open.org/office/OpenDocument/v1.3/cs02/part3-schema/OpenDocument-v1.3-cs02-part3-schema.html#element-text_chapter

[3] https://docs.oasis-open.org/office/OpenDocument/v1.3/cs02/part3-schema/OpenDocument-v1.3-cs02-part3-schema.html#__RefHeading__1415136_253892949

[4] https://docs.oasis-open.org/office/OpenDocument/v1.3/cs02/part3-schema/OpenDocument-v1.3-cs02-part3-schema.html#element-office_text
Comment 24 Commit Notification 2023-02-21 01:10:31 UTC
Seth Chaiklin committed a patch related to this issue.
It has been pushed to "master":

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

tdf#152605 update "chapter heading" to "numbered heading"
Comment 25 Commit Notification 2023-03-18 00:39:25 UTC
Seth Chaiklin committed a patch related to this issue.
It has been pushed to "master":

https://git.libreoffice.org/help/commit/1950b38e185b4ced962e2bacde9ac4086b31257c

tdf#152605 revise "heading level"; update command names
Comment 26 sdc.blanco 2023-06-26 00:52:20 UTC
afaict all "heading level" are removed from UI and help, so closing this ticket as FIXED