-
Notifications
You must be signed in to change notification settings - Fork 1
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Discrete Headings to Exclude Sections from TOC #74
Comments
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 |
The problem with .Code Block Title
[source=ruby]
--------------------
def some_method(x, y)
...
end
--------------------
.Table Title
|=================
| cell 1 | cell 2
|=================
... etc. ... The |
I would suggest to proceed like this:
I am a bit reluctant to implement 3 immediately, because:
|
I'll quickly reply, before handing over the PC to the shop for repair...
Definitely needed (like AsciiDoc
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
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).
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.
I'm not quite convinced about the
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. |
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)). |
Add an attribute to the
[title
node that allows excluding an heading from the TOC — somethingtoc_exclude = true
, where the default would befalse
, ortoc_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:In Asciidoctor a discrete heading is still generated as an heading tag (
<h1>
..<h6>
), but it's excluded from the TOC, and furthermore: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
The text was updated successfully, but these errors were encountered: