Subject: [rfc-i] Internet-Draft citations (and citations in general)

From: Julian Reschke <[email-masked]>
Date: Tue, 8 Oct 2019 21:51:27 +0200

So, I was looking into what RFC 7322 and -bis say about citing internet
drafts, and whether I need to align rfc2629.xslt.

<https://tools.ietf.org/html/rfc7322#section-4.8.6.4>:

> 4.8.6.4.  Referencing Internet-Drafts
>
>    References to Internet-Drafts may only appear as informative
>    references.  Given that several revisions of an I-D may be produced
>    in a short time frame, references must include the posting date
>    (month and year), the full Internet-Draft file name (including the
>    version number), and the phrase "Work in Progress".  Authors may
>    reference multiple versions of an I-D.  If the referenced I-D was
>    also later published as an RFC, then that RFC must also be listed.
>
>       [SYMBOLIC-TAG]  Last name, First initial., Ed. (if applicable)
>                       and First initial. Last name, Ed. (if
>                       applicable), "I-D Title", Work in Progress,
>                       draft-string-NN, Month Year.
>
>      Example:
>
>       [RFC-STYLE] Flanagan, H. and S. Ginoza, "RFC Style Guide",
>                   Work in Progress, draft-flanagan-style-01,
>                   June 2013.

RFC 7322 was published in September 2014, but xml2rfcv2 did not update,
and continued to use:

 >       [RFC-STYLE] Flanagan, H. and S. Ginoza, "RFC Style Guide",
 >                   draft-flanagan-style-01 (work in progress),
 >                   June 2013.

So the only change fro "previous" was that "Work in Progress" moved in
front of the draft name, and lost the parentheses.

rfc2629.xslt implemented the new format, but only when in "RFC" mode, in
order to avoid differences from xml2rfc's TXT output.

So here is an important point: the style guide changed, but the
canonical formatter did not. I *believe* the RFC Production Center
worked around that by manually editing the nroff output. In any case,
style guide, vocabulary definition and implementations need to be
co-ordinated, in particular now, as the formatter's output won't get any
post-processing anymore.

Another point I'd like to make is that formatting references to Internet
Drafts needs special cases in formatters:

- the name from the seriesInfo is used to trigger formatting, but not
actually displayed

- a special note ("work in progress") is inserted

The current -bis draft has in
<https://tools.ietf.org/html/draft-flanagan-7322bis-04#section-4.8.6.3>:

> 4.8.6.3.  Referencing Internet-Drafts
>
>    References to Internet Drafts may only appear as informative
>    references.  Given that several revisions of an I-D may be produced
>    in a short time frame, references must include the posting date
>    (month and year), the full Internet-Draft file name (including the
>    version number), and the phrase "Internet Draft".  Authors may
>    reference multiple versions of an I-D.  If the referenced I-D was
>    also later published as an RFC, then that RFC must also be listed.
>
>    [SYMBOLIC-TAG] Last name, First initial., Ed. (if applicable) and
>    First initial.  Last name, Ed. (if applicable), "I-D Title", Work in
>    Progress, Internet-Draft, draft-string-NN, Day Month Year.
>
>    Example:
>
>    [RFC-STYLE] Flanagan, H. and S.  Ginoza, "RFC Style Guide", Work in
>    Progress, Internet-Draft, draft-flanagan-style-04, 27 September 2019.

(let's ignore the date format change; we already have a separate thread
for that)

So this inserts "Internet-Draft", which is in the name attribute of
seriesInfo. Good, as this make this less of a special case. *However*,
for all other types of seriesInfo, there is no comma between name and value.

So can *please* change this to:

>    [RFC-STYLE] Flanagan, H. and S.  Ginoza, "RFC Style Guide", Work in
>    Progress, Internet-Draft draft-flanagan-style-04, 27 September 2019.

instead?

Let's now consider citations in general. The RFC Style guide isn't that
helpful here, as it gives specific examples, not generic rules. For
instance, see
<https://tools.ietf.org/html/draft-flanagan-7322bis-04#section-4.8.6.1>:

> 4.8.6.1.  Referencing RFCs
>
>    The following format is required for referencing RFCs.  The Stream
>    abbreviation should be used; when no stream is available, as with
>    legacy RFCs, this may be left blank.
>
>    Note the ordering for multiple authors: the format of the name of the
>    last author listed is different than that of all previous authors in
>    the list.
>
>    For one author or editor:
>
>    [RFCXXXX] Last name, First initial., Ed. (if applicable), "RFC
>    Title", Stream, Sub-series number (if applicable), RFC number, RFC
>    DOI, Date of publication, <https://www.rfc-editor.org/info/rfc# >
>    [1].
>
>    Example:
>
>    [RFC3080] Rose, M., "The Blocks Extensible Exchange Protocol Core,"
>    IETF, RFC 3080, DOI 10.17487/RFC3080, March 2001, <https://www.rfc-
>    editor.org/info/rfc3080 > [2].
>
>    [RFC8157] Leymann, N., Heidemann, C., Zhang, M., Sarikaya, B., and M.
>    Cullen, "Huawei's GRE Tunnel Bonding Protocol", independent, RFC
>    8157, DOI 10.17487/RFC8157, May 2017, <https://www.rfc-
>    editor.org/info/rfc8157 > [3].

Compared to other examples (internet drafts, other SDOs), this adds
"stream". Is this something that could also appear for, let's say, W3C
documents? Who knows. So it would be great if we could have a *generic*
concept of a citation, model the vocabulary around that, and then say
how this generic format will be used for the specific IETF-type
references. See related issues
<https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/79>,
<https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/30>,
<https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/28>,
<https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/15>,
<https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/78>.

Best regards, Julian

_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest