Why Multiple Heading IDs?

[pml-lang]

Why Multiple Heading IDs?

[pml-lang]

In the upcoming PMLC version 3, the following rule is applied:

• All block nodes (including the doc node) have an optional id attribute.
• Inline nodes don't have an id attribute.

supporting an ID (anchor) in both the [ch and [title nodes seems redundant

I am not in favor of removing the id attribute for ch, title, or subtitle because:

• Ids can be used to style individual ch, title or subtitle nodes (as you mentioned already)
• In exceptional situations it might make sense to define an id for title or subtitle. For example if a ch, title or subtitle node takes a lot of vertical space, and one wants to precisely define the location of the node in the target document (HTML or other).
• Supporting ids for all nodes might be useful/required for tools that explore the PML AST. For example, a tool that extracts title (or subtitle) nodes might need an id for each node.
• Removing id from some block nodes would require to adjust the simple rule that all block nodes have an id attribute.

it should be made clear which is the idiomatic way of providing an ID to a section heading

I would say (but I'm not 100% sure) that the idiomatic way do define an id for a chapter is to define it in the ch node (not in the title or subtitle node). The reason is that an id for a vertical (block) section is typically defined in the parent node, where the node starts. But the idiomatic way should indeed be stated in the docs.

The [doc node doesn’t support an ID

As said already, the doc node now has an id attribute too, since version 3.
Besides "useful for providing xrefs to jump back to the top of the document", a doc id can also be useful in other situations. For example it could be used to identify different PML documents that are all embedded in a single HTML page.

it might make sense to provide separate semantics for XRef IDs and IDs intended for styling

Yes, maybe. But IMO we should first keep it simple and do this later only if there is enough evidence (i.e. practical use cases) to justify the need for two attributes.

the new custom templates

Sorry, I'm not sure what you mean by "the new custom templates", as custom templates are not supported and not specified yet. When custom templates are added in the future (a planned feature), all node attributes (including the id) will be available in the template definition, and it's up to the user how to use them. If we later decide to distinguish between two ids (one for referencing, and one for styling), then both will be available.

[tajmone]

Clarifications

To clarify my question about multiple IDs...

I'm aware that IDs are also useful in HTML documents for styling purposes, e.g. to allow targeting a specific element, e.g. a chapter subtitle that needs a different font-size because it's too long or short, or to customize the look-&-feel of a specific heading section container (e.g. its bg-color or some images, etc.) — these aspects are implicit in my previous reference to HTML-based GUI designing vs documents, since in the average document such granular CSS styles are fairly uncommon.

The reason I'm questioning these multiple IDs as anchors is because the equivalence between an ID being both an anchor for cross-reference linking as well as element styling is only true in HTML and XML based document, but might not be so in other formats.

Although I'm aware that currently PML is focusing on HTML output only, if the multi-format premise still holds true it might make sense to provide separate semantics for XRef IDs and IDs intended for styling, so that these will work as expected in all formats (regardless of how styles are applied to the format).

While it's reasonable that some attributes will be format specific (e.g. html_* attributes will probably be ignored by some future formats), which is common in many markup syntaxes, keeping an eye on appropriate attributes semantics for important things like cross-referencing and elements styling is indeed important for they are the key to documents being portable across multiple output formats.

In any case, I think it's important to amend the documentation in this respect, clarifying the differences in idiomatic usage of the id attribute on the [ch. [title and [subtitle nodes — i.e. instead of providing an identical description, mention which of these id should be used for section title cross-referencing, and that all of these can also be exploited for custom CSS styling (or JS targeting, etc.).

I've also like to know how the new custom templates will reflect on the above:

• How much control will be handed over to end users in terms of how custom templating can affect the way id attributes are represented in the final output?
• Is there ample room for adjustments there, including translating an id to the proper semantics of the output format to separate cross-referencing from element styling?
• Is the freedom in custom templates an argument in favor of separating the semantics for IDs as XRefs and elements targeting for styles? or does it actually nullify the problem by allowing end users to decide?

Sorry if I'm burdening with these fine-details questions, but having experienced how such details of lightweight markup syntaxes can affect working on documentation projects targeting multiple output formats these questions come spontaneous, and the answers can help me better understand the PML outlook on these questions, and where the syntax is heading in the future.

[tajmone]

Thanks for the explanation, then I can see that it's clearly a case of having to just clarify the documentation in this respect.

I actually ended up thinking about these considerations while editing the Sublime PML snippets for "new chapter", since I had to decide whether to place the id on [ch or [title, since PML 2 changed title from an attribute to a node, opening up the possibility of dual IDs.

All block nodes (including the doc node) have an optional id attribute.

Makes sense from the styling and JS targeting perspective.

• Supporting ids for all nodes might be useful/required for tools that explore the PML AST. For example, a tool that extracts title (or subtitle) nodes might need an id for each node.

Good point, I hadn't thought of this use-case.

I would say (but I'm not 100% sure) that the idiomatic way do define an id for a chapter is to define it in the ch node (not in the title or subtitle node). The reason is that an id for a vertical (block) section is typically defined in the parent node, where the node starts. But the idiomatic way should indeed be stated in the docs.

I'm not sure either since this seems an area where pure "HTML theory" might clash with practical use: I've noticed that often anchor-links end up jumping you to a point in the document just below the anchored-item, and in most browser you end up not reading the section title. Probably this is due to how CSS positioning affects the offset of the anchor. So, the parent node might be a safer option, but I'm not sure either.

What's important though is that the documentation clarifies the idiomatic way of providing section-IDs for cross-referencing, as mentioned above.

As said already, the doc node now has an id attribute too, since version 3.
Besides "useful for providing xrefs to jump back to the top of the document", a doc id can also be useful in other situations. For example it could be used to identify different PML documents that are all embedded in a single HTML page.

Also, it might allow fine-tuning CSS styles in documents which share a same stylesheet file (e.g. books chapters) since the [doc ID could then be used to customize things like the background color of each book Part or chapter, etc. In any case, if unused it does no harm.

the new custom templates

Sorry, I'm not sure what you mean by "the new custom templates", as custom templates are not supported and not specified yet. When custom templates are added in the future (a planned feature), all node attributes (including the id) will be available in the template definition, and it's up to the user how to use them. If we later decide to distinguish between two ids (one for referencing, and one for styling), then both will be available.

Yes, the question was about such future potentials. Asciidoctor (Ruby) has added support for various templating engines in the course of time — ERB (deprecated), Haml and Slim — but all of them allowed conditional manipulation of the exposed value via embedded scripts, so end-users could actually transform the input data before applying it to the format-specific output template. This would allow, among other things, to handle format-specific problems regarding id as a link-target vs a styling-reference.

[pml-lang]

What's important though is that the documentation clarifies the idiomatic way of providing section-IDs for cross-referencing

I've added the following note to the chapter's description:
"The idiomatic way of identifying a chapter for cross-referencing is to assign an 'id' to the chapter node (and not to the chapter's title or subtitle node)."