-
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
Why Multiple Heading IDs? #80
Comments
ClarificationsTo 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. In any case, I think it's important to amend the documentation in this respect, clarifying the differences in idiomatic usage of the I've also like to know how the new custom templates will reflect on the above:
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. |
In the upcoming PMLC version 3, the following rule is applied:
I am not in favor of removing the
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
As said already, the
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.
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 |
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
Makes sense from the styling and JS targeting perspective.
Good point, I hadn't thought of this use-case.
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.
Also, it might allow fine-tuning CSS styles in documents which share a same stylesheet file (e.g. books chapters) since the
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 |
I've added the following note to the chapter's description: |
@pml-lang, I'm a bit confused about the fact that the
[ch
[title
and[subtitle
nodes all support theid
attribute. For all these nodes, the documentation is identical: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:
produces this HTML code:
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 theid
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 theid
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:
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.The text was updated successfully, but these errors were encountered: