Discrete Headings to Exclude Sections from TOC

[tajmone]

Add an attribute to the [title node that allows excluding an heading from the TOC — something toc_exclude = true, where the default would be false, or toc_include if that's more inline with the way attributes are defined.

This is inspired by AsciiDoc's discrete headings, which can be enabled via the discrete attribute on any heading:

[discrete]
== Discrete Heading

In Asciidoctor a discrete heading is still generated as an heading tag (<h1>..<h6>), but it's excluded from the TOC, and furthermore:

A discrete heading is declared and styled in a manner similar to that of a section title, but:

• it’s not part of the section hierarchy,
• it can be nested in other blocks,
• it cannot have any child blocks,
• it’s not included in the table of contents.

The above points are important in Asciidoctor, because with real headings you can't skip levels (e.g. jump from <h1> to <h3>) or use headings inside blocks (e.g. a quotation block, etc.).

As for PML, I think that the goal should be to simply exclude these headings from the TOC generation and computation process (i.e. as if the discrete headings were simply not there).

It might be worth considering whether any child headings of a discrete heading should be computed or not in the TOC. E.g. the problem is that by excluding a Level-2 heading via discrete, if that section has sub-sections then all the sub-headings would need to be manually set as discrete too, otherwise there would be a level-gap in the final TOC, where the discrete heading results in a direct jump from Level-1 to Level-3 because it's not being considered in the TOC generation. Unless the TOC ends up considering the next [ch node as being Level-2 (since in PML chapter nodes don't contain level info, but the level is deduced from their nesting level), which probably doesn't make sense.

So, probably it makes more sense to consider any children of a discrete heading as being discrete too, otherwise the computation of nested TOC levels gets all out of synch.

In any case, this needs to be considered because PML differs from other lightweight markups in this respect, where AsciiDoc and Markdown headings contain in themselves their heading-level info (=, ==) whereas in PML is the actual nesting in the final document tree that determines their level.

References

• AsciiDoc Language Documentation » Discrete Headings

[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)).