Increase consistency through ReSpec auto-links

Hi,

As some of you may have seen, I spent some time in the past few weeks
upgrading webrtc-pc (and mediacapture-share to a lesser extent) to make
more use of ReSpec auto-linking features, where WebIDL terms are linked
using
* {{Foo}} (for interface, dictionary or enum named Foo)
* {{Foo/bar}} (e.g. for an an attribute bar of an interface Foo)
* [= my great concept =] (for a term defined as <dfn>my great concept</dfn>)
* [= my great concept | this great concept =] (for a term defined as
<dfn>my great concept</dfn> but that needs to appear in the text as
"this great concept")

These auto-links work for terms defined directly in the spec, as well as
for specs whose definitions are imported, either via a data-cite
attribute in the parent section, or imported for the whole spec using
respecConfig.xref (see
https://github.com/w3c/webrtc-pc/blob/master/webrtc.js#L152)

See e.g. the changes in https://github.com/w3c/webrtc-pc/pull/2417 and
https://github.com/w3c/mediacapture-screen-share/pull/124

The motivation to using this approach is that it enables ReSpec to
automatically check the validity of the said links and report as errors
links that are not valid (either because of typos, terms that are no
longer defined, etc). I had raised a few issues as a result of doing
that transformation as ReSpec pointed out errors while I was doing so:
 https://github.com/w3c/webrtc-pc/issues/2422
 https://github.com/w3c/webrtc-pc/issues/2421
 https://github.com/w3c/webrtc-pc/issues/2415
 https://github.com/w3c/mediacapture-screen-share/issues/131

Think of it as a linker in a build chain that breaks when it can't find
the proper references in the linked objects.

I believe we would benefit from being as systematic as we can in doing so.

The thumbrules we should be aiming for is:
* never using <a> (except for auto-link to sections, e.g. <a
href="#mysection"></a>)
* never using <code> except for JS primitives (e.g. <code>null</code>)
and instead, use the proper auto-link shortcut provided by ReSpec.

There are still a number of cases where we can't do that, in particular
because the system on which ReSpec relies to detect definitions is
messed up when it comes to gUM and WebRTC stats definitions, both of
which should be fixed the next time we update the TR versions of this
spec (long story).

In particular, the WebRTC spec has a set of <code class="XXX"> for cases
that ought to be auto links, but can't at the moment. At some point, I
think we may benefit from enforcing this policy in our CI.

Hopefully we can also progressively adopt this approach with other
ReSpec-based specs over time; the same applies roughly in the same way
for bikeshed specs.

Dom

Received on Friday, 10 January 2020 14:54:32 UTC