W3C home > Mailing lists > Public > public-webauthn@w3.org > April 2018

[webauthn] cleanup: mark & structure biblio references consistently

From: =JeffH via GitHub <sysbot+gh@w3.org>
Date: Tue, 17 Apr 2018 18:17:57 +0000
To: public-webauthn@w3.org
Message-ID: <issues.opened-315175207-1523989076-sysbot+gh@w3.org>
equalsJeffH has just created a new issue for https://github.com/w3c/webauthn:

== cleanup: mark & structure biblio references consistently ==
Presently, we've (myself included) become somewhat sloppy with our biblio references and auto-link entries.  There's at least two broad categories:

The first, for example, is that we are not consistent in marking citations as **(non-)normative**, e.g.:
```
[...]
        <td>
            The ...
            as defined in Section 7 of [[RFC8152]] ...
[...]
    1. Convert the COSE_KEY ... (see Section 7 of [[!RFC8152]]) to CTAP1/U2F user public key ...
[...]
```
...note the inconsistency in using the normative exclamation mark citation signal **`!`** in the above cites of RFC8152.  There are similar inconsistencies with cites of other specs.

It appears that if a referenced spec is marked normative (at least once?) then it is placed in the "Normative" biblio section, thus cleaning up is not high priority, but probably something we ought to do.

The second cleanup aspect of this is we are creating cross-spec links that are syntactically  inconsistent. E.g.:
```
<pre class="anchors">
[...]
spec: TokenBinding; urlPrefix: https://tools.ietf.org/html/draft-ietf-tokbind-protocol#
    type: dfn
        text: Token Binding
        text: Token Binding ID; url: section-3.2                   [A]
[...]
spec: FIDO-CTAP; urlPrefix: https://fidoalliance.org/specs/fido-v2.0-ps-20170927/fido-client-to-authenticator-protocol-v2.0-ps-20170927.html
    type: dfn
        text: CTAP2 canonical CBOR encoding form; 
           url: ctap2-canonical-cbor-encoding-form                [B]
[...]
</pre> <!-- class=anchors -->

[...]
[[RFC8152]] [Section 7](https://tools.ietf.org/html/rfc8152#section-7)      [C]
...
(see [[RFC8152]]
[Section 13.1](https://tools.ietf.org/html/rfc8152#section-13.1))          [D]
[...]
```
[IIUC](https://en.wiktionary.org/wiki/IIUC),  we ought to be able to craft link anchors in the same fashion as [A] and [B], for the cases of [C] and [D] such that we are using a consistent cross-spec linking approach. 












Please view or discuss this issue at https://github.com/w3c/webauthn/issues/872 using your GitHub account
Received on Tuesday, 17 April 2018 18:18:02 UTC

This archive was generated by hypermail 2.4.0 : Tuesday, 5 July 2022 07:26:32 UTC