Re: [Rswg] A citation as a substantive [was draft-irse-xml2rfc-changes...]

[John C Klensin <[e-mail]>]

Response to Julian, in probably more detail than he wished for,
inline but:

(a) Question for the co-chairs: How deeply into this swamp do
you consider it worthwhile to descend at this point?  Should we
pose the issues and wait for a recommendation for the RPC and/or
RSCE as suggested/explained below or continue to have at it?

(b) Note to John Levine: Discussed in more detail inline but, in
looking at draft-irse-draft-irse-xml2rfcv3-implemented-03 (and
its RFC Editor Function predecessor), it appears that a least
some of the new/added attributes ("section" for <xref> in this
case) lack definitions of what is permitted in their values.
Clearly some definition has been implemented so, as your
document continues to evolve, it would probably be worth
tracking those attributes down and completing the definitions.

Now for the more substantive issues...

--On Wednesday, September 28, 2022 17:52 +0200 Julian Reschke
<[e-mail]> wrote:

> Am 28.09.2022 um 17:21 schrieb John C Klensin:
>> 
>> 
>> --On Wednesday, September 28, 2022 08:35 -0500 Jean Mahoney
>> <[e-mail]> wrote:
>> 
>>>> I don't object to guidance as to better phrasing at all,
>>>> but imposing such as a requirement seems a bit silly when
>>>> the meaning is clear.
>>> 
>>> [JM]  The current guidance for in-text citations can be
>>> found in the RECOMMENDED section of the Web Portion of the
>>> Style Guide. Both styles are okay:
>>> https://www.rfc-editor.org/styleguide/part2/#citation_usage
>> 
>> Jean,
>> 
>> My apologies to you, and everyone else, for mentioning that
>> issue in my note because it seems to have distracted from the
>> more important question, one that I do not believe is
>> addressed in the Style Guide.  That is whether, if one needs
>> to cite, e.g. (and simplifying a bit from Toerless's
>> example), two different sections of the same document,
>> whether you have guidance about whether to use some variation
>> on
>> 
>> 	The background for the current Nomcom selection criteria
>> 	[RFC8989] Section 1,...
>> 
>> and
>> 
>> 	The specific, experimental Nomcom criteria [RFC8989]
>> 	Section 4...
>> 
>> or whether to embed the section number in the references so
>> one would have simply "[RFC8989a]" and "[RFC8989b]" in the
>> running text.  That second form is probably more friendly to
>> both Toerless's concerns about very complex within-document
>> citations and to HTML formats, where an author could actually
>> specify a link of
>> <https://www.rfc-editor.org/info/rfc8989#Section1> if that
>> anchor were supported in the text (it is not for RFCs, but
>> could easily be available for other types of documents).
>> 
>> 
>> As far as I can tell, the current RFCXML vocabulary is not
>> particularly friendly to either.  For the first form and itsy
>> 	"[RFC8989 Section 1]" to "[RFC8989] Section 1"
>> because the former would make it more clear that "Section 1"
>> is part of the citation and not running text.   However, I
>> cannot write
>>     <xref target="RFC8959" citationDetail="Section 1"/>
>> or the equivalent, which I presume would be needed to produce
>> it.
> 
> You could write
> 
>    <xref target="RFC8959" section="1"/>
> 
> This will produce
> 
>    Section 1 of [RFC8959]
> 
> with both parts nicely hyperlinked in formats that support
> linking.
> 
>  > ...

Noting that a "section" attribute does not appear in RFC 7991, I
obviously have not been tracking the vocabulary closely enough,
instead prioritizing actually getting documents written and,
apparently, reading this list, for which I guess I should
apologize.  However:

While the above works for "an RFC or Internet-Draft in the v3
format", it is an error for some other sort of document unless
"relative" is also specified (Section 2.66.4 of
[id.draft-iab-rfc7991bis-04] and Section 2.66.3 of
[id.draft-iab-rfc7991bis-04])

The above illustrates several of the points I (and I think
Toerless) were trying to ask Jean about.

(1) For readability, the brackets should really be outside the
entire citation, because "Section 1" is actually part of it.
For the more complicated case I show above, the parentheses are
needed to prevent things from becoming hopelessly confused.
Maybe the two citations should be parenthesized separately, to
be consistent with having references to two separate RFCs (e.g.,
"... [RFC7991][id.draft-iab-rfc7991bis-04]" or "[3][4]".

(2) Even Section 3.66.5 of the "As Implemented" spec
[id.draft-irse-draft-irse-xml2rfcv3-implemented-03] does not
specify the potential values of the "section" attribute, so I
can't figure out, without either experimenting or appeal to
higher authority, whether I could write (for a different
reference)
  <xref target="foo" section="Appendix D, part 2"/>  
your example with section="1"' hints that might not work.

(3) Item (2) above also illustrates the citation bracketing
problem.  While it would be perfectly sensible to write either 
	The "As implemented" spec [Section 3.66.5 of
	id.draft-irse-draft-irse-xml2rfcv3-implemented-03]
or
  The "As implemented" spec
[id.draft-irse-draft-irse-xml2rfcv3-implemented-03a]
the sentence in (2) strikes me as awkward.  YMMD and that may be
partially a plain text problem.  But having it as 

	Even the "As Implemented" spec Section 3.66.5
	[id.draft-irse-draft-irse-xml2rfcv3-implemented-03]

which is presumably what would be generated using the section
attribute, is, IMO, even more awkward and, I believe that, in
the absence of a comma after "spec" also grammatically
incorrect.  So the comma belongs there in plain text but not in
HTML where the whole business is a citation anchor and link?  I
am not optimistic about getting the right in the output
generation process.

(4) I also have no idea what the sentence in (2) would look like
in an HTMLized process.  We would either end up with the
"Section 3.66.5" in plaintext (not a link) and a link into the
references for the citation anchor or, with some clever
heuristics and some lookahead, a link into the actual document
(https://www.ietf.org/archive/id/draft-irse-draft-irse-xml2rfcv3-implemented-03.html#section-3.66.1)
with the actual citation anchor still pointing to the
references. 

Or maybe I'm still missing something but these seem to be more
questions for Jean and her colleagues about their preferences
and what the Style Manual should say.  Once they have expressed
opinions, the WG can decide whether to disagree or nit-pick.
After there is agreement, I'm confident that we can
reverse-engineer the RFCXML vocabulary to allow accommodating
them (including any author flexibility they think appropriate).
However, dropping a "section" attribute into the <xref> element
without examining the issue that Toerless first raised (I'm just
digging deeper) in this discussion, most of which have been
raised on and off with the RFC Editor Function for decades, is
exactly the sort of thing that causes some of us to feel that
things are in rather a mess.

best,
   john