Section IDs/Anchors Naming Convention and Lookup-Table

[tajmone]

It would be really useful if the PML Reference Manual had a naming-convention for its chapters IDs, so that links targeting specific sections can rely on their anchors always being valid across updates to the RefMan.

We already have this with the specific nodes, which have anchors in the form node_<tag>, which works really great! But we lack something similar for the anchors of the sections that group similar nodes, like:

• Block Nodes
  • Fundamental Nodes
  • Common Nodes
  • etc.
• Inline Nodes
  • etc.

which all rely on auto-generated IDs/anchors, which makes it hard to provide links in projects READMEs, articles, etc.

I propose to adopt a simple convention that will remain unchanged even if the titles of these sections change slightly, i.e. by choosing as anchors the minimum terms that identify them:

section	anchor
Block Nodes	block-nodes
Fundamental Nodes	fundamental-nodes
Common Nodes	common-nodes
Inline Nodes	inline-nodes

Unlike the naming convention for specific nodes, which uses an underscore to separate node_ from the tag name, I sugget we use hyphens so it's clear that the anchor is about a category, or a generic section, and not the anchor of a specific node or syntax element.

Whatever the final choice, it would be great to have the naming convention explained in a dedicated document, and provide a lookup table so end-users can consult it for when they need to link back their articles/docs to the PML RefMan.

Obviously, something similar would be nice to have also with the other PML manuals, although the RefMan is probably the more urgent one.

E.g. in the Sublime PML repo, as well as the PML Playground, I'm struggling to keep my links up-to-date, since the auto-generated anchors keep changing number with each updated, which means I have to revisit every link in the project(s) docs.

[pml-lang]

But we lack something similar for the anchors of the sections that group similar nodes, like: ...

This is done already in the upcoming version 3.0.0.

If you look at function startChapter (currently at line 327) in source code file NodesReferenceManualCreator.java, you can see that there is an id input argument, which cannot be null (annotation @NotNull). This ensures that each chapter has a (non-auto-generated) id.

However, all ids use underscores, not hyphens (e.g. block_nodes).

it would be great to have the naming convention explained in a dedicated document

This would be a bit challenging to do if we want to stay DRY, because the ids would be defined in two different files, with the risk to get out of sync if ids are added, removed, or renamed. Needs further investigation if we decide to create such a dedicated document.

Obviously, something similar would be nice to have also with the other PML manuals

It's done already in the 'PMLC Commands Reference Manual' which is also auto-generated with the Java class CommandsReferenceManualCreator

I've just verified that each chapter in the 'PML User Manual' and 'Advanced PML Features' documents has an id. There were a few chapters without ids.

It's not done yet in the 'PML Changelog'.

[tajmone]

This would be a bit challenging to do if we want to stay DRY, because the ids would be defined in two different files, with the risk to get out of sync if ids are added, removed, or renamed.

The whole idea would be to offer guarantees about some core links to the Reference Manual, so that end users can rely on using them in their own documentation without having to constantly check and fix them with each PML update — if that was the case, most users would simply stop using anchored links.

Since we are talking of node tags and node categories here, the chances that these are going to be renamed or deleted should be rather thin, but then (even if they did) you could still keep the old anchors along with the new ones in order not to break third party links — e.g. let's say that node [list was to be renamed [ls, you could still keep the old #node_list anchor along with the new #node_ls anchor.

Obviously, new nodes would require new anchors being added to the document; but hopefully node names and tags are not going to change much in the future (guarantees for the former depend on the latter, obviously).

I personally think that it's worth the effort. My idea was to add to the repository (or to its Wiki) a README doc with a table listing all the anchors pointing to node groups or single nodes sections, which could also be used as a reference source for extracting the reference-style labels with the links to the PML RefMan sections, which would make it very easy for end users to copy and paste for their personal reuse.

Similarly, we could provide a PML snippet with constant definitions of such links, and so on — both the markdown and PML snippets could even be autogenerated.

These small details (providing guarantees to anchor references, and ready made snippets to use them) are the sort of courtesy toward end users than can make contributions easier and pain-free. I personally find it quite frustrating when dealing with articles and tutorials where all external links either point to long-gone-pages or anchors, forcing me to manually sift through lengthy documents to find the references I was looking for. Even more so when this is avoidable, e.g. with programming languages and syntaxes, where usually syntax elements names remain the same, so there is really no impediment to keep the anchors of their sections of reference the same across different editions of a reference manual.

Needs further investigation if we decide to create such a dedicated document.

As you said, the code that build the RefMan already expects and ID, so these IDs are in place already. The only difference is whether end users will need to manually extract them one by one (as I had to do in my various PML documents) or we provide a ready-made table and/or snippets they can use. Obviously, it's much easier to create such tables/snippets for maintainers than end users, especially since we could consider automating the process — partly, this can already be done via the JSON file generated by PMLC, but that only covers links to nodes, not node groups like "Fundamental Nodes", etc. Furthermore, some categories like "Text-Processing Nodes" are only found in the User Manual but have no counterpart in the Reference Manual.

For me snippets work best, since I can reuse them in every PML related document. So I'm starting already to create my AsciiDoc snippets containing attributes that resolve to PML RefMan links, with all the nodes and their sections.

I do understand that this might not seem a top-priority for the project right now, but the guarantees of fixed anchors naming should at least be taken into consideration, to prevent the proliferation of articles of PML with broken or semi-broken links.

[pml-lang]

The only difference is whether end users will need to manually extract them one by one (as I had to do in my various PML documents) or we provide a ready-made table and/or snippets they can use.

I am all in favor of providing additional documents to make life easier for users. However, we should always try to minimize maintenance burdens, stay DRY, and eliminate the risk of out-of-sync documents. This can best be achieved if:

• these documents are auto-generated
• their re-creation and online update is included in the automatic, one-click PML deployment process.

Of course, more initial work is required to auto-generate documents. But, sooner or later, time is saved, and maintenance is easier, less frustrating, and less error-prone.

this can already be done via the JSON file generated by PMLC

Yes. As you said already in another discussion, we should definitely enhance the JSON file to contain all PML metadata, including useful links to PML manuals. This will allow people to use any programming language to auto-generate additional documents , plugins, tools, etc. and they can easily be updated to reflect changes in new PML versions.

we could provide a PML snippet with constant definitions of such links, and so on — both the markdown and PML snippets could even be autogenerated.

I think I see what you mean, but it would be nice if you could provide a simple example.

[tajmone]

I think I see what you mean, but it would be nice if you could provide a simple example.

Here's an example of such a snippet (AsciiDoc) I use for PML related documentation:

https://github.com/tajmone/Sublime-PML/blob/main/docs-src/user-guide/_attributes-custom.adoc#L8

where currently the various links to attributes types break with each RefMan update due to autogenerated IDs changing.