Bug 140579 - It's unclear, how "Continue previous numbering" should work
Summary: It's unclear, how "Continue previous numbering" should work
Status: NEW
Alias: None
Product: LibreOffice
Classification: Unclassified
Component: Writer (show other bugs)
Version:
(earliest affected)
unspecified
Hardware: All All
: medium enhancement
Assignee: Not Assigned
URL:
Whiteboard: target:7.2.0
Keywords:
Depends on:
Blocks: Bullet-Number-Outline-Lists
  Show dependency treegraph
 
Reported: 2021-02-21 10:32 UTC by Dieter
Modified: 2021-03-23 18:11 UTC (History)
3 users (show)

See Also:
Crash report or crash signature:


Attachments
How to combine items from three lists with two selections (12.83 KB, image/png)
2021-02-27 15:54 UTC, sdc.blanco
Details
proposal for initial help page about "Add to Previous List" (27.42 KB, image/png)
2021-03-16 22:13 UTC, sdc.blanco
Details
Second proposal for Help to Add to List (36.90 KB, image/png)
2021-03-17 17:27 UTC, sdc.blanco
Details
Possible final version for "Add to List" help (47.96 KB, application/vnd.oasis.opendocument.text)
2021-03-17 23:03 UTC, sdc.blanco
Details
How "Add to List" works (12.24 KB, image/png)
2021-03-23 12:50 UTC, sdc.blanco
Details
another version using unordered list instead of table (14.05 KB, image/png)
2021-03-23 12:54 UTC, sdc.blanco
Details

Note You need to log in before you can comment on or make changes to this bug.
Description Dieter 2021-02-21 10:32:23 UTC
There are several bugs that show problems with "Continue previous numbering" option (bug 36220, 122027, 117233, 139912). For me it is very difficult to consider, what is a bug / not a bug, because there is no documentation about that command in LO Help.

So what is needed is:
a) Design-Team should decide, how the command should work (for example: Should selection of "Continue previous numbering" deselect "Restart numbering" (related to bug 139912)? Should selection of "Continue previous numbering" be valid only for selected pargraph or the whole list (related to bug 36220)
b) Add documentation
c) Review bug reports.
Comment 1 Heiko Tietze 2021-02-22 09:36:27 UTC
Lists with the same style (eg. "Numbering 123") continue the numbering over the document unless restarted (the opposite, to always restart and continue on demand, was discussed in the past and rejected). Using a different list style starts a new numbering.

The toggle numbering on/off generates new list styles every time, which is the expectation of Benjamins, while the widget opens with a bunch of predefined styles that continue (the Eve use-case). Having both use cases in one control is convenient but OTOH also misleading.

Continuation and restarting the numbering are not mutually exclusive options but rather commands that can be applied at any time (actually Restart is an attribute: a list of 1,2,3 being restarted before 3 making it 1,2,1 can be extended to be 1,2,3,..,1). The "Continue previous numbering" command works on different list styles and overrides the current style with the previous one.

The logic is not simple but once you understand it makes sense. The only improvement I can see is to disable commands that not apply (first list in the document, no different styles etc.). But the effort sounds rather high compared to low benefit.

