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

[Jean Mahoney <[e-mail]>]

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