Discrete Headings to Exclude Sections from TOC

[pml-lang]

Discrete Headings to Exclude Sections from TOC

[pml-lang]

There is already the header node, introduced in version 2.0.0 2021-09-03. This node is used to insert titles that don't appear in the TOC.

Did you consider this, or do you think there is still a need for toc_exclude = true?

[tajmone]

Did you consider this, or do you think there is still a need for toc_exclude = true?

The problem with [header is that it applies to different elements, not section headings specifically, and there's no way to control the heading level. This node seems to have an equivalent function to AsciiDoc's titles (via .):

.Code Block Title
[source=ruby]
--------------------
def some_method(x, y)
  ...
end
--------------------

.Table Title
|=================
| cell 1 | cell 2
|=================

... etc. ...

The toc_exclude attribute, on the other hand, would ensure that a natural section heading (<h1> etc.) will be rendered as usual in the document, according to sections structure, but excluded from the generated TOC. So I think it's still needed.

[pml-lang]

I would suggest to proceed like this:

1. Add TOC_max_chapter_level as a config parameter. Allows to define which chapter levels are included/excluded in the TOC. Default value is null, which means that all levels are included. For example, setting the value to 4 means that all chapters with level 5 or higher are not shown in the TOC. This parameter is already on my to-do list.

2. Add attribute level to node header. Allowed values: 2 to 6. Default value: the level of the parent chapter plus 1. Use specific CSS classes for each level (e.g. header-level-2, header-level-3, etc.). Maybe we should also use h2 .. h6 tags instead of div tags.

3. If, after implementing 1 and 2, there is still a need for toc_exclude = true, add this attribute too.

I am a bit reluctant to implement 3 immediately, because:

• It adds some complexity, as described in your initial message. Child chapters of an excluded chapter would all need to be excluded too in the TOC. But what if a child chapter of an excluded chapter explicitly specifies toc_exclude = false?

• If 1 and 2 are implemented, 3 is (probably) not needed anymore.

• I don't really like the idea of a TOC that hides some chapters.

[tajmone]

I'll quickly reply, before handing over the PC to the shop for repair...

• Add TOC_max_chapter_level as a config parameter.

Definitely needed (like AsciiDoc toc_level).

• Add attribute level to node header. Allowed values: 2 to 6. Default value: the level of the parent chapter plus 1. Use specific CSS classes for each level (e.g. header-level-2, header-level-3, etc.).

If I've understood correctly, you want to use a class to emulate the styles of default headings? But this would only work when there's a stylesheet that defines the styles for h2..h6 along with .header-level-2...header-level-6.

Maybe we should also use h2 .. h6 tags instead of div tags.

that would be risky, for the user might be trying to enforce a heading level that is out of synch with the document structure (not to mention that include directives work best with free heading nodes where PML determines their level according to their nesting in the final document).

But what if a child chapter of an excluded chapter explicitly specifies toc_exclude = false?

Good question. I guess you'd have to make an opinionated choice on this. Either you ignore it because it's the child of a TOC-excluded node sub-tree, putting the document integrity first; or you make an exception for this specific node, assuming that the end user knows what he/she's doing.

• If 1 and 2 are implemented, 3 is (probably) not needed anymore.

I'm not quite convinced about the level attribute, but I'll need to think it over when I'm not in a rush.

• I don't really like the idea of a TOC that hides some chapters.

Still, it's a standard feature for editorial-level markup languages (DocBook, AsciiDoc, and others). Even pandoc markdown (which generates TOCs) offers a special class to achieve this.

A practical example, when you include a license like Artistic License 2.0, as an Appendix. The Apache license has lot's of sections, sub-sections, etc., but being a legalese contract, you usually only want to keep the main title. Without an attribute to selectively exclude sections, you end up with a huge TOC (where the Apache entries are more than the actual document), or you reduce the TOC depth, sacrificing navigation of the main document.

[pml-lang]

it's a standard feature for editorial-level markup languages (DocBook, AsciiDoc, and others). Even pandoc markdown (which generates TOCs) offers a special class to achieve this.

If it's so well supported in those languages, it means there is a real need for it. So we should consider adding the feature in PML too (even after adding (1) and (2), because they are not a replacement for (3)).