Perhaps we can do something with tooltips. What do you think, Seth?
Comment 2 Mike Kaganski 2021-02-22 10:22:42 UTC
(In reply to Heiko Tietze from comment #1)

I suppose that UX-wise, for Benjamin (who is the main audience of DF numbering applied through toolbar buttons, where indeed each time a new list style is generated), at least bug 36220 comment 10 is relevant and is real UX bug. When there is an existing list (123), and there is a command on the first element of this list to continue previous numbering (= merge lists), it should merge the whole list, not only the first item where the cursor is on. The command is "continue numbering", not "detach from the following numbering".

So I suppose that there *are* things that might be improved.
Comment 3 sdc.blanco 2021-02-22 13:48:12 UTC
(In reply to Heiko Tietze from comment #1)
> "Continue previous numbering" command works on different list styles 
> and overrides the current style with the previous one.
The action of "Continue previous numbering" is:

For the paragraph where the cursor is placed, assign the list id for the last list that appears before this paragraph, regardless of whether that list is a list style or a DF, and regardless of whether the paragraph already has an assigned list style or not.

> The logic is not simple but once you understand it makes sense. 
If the previous statement is correct, then the logic is very simple, but hard to track in the UI unless Style Inspector is used. 

Bug 117233 comment 12 suggests using status bar. 

fwiw, the command has nothing to do with numbering per se.  A more accurate label might be:  "Include in previous list"

(not advocating for this label -- just clarification for now - and before you say "too long"): 

Include in previous list
Continue previous numbering

> disable commands that not apply (first list in the document)
Already works that way in menu and context menu.

> no different styles etc.). 
Works that way for first item in first list, but not for subsequent list items (i.e., might not be too hard to disable).  
But note that it should be available for non-list paragraphs.
Comment 4 sdc.blanco 2021-02-22 14:12:02 UTC
(In reply to Dieter from comment #0)
> because there is no documentation about that command in LO Help.
There is a mention in Writer's Guide 6.4 (p. 182, p. 266), but it seems to be wrong.

There does not seem to be any mention in the "online help".

Probably should be added to: 
https://help.libreoffice.org/7.2/en-US/text/swriter/main0206.html

(and mention "hidden by default")

Should "Continue previous numbering" get an icon?
Comment 5 Dieter 2021-02-22 14:13:09 UTC
(In reply to sdc.blanco from comment #3)
> The action of "Continue previous numbering" is: 
> For the paragraph where the cursor is placed, assign the list id for the
> last list that appears before this paragraph, regardless of whether that
> list is a list style or a DF, and regardless of whether the paragraph
> already has an assigned list style or not.

I doubt, that that there is an agreement, that this actual behaviour is really the desired behaviour. For example see Mike's commetn #2 and his support of bug 36220 comment 10. I would also support this. And so the (desired) behaviour should be described as follows: "For the list where the cursor is placed, assign the list id for the last list that appears before this list, regardless of whether the two lists have a list style or a DF." And I would add: "This deselects 'Restart Numbering' option, if 'Restart Numbering' is active."
Comment 6 Dieter 2021-02-22 14:15:35 UTC
(In reply to sdc.blanco from comment #4)

I propose:
1. Add an icon to "Continue previous numbering"
2. Make that icon visible in toolbar by default
3. Add informations about it to https://help.libreoffice.org/7.2/en-US/text/swriter/main0206.html
Comment 7 Timur 2021-02-22 15:00:25 UTC
Icon is not a proper idea, there's already a bug with drop-down proposal 
https://bugs.documentfoundation.org/show_bug.cgi?id=117233. 

I don't see point in this bug, I just closed a few pf these bugs from comment 1.
And added further proposal for help in https://bugs.documentfoundation.org/show_bug.cgi?id=135895.
Comment 8 Timur 2021-02-22 15:11:06 UTC
For tracking in UI, it's seen, click in front and all list is shaded. 

Revisiting bug 36220, Help I proposed in 135895 also works here: just select 1st and numbered and it will work in step 5. Or select all to be continued in step 6. 
So with that, this bug is redundant.
Comment 9 Dieter 2021-02-22 15:33:35 UTC
(In reply to Timur from comment #7)
> Icon is not a proper idea, there's already a bug with drop-down proposal 
> https://bugs.documentfoundation.org/show_bug.cgi?id=117233. 

To be precise bug 117233 comment 12 gives several ideas: "So one solution can be to make it more prominent. E.g. add it in in the section Bullet List / Numbered List /... in the Styles menu. And add it to the drop-downs in the toolbar in addition to the item "More Numbering" or give it an icon and add it to the toolbar directly (command is ".uno:ContinueNumbering")." So a decision is needed, but we shuld discuss this in bug 117233
Comment 10 Timur 2021-02-23 07:45:30 UTC
This needs no complication more than needed. 
I see 2 issues here 
1. is Continue action from Comment 3 is correct? looks so. 
2. it should be in Help, just where? F1 on Continue gives missing help for uno:ContinueNumbering", should it have is own help page with just that snippet or be part of some more explanation (I prefer that).
Comment 11 Dieter 2021-02-24 14:35:10 UTC
(In reply to Dieter from comment #6)
> I propose:
> 1. Add an icon to "Continue previous numbering"

That's bug 126689.
Comment 12 sdc.blanco 2021-02-25 10:40:19 UTC
*Suggestion*:  For non-list paragraphs, rename "Continue previous numbering" to "Add to previous list", and rename "continue previous numbering" to "Combine lists" for paragraphs with a list id.

*Explanations*:
1.  .uno:ContinueNumbering acts on lists (ordered and unordered) and non-list paragraphs, but UI should present the command names contextually.
2.  With cursor in a non-list paragraph, right-click, choose List.
     a. at present, "Continue previous numbering" is shown.  
     b. The proposal is to change that to "Add to previous list"
3.  With cursor in a list item, or a selection of list items, then
    "Combine lists" should be shown in context menu.

*Benefits*.
1.  Labels would explain more clearly what will happen.
2.  Easier to document the two different situations, because they are more specific.
3.  No need to change the underlying .uno:ContinueNumbering command.

*Open question*.

For "Combine lists", there is a directional effect, based on the order of selection, which decides which list style (bullets, numbering scheme) "wins" (i.e., is used when different list styles are combined). If this is considered a "feature" that should remain, then "Combine lists" is the right command label, and the documentation has to explain the directional effect.

If the directional effect is "dropped", and the "first" list style always wins, then maybe "Add to previous list"  (i.e., same as non-list paragraphs) would be sufficient as command label.  The documentation would explain that all "selected" items (list and non-list) are added to the first list prior to the selection.  (Some "selection" rules for list items would also need to be explained, see bug 36220 attachment 170045 [details] for some examples.)
Comment 13 Heiko Tietze 2021-02-26 13:08:41 UTC
I like term "Add to previous list" and would use it in both cases. Not only because making the label depending on the context involves a lot of coding but also to have more static commands. And this "Add to prev. list" sounds not wrong to me when in a  (different) list.

This topic was on the agenda of the design meeting but hasn't got more input.
Comment 14 sdc.blanco 2021-02-27 15:03:44 UTC
(In reply to Heiko Tietze from comment #13)
>  making the label depending on the context involves a lot of coding
fwiw  probably not much coding would be required, because a TargetURL to .uno:ContinueNumbering could give a separate command name, and there is already a logic for when “continue previous numbering” is shown or not, so it is just to add a mention to the new TargetURL as part of the existing logic for showing "continue previous numbering" (basically being shown in the one situation where "continue previous numbering" is not shown).  This point is not meant to support the argument for multiple commands, but only to undercut the “more coding” argument as a justification for one command.
Comment 15 sdc.blanco 2021-02-27 15:54:53 UTC
Created attachment 170117 [details]
How to combine items from three lists with two selections

(In reply to Heiko Tietze from comment #13)
> topic ... hasn't got more input.
Main issue:  Some users will attempt to interpret the meaning of “Add to previous list” without reading relevant documentation.

I am advocating here only for an “informed decision” about the “label”, that appreciates the current behavior of .uno:ContinueNumbering, including its directional effects.  

Here are some simple exercises based on two lists to illustrate that behavior.

Use Toggle Ordered List to make two separate lists with different numbering schemes (I have chosen two so that I can refer to the list labels).

    1. Take abc cparaga
    2. Toogle Ordered List
    3. start to break it up
    4. asdfasdfaf


    (1) Now we continue to write.
    (2) andf
    (3) asdfasdfaf
    (4) modsfa
    (5) sdfasdf
    (6) asdfasdfaf

Demonstrations

Each technique starts with a “fresh” set of two lists as just described.

Technique A. Select part of line (3), press Ctrl, then select part of line 2., “continue previous…”

Result:  (3) → 5. (in second list) with no other changes in first or second list.  (i.e., numbering scheme/list structure of second selected list “wins”).

Technique B. (opposite direction now). Select part of line 2. and part of line 3. press Ctrl, select part of line (3), then “continue previous…”

Result:  2. → 1)  3. → 2) and all numbers changed in second list .  
(again numbering scheme of second selected list “wins”)

Technique C.  Select one or more consecutive lines in second list, starting with line (1) (and no selection in first list), then “continue previous…”

Result:  selected lines are added to previous list with previous list numbering scheme.

Technique D.  No result with “continue previous numbering” if (no selection in first list), and selection in second list is not consecutive paragraphs starting with of line (1)

Technique C. also works with non-list paragraphs, hence the suggestion “Add to previous list”, but notice, at present that Technique B does *not* add to previous list.  But Technique B has some justified use value.  (e.g., Suppose you decide that lines 3. and 4. should be lines 1) and 2) of the following list.  Technique B. does the trick. This is what motivated the suggestion “Combine lists” -- because you can decide -- depending on direction, what is combined with what.

These "combine" effects also work across multiple lists.  I have attached a screenshot example where selections (seen as blue highlighting) are made in list 2 and list 3, which results in them being added to list 1. (i.e., even though technique A is used there, it becomes technique C in effect because there is a previous list).

In short: if the label becomes “Add to previous list”, then .uno:ContinueNumbering needs to have its present “directional” capability (second list selected "wins") eliminated to make the “previous” list always “win” (in terms of list identity).

And what about Technique B, where some items at the end of the “previous list” can be added to the beginning of a following list? 
(that would also be eliminated with directionality).

And one final question.  At present, it is possible (i.e., Technique A) to add arbitrary items from a second list to a first list. Would that possibility remain?  If not, then the documentation would become easy, because it would never be necessary to select anything in the “previous list”. The help page might say: 

   1. Identify a list for addition.
   2. Select paragraphs after that list to be added.
   3. Choose “Add to Previous List”.
   Note: For paragraphs already in a list, only the first paragraph, 
         and any number of consecutive paragraphs, can be added.

I can see the value of the directional effects and differential selection effects. I can also see the value of "clipping the wings" of .uno:ContinueNumbering to make it only add paragraphs after a list (as described in the "help proposal"), so -- no opinion expressed here about what to decide -- beyond a request to have a clear decision about "expected" behavior of .uno:ContinueNumbering so that it can be documented.

Note -- this is *not* an issue of DF vs. list styles (i.e., the techniques described here work the same way on lists assigned to list styles, or with a mixture of DF and list styles).
Comment 16 sdc.blanco 2021-02-27 16:26:36 UTC
(In reply to sdc.blanco from comment #15)
> Note -- this is *not* an issue of DF vs. list styles
And not an issue of numbers vs. bullets either.
The directional techniques work the same with bullets.
No matter what the final command name becomes, it is a "good" thing that "numbering" in the present command name is changed to "list".
Comment 17 sdc.blanco 2021-03-16 15:08:31 UTC
Proposal for "tooltip" for .uno:ContinueNumbering -- in connection with renaming to "Add to Previous List"

    Add selected paragraphs to immediately preceding ordered or unordered list.

Reasons:
1. Short text.
2. Focuses on most likely (and easiest) command use (technique C in comment 15) 
3  Consistent with command name.
4. Signals that it can be applied with all kinds of lists.
5. No good ideas for signalling technique A or B (in comment 15) in a short tooltip, that would not obscure technique C.
Comment 18 Heiko Tietze 2021-03-16 15:35:03 UTC
(In reply to sdc.blanco from comment #17)
>     Add selected paragraphs to immediately preceding ordered or unordered
> list.

No need to be too short, and "immediately preceding" is not super simple English and "ordered or unordered list" needs to be understood as well. Simpler alternative could be "Make this paragraph continue the previous list, whether ordered or unordered."

I would also add kind of example like: "... For example, if the previous list ends with number 5 this one will start with 6." 

But your text is concise and more on the point, could be the better choice. Up to you :-)
Comment 19 Mike Kaganski 2021-03-16 15:37:16 UTC
(In reply to sdc.blanco from comment #17)
>     Add selected paragraphs to immediately preceding ordered or unordered
> list.

What is "ordered" and "unordered"? Do we use these terms somewhere? (I'm surprised; does "ordered" refer to "numbered/bulleted" or to "sequential/numbering restarted"?)
Comment 20 sdc.blanco 2021-03-16 15:51:46 UTC
(In reply to Mike Kaganski from comment #19)
> What is "ordered" and "unordered"? Do we use these terms somewhere?
bug 139667, comment 12
Comment 21 Mike Kaganski 2021-03-16 15:56:31 UTC
(In reply to sdc.blanco from comment #20)

Heh, funny to see the inconsistency, when some correct terms (outline numbering) get replaced with "layman" terms ("chapter numbering"), and others go in the opposite direction... ;-D Well, whatever. Thanks for the reference, I see it now in the UI in 7.2.
Comment 22 sdc.blanco 2021-03-16 22:13:11 UTC
Created attachment 170520 [details]
proposal for initial help page about "Add to Previous List"

"Continue previous numbering" has gotten a new name and its own icon (bug 126689), but does not have its own help page. Attached is a proposal for an initial help page.(The icon does not appear in this version because of a lack of updating that I cannot perform, but should appear in published version)

The page describes the "limited" version of the command (i.e., Technique C in comment 15). The description is consistent with the new label, and should remain valid even if its functionality is changed. In other words, the help page tells the truth, but not the whole truth about how the command works (at present).

Comments?
Comment 23 Dieter 2021-03-17 07:19:23 UTC
Thanks again for your work. My comment:
- Is the sentence "Choose the list to get additional list items" necessary (because you already inform how to access to the command). But if you think it is necessary I would either write "a list" or specify "the" list.

I also would prefer a clarification about the other techniques you've described in comment 15. Which techniques arevalid and which techniques should be considered as a bug. If there is a clarification a description of the valid techniques should be part of the help page. What do you think, Heiko?
Comment 24 Heiko Tietze 2021-03-17 08:30:38 UTC
(In reply to Dieter from comment #23)
> What do you think, Heiko?

It wouldn't be helpful to me because I approach the page from either the command itself being interested in its functionality or looking for a how-to-do-something. The only information is the first sentence without reason and technical background (lists generated on-the-fly vs. lists with a special style) neither an example ("continue numbering" was easy to understand although not precise).

But we had this conversation before and the help is done intentionally in this form with, IIRC, the idea that users follow instructions like recipes (what I also never do *g*).

So I'm the wrong person to ask about documentation.
Comment 25 Dieter 2021-03-17 08:53:42 UTC
(In reply to Heiko Tietze from comment #24)
> So I'm the wrong person to ask about documentation.

I don't ask for documentation, but for functionality. Comment 15 describes four different techniques how to use "Add to Previous List" button. Are all techniques desired or is there a technique, that should be changed? I think we need a consensus about it. (And as a second step we can document this consensus)
Comment 26 Heiko Tietze 2021-03-17 09:38:11 UTC
(In reply to Dieter from comment #25)
> Are all techniques desired or is there a technique, that should be changed? 

Only question I see is the directional Easter egg, and we have a discussion somewhere else. So yes, currently we support all techniques.
Comment 27 sdc.blanco 2021-03-17 11:56:02 UTC
I propose to change the command name from "Continue previous numbering" to "Add to List"

Reasons:
1. Possible to add paragraphs:
   (a) that appear prior to a list.
   (b) that appear both prior and after a list.
   (c) to any arbitrary list, if there are multiple lists.

2. In other words the "critical" feature is where the cursor is placed, when the command is used, not the position of the paragraphs in relation to the list.
Comment 28 Dieter 2021-03-17 11:58:11 UTC
+1
Comment 29 Mike Kaganski 2021-03-17 11:59:48 UTC
(In reply to sdc.blanco from comment #27)
> I propose to change the command name from "Continue previous numbering" to
> "Add to List"

... which would be confusing for a paragraph that is first in a following list. It is already in a list - where should it be added to?
Comment 30 sdc.blanco 2021-03-17 12:25:54 UTC
(In reply to Mike Kaganski from comment #29)
> ... which would be confusing for a paragraph that is first in a following
> list. It is already in a list - where should it be added to?
Yeah, it is confusing, when having to write documentation for it.

"First in following list" is a "special" case. It is always added to the list that comes prior.

"Second (or any other position) in following list" depends on which list was selected last. That is, the numbering that is applied is determined by the list where the cursor is located when the command is executed.

[this is the "background" or "reason" for that what is popularly called the "directional" effect or "Easter egg" (though I am not certain that it is an Easter egg). The "directional effect" focuses only on an accident of the geometry of a 2-dimensional surface. I prefer to called it "last-selected", and use the mnemonic "last-selected wins" -- except for this "special" case of "first" in the list.]
Comment 31 Mike Kaganski 2021-03-17 12:30:17 UTC
(In reply to sdc.blanco from comment #30)
> I prefer to called it ...

Heh. You just put it from feet to head, and prefer that ...

It adds to the list that is the list of closest paragraph-in-a-list *prior* to this paragraph. If it happens to be in the middle of a list, it simply happens that the closest previous paragraph-in-a-list is the previous paragraph that belongs to the same list. Trying to interpret id differently is just confusing yourself and your readers.
Comment 32 sdc.blanco 2021-03-17 12:36:28 UTC
(In reply to Mike Kaganski from comment #31)
> It adds to the list that is the list of closest paragraph-in-a-list *prior*
> to this paragraph. If it happens to be in the middle of a list, it simply
> happens that the closest previous paragraph-in-a-list is the previous
> paragraph that belongs to the same list.
Please give a concrete example to illustrate.
Comment 33 sdc.blanco 2021-03-17 14:22:09 UTC
---test document here ---
Para 1 – top of page
    1. List entry 1
    2. List entry 2

---end of test document---

Test 1
1. Select (some part) of Para 1
2. Press Ctrl, while selecting (some part) of List entry 1

Result: “continue previous numbering” is inactive.
Expected: ??

Test 2.
1. Select (some part) of Para 1
2. Press Ctrl, while selecting (some part) of List entry 1 and List entry 2 
   and ending with cursor in List entry 2.
3. Format>Lists> “continue previous numbering”

Result: Para 1 added to list.

Test 3.
1. Select (some part) of Para 1
2. Press Ctrl, while selecting (some part) of List entry 2 and then 
   List entry 1, ending with cursor in List entry 1.
3. Format>Lists> “continue previous numbering”

Result: “Continue previous numbering” is inactive.

Test 4.
1. Select (some part of) all three lines, ending with cursor in List entry 2.
Result: “Continue previous numbering” is inactive.
Expected: ??

Questions
1. Why should “continue previous numbering” be inactive in Test 1? (given Test 3)?
2. Test 2 and Test 3 are identical in terms of what is selected, but depending on cursor position, “continue previous numbering” is active or not. (seems unnecessarily arbitrary)
3. Given that all paras are selected in Test 2 and Test 3, why shouldn’t situation in Test 4 also enable “continue previous numbering”?
Comment 34 sdc.blanco 2021-03-17 14:25:40 UTC
(In reply to sdc.blanco from comment #33)
> 1. Why should “continue previous numbering” be inactive in Test 1? (given
> Test 3)?
Correction:  "Test 3" -> "Test 2"  (because Test 2 shows that Para 1 can be added).
Comment 35 sdc.blanco 2021-03-17 15:05:48 UTC
(In reply to Mike Kaganski from comment #31)
> If it happens to be in the middle of a list, it simply
> happens that the closest previous paragraph-in-a-list is the previous
> paragraph that belongs to the same list. Trying to interpret id differently
> is just confusing yourself and your readers.
I have re-read this several times, without being able to form a clear or stable meaning, but from what I understand, I believe it is not accurate.

Further and previous experiments (including using several different lists and non-list paragraphs) lead me to believe:

1. Select any paragraphs you want, anywhere in the document, list or no list.
2. Place the cursor anywhere you want (as long as it is in or after a list)
3. Format > Lists > Continue Previous Numbering

Result:  The list that immediately precedes the cursor (or where the cursor is located) will have its numbering/formatting applied to the selected paragraphs.
(with a caveat for some corner cases, where Continue Previous Numbering is not active, such as illustrated in comment 33)

This might make the documentation very easy.

1. Select paragraphs to be added to a list.
2. Place cursor in the list.
3. "Add to List"

Result:  Selected paragraphs get the labelling and formatting of the list.

(to be completely accurate, step 2 should be "in the list, or after the list, but before the next list".)
Comment 36 Dieter 2021-03-17 15:51:37 UTC Comment hidden (obsolete)
Comment 37 sdc.blanco 2021-03-17 16:28:41 UTC Comment hidden (obsolete)
Comment 38 sdc.blanco 2021-03-17 17:27:32 UTC Comment hidden (obsolete)
Comment 39 Dieter 2021-03-17 17:48:58 UTC Comment hidden (obsolete)
Comment 40 sdc.blanco 2021-03-17 21:49:45 UTC Comment hidden (obsolete)
Comment 41 Dieter 2021-03-17 22:30:20 UTC Comment hidden (obsolete)
Comment 42 sdc.blanco 2021-03-17 23:03:44 UTC
Created attachment 170539 [details]
Possible final version for "Add to List" help

(In reply to Dieter from comment #41)
> So perhaps "target list" could be a solution? But it's up to you
> to decide. 
Left as is. Seems less problematic than other "solutions". "target" introduces a new undefined term. (btw, this difficulty is related to the query in comment 23 about the necessity of a first step to "choose a list")

See attached for new version. 

> We should use it as a starting point and we will see if some
> modifications are needed later.
Agree.  This page is supposed to explain the operation of the command. 
But there are many interesting and useful ways that the command can be used.
For example, to add items "before" the list (see Test 2 in comment 33 for one example). Perhaps you also imagine a "guide" page, that gives some examples of  typical "use cases", that shows what the command can be used for, rather than explaining the basic procedure for how the command works (which is still only formulated empirically by induction from experiment - have not tried to find the source code).
Comment 43 Dieter 2021-03-18 07:02:05 UTC
(In reply to sdc.blanco from comment #42)
> Possible final version for "Add to List" help

Yes, no further comments from my side.


> Perhaps you also imagine a "guide" page, that gives some
> examples of  typical "use cases", that shows what the command can be used
> for, rather than explaining the basic procedure for how the command works

Perhaps too much for a help page, but good idea for the writer guide.
Comment 44 Mike Kaganski 2021-03-18 07:39:31 UTC
(In reply to sdc.blanco from comment #33)
> ---test document here ---
> Para 1 – top of page
>     1. List entry 1
>     2. List entry 2
> 
> ---end of test document---
> 
> Test 1
> ...
> 
> Test 2.
> ...
> 
> Test 3.
> ...
> 
> Test 4.
> ...

Let me describe the internal logic here. Maybe that would help you.

When Writer decides which list to continue, it takes into account the selected part that *has the cursor*. Note that no matter how many separate parts you select, only one of them has the *blinking cursor* at the position where you released your mouse button last time. So Writer internally has a selection object, which may be a list of chunks: "Current selection has three chunks: [para 1 pos 3 to para 2 pos 6]; [para 2 pos 8 to para 2 pos 13]; [para 3 pos 2 to para 4 pos 10]" (the cursor blinks at para 4 pos 10). The last one would be the active one, that will be considered.

Now it knows that to decide what list to continue, it needs to use [para 3 pos 2 to para 4 pos 10]; but it will not use the blinking cursor position, but the *start* of the active chunk, namely, para 3 pos 2 - so it will consider paragraph 3 properties, not paragraph 4 properties. This is important, since if paragraph 3 does not have any *previous* lists, it will be unable to have any list to continue, and the command will be unavailable.

Hope this helps.
Comment 45 sdc.blanco 2021-03-18 08:33:20 UTC
(In reply to Mike Kaganski from comment #44)
> Let me describe the internal logic here. Maybe that would help you.
Definitely. I prefer (that word again...) theoretical knowledge over empirical.

iiuc - then this is BOTH a positional and directional phenomenon (where the positional and directional are strongly correlated, because cursor position is always somewhere in the active chunk).  But I still do not understand "active chunk" adequately.

> When Writer decides which list to continue, it takes into account the
> selected part that *has the cursor*.
The positional part.  And confirmation of the value of "last-selected win" principle (though I started yesterday to think of it "cursor position")

> Now it knows that to decide what list to continue, it needs to use [para 3
> pos 2 to para 4 pos 10]; but it will not use the blinking cursor position,
> but the *start* of the active chunk, namely, para 3 pos 2 
This is the directional part (*start*).  But I need a clarification of the meaning of "active chunk". My guesses about the meaning of "active chunk" have not been adequate to make an explanation of the difference between Test 2 and Test 3, where I am guessing it is relevant. 

(I confess that it still seems like only cursor position.  This is explains why Test 1 and Test 3 give the same result. And also why Test 5 and Test 2 give the same result.)

Test 5.
1. Select Para 1
2. Hold Ctrl and select List entry 2.
3. Add to List

Result:  Para 1 is added.  (just like Test 2).

Probably my simple test document is too simple to be able to see the significance of *start* of active chunk over "cursor position".  
Can you give a concrete example to illustrate that (so I can overcome the limits of my knowledge from empirical induction)?

In any case, thanks for laying out the internal logic.
Comment 46 Mike Kaganski 2021-03-18 09:08:08 UTC
(In reply to sdc.blanco from comment #45)
> Probably my simple test document is too simple to be able to see the
> significance of *start* of active chunk over "cursor position".

No, and actually your test 4 is the example that you ask for:

> Can you give a concrete example to illustrate that?

You select a chunk from para 1 to list entry 2, and your (last, and at the same time the only) chunk ends at list entry 2 (where the cursor blinks), but it starts at para 1, so Writer considers para 1 when looks for a *previous* list. Para 1 does not have preceding paragraphs with lists, so Writer disallows adding to list, despite the selection contains the list entry 2, and and even the blinking cursor is at list entry 2. That is how it's different from test 2, where the last chunk starts at list entry 2.
Comment 47 Commit Notification 2021-03-18 09:28:03 UTC
Seth Chaiklin committed a patch related to this issue.
It has been pushed to "master":

https://git.libreoffice.org/core/commit/7d76581ed37851ba1e588ecb919738e1d33784d6

tdf#140579 "Continue previous numbering" -> "Add to List"

It will be available in 7.2.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 48 Commit Notification 2021-03-18 09:35:18 UTC
Seth Chaiklin committed a patch related to this issue.
It has been pushed to "master":

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

tdf#140579 add "add to list" help page
Comment 49 sdc.blanco 2021-03-18 12:13:44 UTC
(In reply to Mike Kaganski from comment #46)
> No, and actually your test 4 is the example that you ask for:
Thanks. It is tricky (impossible?) to summarize succinctly, because there are multiple ways to make selections in multiple environments.

But to start:

Rule 1. position of *start* of active chunk determines whether or not there is a list to continue, which determines whether "continue previous numbering" command is active in menu/tb.

    But it is not so intelligent, because it also uses itself as a list, 
    so it sometimes shows itself as active, when there is nothing to continue.

    Examples:

    (a)  Test 6
         1. Select "List entry 2"

     Result:  "Continue previous numbering" is active (but nothing 
              happens when clicked).

    (b)  Technique D, comment 15 is another example.

Rule 2.  When "continue previous numbering" is active, and the active chunk is in only one list (when and two or more different lists are selected), then "Position of cursor" is functionally equivalent to "position of active chunk" (afaict), and the list formatting for the position of the "active chunk"/cursor is applied to all the selected paragraphs (regardless of their list status).
(this is background for my "last-selected wins", which I can see now is a useful heuristic, but not the operative principle).  (These are illustrated with Techniques A and B in comment 15)

Rule 3. There is another situation that I cannot explain with the "logic" (as I have understood it).

This is the "exception to Technique D" or in positive terms "Technique C" which is also the case that was added to the help:

"Add Consecutive List Entries to an Immediately Prior List"
1. Select one or more consecutive list entries, starting from the first entry, that you want to add to the immediately prior list.

(in this case, the prior list formatting is applied, regardless of which direction the entries are selected.  This is an exception to rule 2, because the formatting of the "position of chunk"/cursor is not being applied. And "start of chunk" does not seem to matter -- in the sense that one can select in either direction, but the result is the same.  But I cannot see how to twist the information in comment 44 to explain this case.
Comment 50 Mike Kaganski 2021-03-18 12:27:43 UTC
(In reply to sdc.blanco from comment #49)
>     But it is not so intelligent, because it also uses itself as a list, 
>     so it sometimes shows itself as active, when there is nothing to
> continue.
> 
>     Examples:
> 
>     (a)  Test 6
>          1. Select "List entry 2"
> 
>      Result:  "Continue previous numbering" is active (but nothing 
>               happens when clicked).

No. It does not consider itself. It always considers *closest **previous** paragraph which has a list applied*. For "List entry 2", there is a previous "List entry 1", which has list applied, and *that* paragraph and *that* list is used to apply to "List entry 2" (and that happens to change nothing, because "List entry 2" already is part of that list starting from "List entry 1"). There's no difference here (neither conceptual, nor functional), and so no need to try to make it a special case.

I didn't quite get the rest, honestly.
Comment 51 Mike Kaganski 2021-03-18 12:38:27 UTC
Oh...

There is only one rule. One and only one. And it is explained already.

1. Get the topmost point of the last selected chunk;
2. From that point, go to the previous paragraph;
3. Check if current paragraph (chosen at step #2) has a list applied;
4. If #3 is false, goto #2;
5. If there's no more previous paragraphs, it means that there were no paragraphs with lists before the one from #1; disable the command and exit;
6. If we are here, we found the closest previous paragraph with list. Enable the command; use this found paragraph's list when the command is executed.

No exceptions from the rule.
Comment 52 sdc.blanco 2021-03-18 12:54:44 UTC
(In reply to Mike Kaganski from comment #50)

> and so no need to try to make it a special case.
Wasn't trying to make a special case. Only speculating a possible reason because  did not have the important additional information that you just provided. Thanks.

From a UI/UX point of view, it is inconsistent to have "Add to List" disabled in some cases where there is nothing to change, but not in all cases, such as this one.
Comment 53 Mike Kaganski 2021-03-18 12:57:29 UTC
(In reply to sdc.blanco from comment #52)
> From a UI/UX point of view, it is inconsistent to have "Add to List"
> disabled in some cases where there is nothing to change, but not in all
> cases, such as this one.

No! It is not "cases where there is nothing to change", it is "there is no list in previous paragraphs". Wherever there *is* list in any of previous paragraphs, the function is enabled. This is the case when using a wrong terminology creates seeming inconsistency (so the terminology is wrong).
Comment 54 sdc.blanco 2021-03-18 13:11:23 UTC
(In reply to Mike Kaganski from comment #51) 
> There is only one rule. One and only one. And it is explained already.
Cool.  Just need one point of clarification, which I asked about before.

> 1. Get the topmost point of the last selected chunk;
"topmost" means sequential position in the document.
And this is the same as what you called "start of active chunk" in comment 44.
That is, "topmost" = "start of"  and this has has nothing to do with the direction in which the mouse was dragged in making the selection of the chunk.

Otherwise, I think I understand how to explain the different cases/techniques/situations that I have generated here.
Comment 55 Mike Kaganski 2021-03-18 13:14:41 UTC
(In reply to sdc.blanco from comment #54)
> > 1. Get the topmost point of the last selected chunk;
> "topmost" means sequential position in the document.
> And this is the same as what you called "start of active chunk" in comment
> 44.
> That is, "topmost" = "start of"  and this has has nothing to do with the
> direction in which the mouse was dragged in making the selection of the
> chunk.

Absolutely. And also it has nothing to do with vertical position on screen, so e.g. in case of two-column layout, a selection chunk starting at the bottom of the first column, and ending somewhere at the top of the second column, will consider the point at the bottom of the first column (even though it is vertically lower); my wording "topmost" may be confusing. You made it correct, when wrote "sequential position in the document".
Comment 56 sdc.blanco 2021-03-18 14:03:39 UTC
(In reply to Mike Kaganski from comment #53)
> wrong terminology creates seeming inconsistency (so the terminology is wrong).
Let me try without terminology.  My interest is to highlight some examples of actual behavior that from (my) UX pov seem "puzzling" or "strange" or "unexpected" or "problematic".

No assertion that these are bugs. I agree that each Case follows the "rule", (i.e., performing as designed). I understand how to explain them, not asking for explanations. As stated before, only trying to give some concrete (problematic) examples to consider from a UX perspective.  

(To All:  very easy to test/experience yourself. 
  1. Copy the section between the longer dashed lines to an empty document.
  2. The three lines between the shorter dashed lines is the test document.
  3. Apply list formatting to the "list entry" paragraphs.
  4. Follow the instructions for each "Case", using the "test document"
  5. Compare your results with the results described here.
 )
-------------------------------------------------
 test document   
----
Para 1
1. List entry 1
2. List entry 2.
----
"active" and "not active" refer to state of "Add to List" command in menu/tb

Test A
Case 1.  Select "list entry 1"    "not active"
Case 2:  Select "list entry 2"    "active, but nothing happens when clicked"    

Test B
Case 3: 
  a. Select Para 1
  b. Ctrl, select list entry 1    "not active"
     (same result if "list entry"
      then select "para 1")

Case 4: 
  a. Select Para 1
  b. Ctrl, select list entry 2    "active, and Para 1 is added to list"

Case 5:
  a. Select list entry 2
  b. Ctrl, select para 1          "not active"

-------------------------------------------------------

Problems from (my) UX pov.

1.  In Test A, it is strange for the button to be "not active" in Case 1, but "active" in Case 2, and for nothing to happen when pressing.  I would expect it to be "not active" in case 2 as well if nothing is supposed to happen.

2. In Test B, it is strange that direction of selection does not matter in Case 3 (when selecting List entry 1), but it does matter in Case 4/5 about whether the button is active or not.

3. In Test B, it is strange that Case 4 allows adding the item to the list, while Case 5 does not.
Comment 57 Dieter 2021-03-18 15:20:47 UTC
I think we've reached a very specialized discussion. I'm afraid, that no new people will join the discussion and read all (or most) comments. So my initial question was: How should command work? Heiko gave the answer in commment 26: "So yes, currently we support all techniques." So my question is answered and we have a proposal for documentation.
Clearly we can still discuss, if there should be an improvement in documentation or in the behaviour of the command itself, but I recommend to do this in separate reports. Otherwise we might never come to an end and we defenetly loose the overview.
Comment 58 sdc.blanco 2021-03-18 15:34:44 UTC
Suggest changing summary to something like:  
   How "continue previous numbering" / "Add to List" actually works and should work
Comment 59 sdc.blanco 2021-03-23 12:50:45 UTC
Created attachment 170657 [details]
How "Add to List" works

(In reply to Dieter from comment #0)
>For me it is very difficult to consider, what is a bug / not a bug, 
See attached procedure.
Comment 60 sdc.blanco 2021-03-23 12:54:44 UTC
Created attachment 170658 [details]
another version using unordered list instead of table

Here is another version, using unordered list, instead of table.
(formatting possibilities are limited in help DTD, e.g., no nested lists).
In any case, now QA has a reliable aid for evaluating "Add to List" bug reports.
Comment 61 Dieter 2021-03-23 18:11:59 UTC
(In reply to sdc.blanco from comment #60)
> In any case, now QA has a reliable aid for evaluating "Add to List" bug
> reports.

I agree