Chapter and Title IDs: How Do they Work?

[tajmone]

PML v2.0.0

@pml-lang, I can't work out how to define a chapter title ID.

The Reference Manual clearly mentions that the id attribute is available for both the [ch and its [title nodes, but so far I've only managed to see the the former being honoured in the resulting HTML code (on the <section> tag), whereas the latter doesn't produce anything (on the <h2>..<h5> tags).

Examples:

[doc [title My Doc Title]
[ch (id=intro) [title Introduction]
    Lorem ipsum dolor sit amet.
][ch [title (id=chap1) Chapter One]
    Lorem ipsum dolor sit amet.
][ch (id=sec2) [title (id=ch2) Chapter Two]
    Lorem ipsum dolor sit amet.
]]

result in the following HTML (excerpts):

<section id="intro" class="pml-chapter">
    <h2 class="pml-chapter-title">Introduction</h2>

<section id="ch__1" class="pml-chapter">
    <h2 class="pml-chapter-title">Chapter One</h2>

<section id="sec2" class="pml-chapter">
    <h2 class="pml-chapter-title">Chapter Two</h2>

So, when the [ch ID is omitted, one is auto-generated by PML for the <section id>, but in no case an ID is being added to the <h2> tags, and the custom ID from the PML source is being ignored.

I'm I doing something wrong?

And, in any case, what would be the purpose of having a separate ID for the section and the heading tags? Is to allow custom CSS/scripting on both the entire sections and the specific heading?

The documentation should clarify the difference between these two type of IDs, since they are closely related to the same node, and provide some practical usage examples.

[pml-lang]

the latter doesn't produce anything

This is actually a bug. I've discovered that there are a few nodes for which the HTML writer wrongly ignores the id attribute - among them title and subtitle. Will be fixed soon.

I'm I doing something wrong?

No, it's just a bug.

what would be the purpose of having a separate ID for the section and the heading tags?

An id has the following purposes:

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

In the case of a ch (chapter) node, an id is required because it is referenced from the table of contents. Hence, if an id is not explicitly provided, it is auto-generated by PML.

Normally you would never assign an id to a title node (unless you want to style it individually). And you would assign an id to a ch node only if you want to reference to it within the document, or you want to create an HTML anchor or you want to style it individually.

[tajmone]

This is actually a bug. I've discovered that there are a few nodes for which the HTML writer wrongly ignores the id attribute — among them title and subtitle. Will be fixed soon.

It would be a good idea to have some sort of reference document or page (e.g. a dedicated page on the Wiki of this repository) with all the known issues and bugs for the latest PML version.

The Wiki page seems the easier solution, since it can be edited in the browser, no Git setup required, and it also allows editing the page in various markups (markdown, AsciiDoc, etc.), so AsciiDoc can be used when complex tables are needed (cell/row spanning) and markdown for simpler pages.

Normally you would never assign an id to a title node (unless you want to style it individually). And you would assign an id to a ch node only if you want to reference to it within the document, or you want to create an HTML anchor or you want to style it individually.

This is something worth mentioning in the reference documentation, especially the fact that the id used in the TOC is the one from the [ch node. Right now, it almost seems as if they are alternative ways to give an ID to a chapter.

[pml-lang]

It would be a good idea to have some sort of reference document or page (e.g. a dedicated page on the Wiki of this repository) with all the known issues and bugs for the latest PML version.

We have already issue pages for the repositories (e.g. converter issues). What would be the purpose of an additional Wiki page?

This is something worth mentioning in the reference documentation

I have updated the doc for the id node.

This is actually a bug.

The bug has been fixed. Will be included in the next update.

[pml-lang]

This is actually a bug.

This bug is now fixed in version 2.1.0