recommendations for citation style

[ajeanmahoney]

Section 3.5 states the following:

   We recommend using A) and strongly recommend consistent use of one style throughout.

As the RPC does not enforce citation style consistency, perhaps this could be rephrased as

   Consistent use of one style throughout is recommended, with style A) being preferred. 

Also this sentence should be moved from point 8 to point 7.

*ajeanmahoney edited this to add a link to the section in draft-rpc-rfc7322bis-00

[ajeanmahoney]

Also improve the example for style A)

Current:

       a.  As part of the transition to IPv6, NAT64 [RFC6146] and DNS64
           [RFC6147] technologies will be utilized by some access
           networks to provide IPv4 connectivity for IPv6-only nodes
           [RFC6144].

Perhaps:

       a.  This document defines a YANG data model [RFC7950] that can be used 
           to configure and manage Network Time Protocol version 4 [RFC5905]. 

[becarpenter]

Just an example where I think style B is the best choice, even in a document that mainly uses A:

In terms of Section 2.4 of [RFC3986], the "%" character preceding a zone identifier is acting as a delimiter, not as data.

Any other way of expressing this seems convoluted.

[cabo]

The problem really is that you need two different ways to do citations, as a suffix that is not part of the sentence and as a part of the sentence. Given that we don't have the latter in RFCXML, it is now common to abuse the suffix form as the form that is part of the sentence. Recommending to be consistent instead is meaningless, as the abuse is the only way to do that part of sentence construction.

[becarpenter]

@cabo, correct! In book6 I decided to support two styles of citation for exactly that reason. {{RFC1234}} works like kramdown and {{{RFC1234}}} suppresses the brackets. See book6 documentation.

[cabo]

Interesting! kramdown-rfc is using {{{ for something else, though.

[cabo]

BTW, here is a source that discusses the two forms, which they call "parenthetical in-text citations" versus "narrative in-text citations":

https://apastyle.apa.org/style-grammar-guidelines/citations/basic-principles/parenthetical-versus-narrative

Of course, we are not using APA style, but RFC numbers, I-D names, and mostly abbreviated author-date references, but the same considerations apply.

[cabo]

One of the problems of RFCXML is that an internal cross reference is always rendered prepared for narrative style, so the authors have to add parentheses for parenthetical style:

narrative: {{foo}} explains that bar is a baz.

parenthetical : bar is a bar ({{foo}}).

While the fact that we are misusing parenthetical style even for narrative citation references makes a different form necessary:

narrative: {{foo}} explains that bar is a baz. [bad style actually]

parenthetical: bar is a baz {{foo}}.

This is extremely easy to mix up.

Worse, external section references are again rendered for narrative style!

narrative: {{Section 5 of foo}} explains that bar is a baz.

parenthetical: bar is a baz ({{Section 5 of foo}}).

This inconsistency leads to constant errors while editing. We need to clean this up at some point, probably by adding two extra variants of <xref, one of which is always narrative style and the other one always parenthetical style (leaving <xref in place for backwards compatibility).

[becarpenter]

Yes. And:

narrative: {{foo}} explains that bar is a baz. [bad style actually]

could be "fixed" as:

RFC 9998 [RFC9998] explains that bar is a baz.

but since that is plain silly, we end up with:

The barbaz specification [RFC9998] explains that bar is a baz.