Advanced TOC editing - details and others

[KevinH]

@icearch,

One question, if you have a TOC list like the following for a start.

Chapter 1
Chapter 2
Chapter 3
Chapter 4
Chapter 5
Chapter 6

And the user multi-selects chapters 2 through 4 and hits the MoveRight (indent) button.

Should Chapters 2 through 4 all be direct first children of Chapter one in that case? Or what?


Next assume the same starting chapter list in the TOC, but this time select chapters 2 and 4 (non-contiguous) and hit MoveRight, what would the final list look like?

Can you see the ambiguity here? When multi-selecting (contiguous and non-contiguous examples) how would the parent of each be chosen? It is not clear and in many ways it is contradictory.

Obviously, this is not an issue given the original single selection model.

Until issues like this are ironed out, there really is no test implementation I can make.

Would your work case be consistent with only contiguous multi-selection?

[icearch]

I am starting a new thread here to talk about the tech detail of how advanced TOC editing should work, so that the main new feature thread would not be flooded.

I need some testing, so it's just a placeholder now.

Anyone with questions or solutions or thoughts can post here.

[icearch]

I have some work in my hands so it may take several days for me to have free time to do this.

[KevinH]

Oh, no worries. I thought you had previously said you used some other software (calibre?) that allowed multiple selection for editing a TOC so I thought you might have ideas on how it worked based on that software. If not, I can wait.

[icearch]

Yes, I have some basic ideas, but need some testing to be sure. And to clarify some border conditions. Let's not hurry, I will come to a more rounded solution.

[icearch]

And I finally have some free time to do some test.

Next Are five segments.

1 is I tested how TOC editing works in Sigil.

2 is the conclusions I get.

3 is I tested how TOC editing works in Calibre. It's pretty messy.

4 is the conclusions I get.

5 is the new set of rules I come up with about how Sigil should accomplish advanced TOC editing.

If you are not interested in how I comes to these conclusions or think the testing part is messy (it is), just jump to the last.

I am not a CS professional and English is not my native language, so bear with me if I say some terms wrong. I post with lots of pic so it should help.

[icearch]

First of all, we already agreed that changing NAV or TOC should NOT affect what’s in the actual text, which is just how it works now, both in Sigil and Calibre.

So let’s see how entries moves in Sigil.

First of all, I created a file that contains 8 h1 tags.



And the TOC looks like this:



Lets move B to the right (indent it).



No problem, and continue clicking Right does nothing. That means the level must be continuous.

Then move C to right once, it becomes sub-level of A, Twice and it becomes sub-level of B.

Lets move D to the farest right for the next setp.



Now, move C to the left,



We can see D moved with C, it’s parent-level, as a whole.

Let’s say we have a configuration like this:



And move C to left:



So D and E moved with C.
And move C to right again:



We can see D/E/F/G all moved with C. Because we make C be the parent-level to all of these.

You can also make it past 6 levels





As to move up or down, it can only happens between entries with the same level, so not important.

[icearch]

So we can comes to conclusion below:

1. Moving an entry means moving all it’s current sub-level entries.

2. Moving an entry to right makes it sub-level of the entry above it, if already that, then right does nothing.

3. Moving an entry to left makes it goes up a level, until the top.

4. Moving an entry up or down switches with the entry above or below.

5. You can make as many levels as you want, up to the each entry a level.

[icearch]

Let’s see what Calibre do:



To my test, moving single entry works just like Sigil so no more repetition.

Let’s move multiple entries.



1. Continuous and same level:





Moves as if you move it one by one.



2. Non-continuous and same level:





Still, moves as if you move it one by one.




3. With sub level, select all and only entries within.









4. With sub level, select only parent entries





Works just like 3, and it auto select Sub-level entries for some reason. More movement show no difference with 3.




5. Here is the fun part:





This is caused by also moving entries one by one, but from bottom to top. If you move F, D, and B, you get the same result.




6. But if you select it continuously:





It moves like a single block.



And I will call it a day now, since I didn’t read the source code, does not know how it actually works. Mabe ask kovidgoyal for help.

[icearch]

But we can come to conclusions below:

1. Move continuous entries works like I’s a single block, retaining it’s inner structure.

2. Moving non-continuous entries works like moving them one by one, bottom to top.

[icearch]

And we can see it’s pretty messy here, lot’s of confusion.

So I think we can meet our need with a more clean and neat approach, with these set of rules:

1. Move entries means move all it’s sub-level entries, retaining all structures inside.

2. That means you can NOT select entries with different level.
2.1. Using Ctrl to select one by one of course have no problem( of not let user select entries with different level ).
2.2. Using Shift can only select the highest level ones the user chooses.

3. With rule 1 and 2, there is no difference between continuous and non.

4. Treat it like a automate queue, move each selected entries as user demands.

4.1. Moving them left or right can cause some issiue of becoming sub of each other.
4.1.1. If user demands right, work each entries T2B, so the below ones does not become sub of the above ones.
4.1.2. If user demands left, work each entries B2T, as the below one can break free first.

4.2. Moving them up or down can cause some issues in order. We need different directions
4.2.1. If user demands up, work each entries B2T, so it will float to top and not changing order.
4.2.2. If user demands down, work each entries T2B, so it will sink to bottom and not changing order.
4.2.3. Continuous or non have no difference, at the end it will bunch up and gather together with the same order within them.

5. Work it out and print the result to nav.xhtml.

I think that’s it, I think you do not need too much change in the code where it process movement, may need some hard work in the selecting part. Hope for the best.

[icearch]

After some second thought, maybe if we apply rule 4 strictly, we can let user select entries with different levels? Need more testing.

But better not for good measure. If user need to do different level editing, just do it in seperate steps.

[KevinH]

I will take a look at creating a demo build that acts similarly for testing things. But no promises.

Luckily based on a github there is QItemSelection and QItemSelectionRange classes in Qt that convert mixed and non-contiguous selections piecewise into a list of contiguous selection ranges. That should be useful for a MoveRight (indent). But for a MoveLeft (unindent) siblings have to be dealt with too which complicates things.

Since MoveUp and MoveDown only work for top level items and they carry their children they are much simpler.

What about multi-selections with Delete? The safest would probably be to limit it to single selection at a time as it wipes out children, grandchildren, great-grandchildren, etc so a lot could be lost.

[icearch]

MoveUp and MoveDown does not only apply to top level entries, they apply to every level, carring the childern.

As to delete, I really didn't thought of that.

After some test, both Sigil and Calibre delete items with all of it's childern. So I think maybe just make it be.

For avoiding big progess loss, maybe add Undo button? Calibre have Undo. Since if we are applying multi-item editing, adding Undo is a good idea.

[KevinH]

Not sure about Undo. Just cancel and reopen if you mess up. Nothing is applied until you save the result.

Yes, move up and down only works on top level items (and their children all come along) when we move them. To see this in Sigil try selecting a single second level toc row and try to use move up or move down, nothing happens. TOC is a QTreeView with row selection. Operations are done on rows.