[TOC] get an attribute directly from a style

[a.l.e]

i can attach my file, but it won't really show you, the few essential things you likely need to take into consideration for a "useful" TOC in scribus.

as i wrote, it would probably be helpful if you could go through:

• the forum thread i've linked above,
• this thread
• the README and the script in python (it's only about 100 LOC) in https://github.com/aoloe/scribus-script-repository/tree/master/table_of_contents

you will then have a list of things that people actually using scribus need for creating a TOC (their feedback has been very very useful to me!) and have a rather simple reference implementation.

[a.l.e]

Today, I have a bit more time.
Here my first impressions about the TOC in Scribus:


The Config > Tables of Contents dialog is not comfortable to use and some important features are missing.
(Some of the issue might already have been there before introducing the styles in the TOC...)

The top half of the dialog is by default empty and stays most of the time almost empty:
the huge majority of document with a TOC will only have one single TOC.
And when the user gets for the first time into this dialog, the goal is to define a table of contents!

I'm suggesting to pre-fill the list of TOCs with "Table of Contents" (without the "1"! The second one gets a "2") and make the list much smaller.
I guess that the TOC should only be saved in the .sla, if it has a minimal definition (at least one level defined...).

On the other side, the most "important" part of the dialog is probably the matching of heading and toc paragraph styles.

For each level we need (at least):

• the heading paragraph style,
• the toc paragraph style (yes, we need different toc styles for each level!),
• the page number placement.

So the first suggestion is to make the list of TOCs a simple list with two "icon buttons" (+, trashcan) and let the user change the name of the TOC by double clicking the entry in the list (no input field needed).
This list would be shown in the left part and on the rights side the TOC's settings.
The lower part would be for adding the levels with styles (or alternatively the attributes, if after having implemented a "usable" style based TOC you still think that somebody would want to use that...)

It could look somehow like that:

Code Select Expand

                                                                                                               
++---------------------------+-+-+-+-----------------------+-+                                                 
||table of contents         || |+| | type: [style |v]      | |                                                 
||                          || +-+ | source: [frame |v]    | |                                                 
||                          || +-+ | [ ] non printing      | |                                                 
||                          || |-| |                       | |                                                 
|+---------------------------+ +-+ +-----------------------+ |                                                 
|+---------------------------------------------------------+ |                                                 
||[h style |v] [toc style |v] [page number |v]             | |                                                 
||                                                         | |                                                 
||                                                         | |                                                 
||                                                         | |                                                 
||                                                         | |                                                 
||                                                         | |                                                 
|+---------------------------------------------------------+ |                                                 
|+-+ +-+                                                     |                                                 
||+| |-|                                                     |                                                 
|+-+ +-+                                                     |                                                 
+------------------------------------------------------------+                                                  (https://textik.com/#153e79c2edb01a7a)

By the way, as you might have noticed, my TOC Python script does not have a UI.
The main reason for it, is that it's indeed not easy to create a good UI and opted for default values and using the attributes.
But here now we have a UI and, as it is now, it forces lot of unnecessary mouse movements and scrolling that can be avoided.


One further important issue: picking the destination frame!
Do you really expect the user to know the name?
I see two possible solutions (which are not mutually exclusive):

• If a frame is selected when opening the settings, propose or use that frame as the target one
• If a frame is selected when running "Generate TOC" rename the menu entry to "Generate TOC in this frame" (or add such an entry)
• (Adding a "pick a frame" button is probably way to complicated and -- while being a nice idea -- it's way to complicated to implemented for its use)

I leave it open, if the TOC definition should stay in the document configuration, or if it should be moved to a separate dialog that can be triggered when a frame (the one containing the table of contents!) is selected.

In my script, I went for defining the TOC as a set of attributes on the target frame, so it seems to be possible to define it outside of the settings and it might be even easier to do so!

It might also be necessary to individually update the TOCs, which might be easier with a separate dialog.


Still the UI: the "Generate Table of Contents" menu entry is disabled by default.
I'm not sure if would be a good idea to start the Document Settings, since the user then would expect to use that menu entry for modifying the settings.

It might be worth exploring the idea to add tooltips to menu entries that are deactivated for non trivial reasons (we do not need to explain why you can't load an image on a text frame...).

This seems to to be possible with Qt 6 (not tested):

https://stackoverflow.com/questions/60484006/how-to-include-tooltips-for-menu-items-in-qt

(This is probably not needed if we get two menu entries, one for defining the current TOC, the other for generating all TOCs.)


On top of that, there are features that have been requested and are implemented in the script:

• Optionally, remove the end of lines from the title (per level or for the whole TOC; strip them or truncate after the first one).
• Remove the end of frame / end of column signs from the titles (yes, depending on how you define them, they will be part of the title)-
• It should be possible to create the paragraph styles from the TOC dialog (it's not necessary to  define them, just ask for the and create the style; maybe ask for a base style, since it might be painful to change it later; the script creates a set of pre-defined styles)

Finally, a few bugs I stumbled upon:

• In my screenshots you see that -- for reasons that are unknown to me -- some entries are repeated multiple times.
• In the settings dialog, the first (and default) entry is "[Default Paragraph Style]" and when hitting "Add" while it's selected, an empty entry is added to the list styles (i guess that the list should only contain real styles...)
• The frames are read in z-order: by default they should be read top down and left to right (of course in an official tool we should consider RTL...)
• For linked frames, the order on the page should be ignored (what comes first, shows up first: what counts is the position of the first frame of the chain on the given page).

Lot of text, sorry... Probably, just reading the README, the code and the other thread would have been shorter : - )

[MrB]

A lot of those things were already in the works.
I already committed a fix for the duplicate lines a couple of days ago
I've now added styles per heading.
I've never seen a TOC with different page number placement (ie start or end)
- Removed the [Default...] style
- rearranged doc setup ui
- Added remove line breaks code but not enabled yet.. it means joining separate paragraphs.. still to do.
- Removed the 1 from the first TOC naming

[a.l.e]

hi craig

hard to say something...

your announcement was "Scribus now has a style based TOC"...
and since scribus already had a TOC that the team seemed to like, seeing a style based TOC that basically replicates the old one (with almost all the drawbacks mirrored) gave me bad vibes.

sorry, if i misunderstood your goals.

it might be useful if, the next time, you could also announce the work you still plan to do.


i made a second quick test this morning and, while i see some improvements (the massive duplication is gone):

• the UI is... well... a polite german would call it "gewöhnungsbedürftig" (i guess it can be translated with "there is room for improvement")
• the order of the titles in the toc is not what most users will probably expect.
• chained frames are not correctly processed.
• frame and column breaks really need to be stripped from the toc entries (to be honest, the way those breaks work should be fixed instead; but that's probably not going to happen (soon)).
• number placement must probably be a per level setting (not because one would want to place left or right on each level, but because one might want to exclude the number from some levels! and a wild guess: left placement might be necessary for RTL text)
• "Default Paragraph Style" is now missing from the list of document styles for the TOC.
• the styles in the "Heading styles" are alphabetically sorted (they should be at least in insert order; but, at the end of the day, it should be possible to sort them manually; and the toc styles should follow; sane people will call their styles h1, h2, ... but you can't assume that!)
• it should be possible to add multiple times the same TOC style (and the "Paragraph Style" at the top should be disabled when the TOC is style based)
• in the styles list, the "Delete" button does not work correctly (it stay disabled when all styles have been removed)

no idea which of those points are already clear to you and where the feedback is useful.

i attach another simple test file and a screenshot of the UI (since most people won't be able to try this out...)

[a.l.e]

hi craig

after this afternoon's changes, the result looks better! thanks.
(sadly, there are also some regressions: i don't have any paragraph styles in the lists anymore...)

there is one thing i noticed: you made the removal of the frame and column breaks depend on the "remove new lines" option.

i really think that they should always be removed. there is no reason for wanting them to be copied over into a table of contents (ok, i just found out that it's slightly better to first add the new line and then the frame break: but you can't count on people to do that!)

in my eyes, removing the line ends is rather for cases situations like:

I.
First chapter

or

I. First chapter with a long title
and manual new line
because it's not so nice to have
full width titles

in the attached .odt file, you can see what i think this the right way to present the page breaks in scribus (well, of course, in scribus it will be a frame break).
i would really be important that in scribus too, for the frame break to also be a line break... but that's a different topic!

[MrB]

Ok a new version is now in SVN.
Reorganised the UI for main TOC
Created settings per style header, removed extra style list. Added single style list selector, and individual settings for remove line breaks, page numbering location
Removed the line break removal from the main TOC
COL/FRAMEBREAKs always removed, line breaks per settings (currently defaulted to off)
There's probably a few UI tweaks still to do.

[a.l.e]

hey!

it starts to work correctly!

i had to recreate my test file (somehow the old one did not work anymore... but it has been edited with multiple intermediate steps of the TOC... so it was somehow expected to happen).

the order of the titles is now what i would expect, but the one that is on the second page (which is in a chain starting on a first page) is showing up twice.

concerning the UI:

- i would move the options that are specific to the attributes in the lower half of the dialog and show one of both panes, depending on the selection.
  that is, if after having implemented all this, you still think that it's useful to keep around the attributes based TOC...

- when no style is selected in the list on the left, the properties on the right should be disabled.

- since now the order of the style is not relevant anymore, it might be not be strictly necessary to move them up and down.
  but i guess that most people will want to see them in a specific order, so it might be good to keep the feature.

finally, the last issue still open concerns the way to pick the target frame:

- on the one side, the user will not now the name and will have to close and open the dialog again to find it out.

- on the other side, a real document might have dozens of text frames and the user will have to scroll though a big list of items...

... i guess that the simple solution is to add a button "select current frame" next to the list of frames, and make it active if a frame is currently selected.

thanks for the fixes!

[MrB]

See how you go now with r26074.
Just the frame selection idea to solve in the future.

[a.l.e]

good morning craig,

the UI looks ok now.

the detection of the entries for the TOC is mostly good.
but, after having created a new page about mixing chained titled and free standing ones, i noticed that some titles on it were not collected.

on page three of the attached document, the two h2 in the chained text are missing from the TOC.
i guess, that it's because of the empty line before the titles.

finally, the reason why i've created page three:

if i recall correctly, in my python script, i keep the titles from the same page and chain together.
and i sort them by the order in the chain, not by the order on the page.
(not very hard to do: process all the next items if they are on the same page; ignore frames with precedent frame on the same page)
it's probably not something that happens very often, and the example on page three is a bit contrived, but if i think of a newspaper with four/five columns and multiple articles per page, then it's a layout that is somehow common.
it's true that newspapers don't have a TOC, but if, in the (near) future, we manage to also generate a PDF TOC, then the order is relevant.

up to you to decide if you think that this use case is legit and if it needs to be supported in this first version of the TOC.

thanks for your work!
a.l.e

[MrB]

Thanks Ale. I'll see what I can find.

[MrB]

Hi @a.l.e

Please check out r26077. Its all good now with your toc test 2 file.

Craig

[a.l.e]

yes, now the order seems to be good!

for me the question stays open, if it's better or not to mix the titles from a chain with other titles in between, but we can for sure wait and see if somebody brings a real world document where this matters.

[MrB]

A few more commits to fix another issue and code simplification in r26082. Your test still passes.