Why Multiple Heading IDs?

[tajmone]

@pml-lang, I'm a bit confused about the fact that the [ch [title and [subtitle nodes all support the id attribute. For all these nodes, the documentation is identical:

Description: A unique identifier for the node.

An id can be used to:

• identify a node so that an internal link can be done with an 'xref' (cross reference) node.
• identify a node so that it can be styled individually with CSS
• create an HTML anchor so that it can be accessed with the # (hash) sign (e.g. writing id=foo will enable you to have an HTML link ending with #foo.

Usually a heading has only one ID in documents, and supporting an ID (anchor) in both the [ch and [title nodes seems redundant and confusion prone, especially since you can't have a titleless chapter heading.

The [doc node doesn't support an ID because obviously it doesn't need one (at least not semantically), since the doc title is the top of the page, although one might argue that assigning an ID to the [doc [title node could be useful for providing xrefs to jump back to the top of the document.

My argument is that chapter titles only need one.

The following PML source:

    [ch (id=chapter_id) [title (id=title_id) Chapter With Double-ID]

produces this HTML code:

<section id="chapter_id" class="pml-chapter">
  <h2 id="title_id" class="pml-chapter-title">Chapter With Double-ID</h2>
</section>

What's the point in having double anchors here? They will both jump to the same document position, but they can confuse users as to which one is the idiomatic way of assigning an anchor for cross references — especially if you consider that each ID must be unique.

In collaborative editing, contributors need to know where to place the ID/anchor, should it go on the [ch or [title node? Ending up with large documents where the heading IDs are sometimes on the [ch node and other time on [title leads to messy documents, especially if editors rely on editor scripts that target attributes by nodes (e.g. to enforce naming conventions), since these scripts might miss any IDs on the other node.

Since the [doc node doesn't support an ID directly, but only via the [title subnode, it seems to me that the most reasonable approach would be to drop the id attribute from [ch and only keep it on the [title node, since the latter is shared between both [doc and [ch.

Even more confusing is the fact that the [subtitle node supports the id attribute too — meaning that a section heading can have up to three IDs! What's the use of placing an ID/anchor on a subtitle? The position of a title and its subtitle within a document are basically one and the same (nothing else should be placed between them) and since you can't have a subtitle without a title, the [subtitle node is merely an extension of the [title node, practically speaking, just as [title is an extension of [doc or [ch, since [title never stands on its own but always leans on a section heading (be it the main doc title or one of its sub-sections headings).

I think these questions should be addressed before v3.0 is out:

• If there are good reasons why headings support multiple IDs (up to three per heading, if you include subtitles) then these reasons need to be documented, and it should be made clear which is the idiomatic way of providing an ID to a section heading.
• If my arguments for deprecating the id attribute on [ch and [subtitle are valid, then they should be dropped before PML 3.0 is out — otherwise we'll be seeing another MAJOR release cycle with breaking changes within the same MAJOR release (unacceptable under Semantic Versioning).

So, am I missing out something here about the reasons for supporting multiple IDs in section headings?

I know that technically speaking this is all valid HTML (you can place anchors wherever you want, including <strong> and <em>), but from a documentation writers' perspective it doesn't make much sense (whereas it might for HTML based GUI designers). Since PML is all about documents, IMO we should stick to writers semantics and best practices, so that PML idiomacy is unambiguous to its users.

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

[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]

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