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

[Julian Reschke <[e-mail]>]

Am 28.09.2022 um 19:40 schrieb John C Klensin:
> 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:

RFC 7991 has "<relref>". Nobody liked that, and thus we have an
extension on <xref> instead.

> 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.

Sounds you would like "[Section x of RFCYYYY]"? That's not common
practice in RFCs and also not the preferred format as stated by the RFC
Editor (I believe).

Yes, we can discuss this. xml2rfc happens to support was has been widely
used before.

> 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.

It's a section number (where number is alphanumeric so that appendices
can be referenced).

> (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

I would simply say "Section 3.66.5 of the "As Implemented spec [...]". I
*believe* you can get that with the right combination of sectionFormat
attributes and text content of <xref>.

At the end of the day, the goal of the xml2rfc vocabulary is to make
simple things simple, and also get authors to use a consistent style. If
your style preferences are different, you might have to type a lot more.

> HTML where the whole business is a citation anchor and link?  I
> am not optimistic about getting the right in the output
> generation process.

At this point it's pretty clear to me that you haven't tried the format.
How about doing that instead of elaborating what could in theory be bad
about it?

> (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.

I recommend just trying it, or looking at the hundreds of RFCs that have
been published in the last few years.

Example: <https://www.rfc-editor.org/rfc/rfc9110.html#section-2.1-4>.

> 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).

I happen to have tests for this. See
<https://greenbytes.de/tech/webdav/xref-tests-hlext.xml2rfcv3.html>.

> 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

Best regards, Julian