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

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

Jean,

Many thanks.  And apologies for the bits that you picked up and
answered while I was writing my long response to Julian.

best,
   john


--On Wednesday, September 28, 2022 12:32 -0500 Jean Mahoney
<[e-mail]> wrote:

> John and Julian,
> 
> On 9/28/22 10:52 AM, Julian Reschke 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...
> [JM] The RFC Style Guide [RFC7322] is not explicit about the
> scope of a reference, but it can be inferred that it is at the
> level of a document rather than a section.  That is, an
> author does not need to provide a reference entry for each
> external section cross-referenced in the document.
> 
> 
>>> 
>>> or whether to embed the section number in the references so
>>> one would have simply "[RFC8989a]" and "[RFC8989b]" in the
>>> running text. 
> [JM]  If an author wants to create a reference entry for a
> particular external section, the tag construction above along
> with providing section details in the entry works, but this
> construction is not captured in the current Style Guide. I've
> added an issue
> (https://github.com/rfc-format/draft-flanagan-7322bis/issues/9
> ).
> 
> An example taken from RFC 8753:
> 
>     For most purposes, this would be done by adding to
>     the table of exceptions associated with Rule G [RFC5892a].
>     ...
> 
>     [RFC5892a] Faltstrom, P., Ed., "The Unicode Code Points and
>                Internationalized Domain Names for Applications
> (IDNA)",
>                Section 2.7, RFC 5892, August 2010,
>                <https://www.rfc-editor.org/rfc/rfc5892.txt>.
> 
> 
>>> 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.
> [JM] As Julian points out, xml2rfc supports the creation of
> hyperlinks to sections in other RFCs, and multiple formats are
> available. These formats are specified with the sectionFormat
> attribute:
> 
>     <xref target="RFC8959" section="1" sectionFormat="of"/>
> 
> For more information about sectionFormat, please see:
> https://www.rfc-editor.org/materials/FAQ-xml2rfcv3.html#name-w
> hat-about-referring-to-a-s
> 
> This <xref> construction creates in the PDF and HTML outputs
> two hyperlinks:  a _Section N_ hyperlink to the actual
> section of the RFC hosted on rfc-editor.org and an _[RFCXXXX]_
> hyperlink to the entry in the References section. The _Section
> N_ hyperlink is just that; it is not considered part of the
> reference entry.
> 
> To be explicit that a particular cite tag and its reference
> refers to a section and not the entire document, an author
> needs to create a custom value for the target attribute and
> build the reference entry with supporting text as shown in the
> example taken from RFC 8753.  xml2rfc does not have a
> shortcut for creating a section-specific cite tag and
> reference entry.
> 
> Best regards,
> Jean
> 
> 
> 
>> 
>> > ...
>> 
>> Best regards, Julian
>>