Parameter ID vs Anchor ID

[tajmone]

Elsewhere, you clarified that constant parameters IDs must be named according to the [a-zA-Z][a-zA-Z0-9_]* pattern.

But what about attributes IDs which will generated HTML anchors? Do they also follow the same pattern, or do they support the XML naming convention?

Asciidoctor, for example, follows the [a-zA-Z][a-zA-Z0-9_]* pattern for naming attributes, but supports XML naming for anchors, following the XML 1.0 specs:

NameStartChar  ::=  ":" | [A-Z] | "_" | [a-z] | [#xC0-#xD6] | [#xD8-#xF6]
                        | [#xF8-#x2FF]    | [#x370-#x37D]   | [#x37F-#x1FFF]
                        | [#x200C-#x200D] | [#x2070-#x218F] | [#x2C00-#x2FEF]
                        | [#x3001-#xD7FF] | [#xF900-#xFDCF] | [#xFDF0-#xFFFD]
                        | [#x10000-#xEFFFF]
NameChar       ::=  NameStartChar | "-" | "." | [0-9] | #xB7 | [#x0300-#x036F] | [#x203F-#x2040]
Name           ::=  NameStartChar (NameChar)*

I believe that the XML naming convention for anchors provides better i18n support, since it covers special letters (accents, diacritics, etc.) and maybe some non-Latin alphabets too (I'm not sure, I haven't check all those chars ranges).

Obviously, the PML spec could simply restrict anchor names to the [a-zA-Z][a-zA-Z0-9_]* pattern, or operate some transformations (like various markdown tools already do).

Whichever the case, it's worth mentioning it in the PML Reference Manual, for clarity's sake — also, editor plug-ins developers need this info to implement the PML ID type for attributes values. Currently, the CLI help mentions these ID attributes to be of "string" type, e.g.:

2.
Id             : id
Title          : Node Identifier
Type           : string or null
Description    : A unique identifier for the node. The id can be used for
                 cross-referencing, or for local links in the resulting HTML code.
Required       : no
Default value  : null
Examples       : id = basic_concept

where "string" is a rather generic definition, unlike other specific types (e.g. "date"). It might make sense to document both the parameter and anchor IDs as their own types (e.g. "id" and "anchor_id"), provide their pattern definitions (or patterns, if they differ).

[pml-lang]

what about attributes IDs

Whenever the PML reference manual states "string" (or "string or null") it really means that any string (e.g. any sequence of Unicode characters) is allowed.

This must of course be changed for attribute ID. The value should be restricted and compatibility with HTML anchors must be ensured.

the PML spec could simply restrict anchor names to the [a-zA-Z][a-zA-Z0-9_]* pattern

This would be a good start. We would have a single, simple rule for attribute IDs and parameter IDs. The rule(s) might be relaxed in the future.

it's worth mentioning it in the PML Reference Manual

I have appended the following text to the 'Description' field for IDs:
An identifier must start with a letter and can be followed by any number of letters, digits, and underscores. Note for programmers: The regex of an identifier is: [a-zA-Z][a-zA-Z0-9_]*. Identifiers are case-sensitive. The following identifiers are all different: name, Name, and NAME.

The internal check of the value by the converter application remains to be done.

[tajmone]

Any Char is Accepted in IDs

More tests reveal than any character can be used in IDs. E.g.:

[ch title = "Chunk 1: Bad ID" id=%12id ]

compiles to HTML without error, leading to:

<section id="%12id" class="pml-chapter">
    <h2 class="pml-chapter-title">Chunk 1: Bad ID</h2>
</section>

So it seems that currently the ID rules are rather relaxed.

Documenting Features Status and Their Guarantees?

I think that for the sake of developing third party tools, like editor support for PML syntax, it would be important to include in the PML Reference Manual some developers notes regarding this king of technical details, indicating whether a specific feature is guaranteed to be stable in time, or it's still subject to changes, etc., so that developers can decide the correct course of actions (e.g. how much energy to invest in specific features, or whether to postpone their implementation, and if they might need to be tested for in a test-suite, in order to catch changing behaviour between pmlc updates).

I know that PML is a WIP project, and that it will inevitably be subject to changes (for the good), including backward breaking changes, since the syntax will take its natural course as users feedback pours in, and that it might take a couple of years before we reach a point in which the core features are set in stone and development will focus on adding new features without breaking backward compatibility.

But still ... it's also important that developers can feel free to invest energy in creating third party tools, without fearing that these will become obsolete and unusable in time; and that similar efforts might find guidance in the official documentation — simple indications regarding the stability or temporary nature of a feature could make a huge difference in this respect.

Third party tools are important for building a rich echo-system around any application, which ultimately is a strong incentive for adopting any new technology.

In my case, I've been over-implementing an editor feature which doesn't actually match the current pmlc behaviour: marking in the editor a malformed ID as invalid is a very useful feature, but in this case it mismatched the actual behaviour, due to discrepancies between documentation on actual implementation. An admonition note in the Ref Man could have, for example, stated what the ultimate goal for IDs naming convention will be (e.g. that eventually it will support the same standard as XML/HTML, as mentioned above), and what the current reality is.

This kind of information could guide developers in their choices — e.g. one might decide to implement straight away the XML naming convention, if that was the ultimate PML goal, instead of implementing the simpler pattern today and update it in the future.

[tajmone]

BUG: Spaces Accepted Too

This is definitely a bug! PMLC accets:

[ch title = "ID Test" id="66 xx" ]

and generates:

<section id="66 xx" class="pml-chapter">

which is of course not usable in targeting anchor ID via links, since spaces are not allowed.

[pml-lang]

pmlc doesn't actually complaint if an identifier starts with a digit

any character can be used in IDs

Spaces Accepted Too

Yes, the current parser accepts any string (even if it includes spaces), as stated in my previous comment:

Whenever the PML reference manual states "string" (or "string or null") it really means that any string (e.g. any sequence of Unicode characters) is allowed.

I updated the documentation, but didn't yet enforce the rule in the parser, as said in my previous comment:

The internal check of the value by the converter application remains to be done.

The [a-zA-Z][a-zA-Z0-9_]* rule will be enforced in the new parser I'm currently working on (future PML version 2.0).

In Sublime PML, I'm currently assuming that a valid ID must abide to the above mentioned RegEx pattern [a-zA-Z][a-zA-Z0-9_]*
and that anything else is an error (and should be highlighted as invalid)

Yes, that's the correct way to do it.

include in the PML Reference Manual some developers notes

I agree. The the docs must be improved. Will be done after the new parser is integrated.

[pml-lang]

I've opened an issue in the converter repo.

[tajmone]

Yes, the current parser accepts any string (even if it includes spaces), as stated in my previous comment:

sorry, I had missed out that comment.

The [a-zA-Z][a-zA-Z0-9_]* rule will be enforced in the new parser I'm currently working on (future PML version 2.0).

Then I'll leave Sublime PML as it is, since it will inform users about wrong patterns that will soon lead to an error.

This is a good example of a feature that should be documented as "coming soon", which then developers should enforce right away in their PML-related tools, since it's not blocking anything if done prematurely, but will be compliance-ready when the feature is finally implemented in a next PML version.