w3c / aria

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

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

Open rahimabdi opened 4 months ago

rahimabdi commented 4 months 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 4 months ago

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