w3c / aria

Accessible Rich Internet Applications (WAI-ARIA)
https://w3c.github.io/aria/
Other
637 stars 123 forks source link

Add ReSpec aliasing clarity in README.me's "Editorial Documentation" section #2287

Open rahimabdi opened 1 month ago

rahimabdi commented 1 month ago

Describe the change

When linking to other specs using ReSpec syntax, there are scenarios where you need to provide alternative link text for the automatic external reference linking (xref).

For example, in the "Editorial Documentation" section, it's stated:

<section data-cite="webidl">
    <p>
        All ARIA attributes reflect in IDL as [=nullable type|nullable=]
        {{DOMString}} attributes.
    </p>
</section>

This means that nullable will be presented in spec text (not nullable type).

I'd like to add some clarity around 1) how to alias when referencing other specs and 2) what can/cannot be aliased per ReSpec syntax (see: https://respec.org/docs/#aliases-and-synonyms).

spectranaut commented 1 month ago

This is a great idea, and if you haven't seen it yet, I frequently use: https://respec.org/xref/