Subject: [Tools-discuss] Section references to referenced documents (Fwd: [apps-discuss] AppsDir reviews of draft-ietf-jose-json-web-signature-32)

From: Carsten Bormann <[email-masked]>
Date: Wed, 15 Oct 2014 09:35:56 +0200

From a recent appsdir review and the response to that:

Begin forwarded message:

>> 4.1.1. & 4.1.2. The links to Section 4.1 and Section 5.1 of JWA are incorrect.
>> They link to JWE instead of JWA.
>> 
>> In 4.1.1. the link is:
>> https://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-32#section-4.1
>> ...but it should be:
>> https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-33#section-4.1
>> 
>> In 4.1.2. the link is:
>> https://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-32#section-5.1
>> ...but it should be:
>> https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-33#section-5
>> (JWA doesn't seem to have an anchor for 5.1)
> 
> These link URLs are actually created by the IETF tools - not in the draft itself.  (You'll see "Html markup produced by rfcmarkup 1.109, available fromhttps://tools.ietf.org/tools/rfcmarkup/" at the bottom of the drafts.)  I'm not sure who to file a bug on this with.

I don’t quite understand the comment, but it is clear that text like

   the initial contents of this registry are the values defined
   in Section 3.1 of the JSON Web Algorithms (JWA) [JWA] specification.

is highlighted with a reference to Section 3.1 in the current document, not in the document being referenced.  I have no idea how to fix this (unless we add significant natural language processing to the rfcmarkup tool), so I’m raising this for discussion first before creating a tracker entry.

(Editorially, I believe a reference with an uppercase “Section” should always be one to the current document; a reference to a section in a different document should use lower case.  But I have no idea how wide-spread this convention is and whether this is the right thing to trigger on.)

Grüße, Carsten

---

From: Henrik Levkowetz <[email-masked]>
Date: Thu, 16 Oct 2014 12:56:05 +0200

Hi Carsten,

On 2014-10-15 09:35 Carsten Bormann said:
>> These link URLs are actually created by the IETF tools - not in the
>> draft itself.  (You'll see "Html markup produced by rfcmarkup
>> 1.109, available fromhttps://tools.ietf.org/tools/rfcmarkup/" at
>> the bottom of the drafts.)  I'm not sure who to file a bug on this
>> with.
> 
>   the initial contents of this registry are the values defined in
>   Section 3.1 of the JSON Web Algorithms (JWA) [JWA] specification.
> 
> is highlighted with a reference to Section 3.1 in the current
> document, not in the document being referenced.  I have no idea how
> to fix this (unless we add significant natural language processing to
> the rfcmarkup tool), so I’m raising this for discussion first before
> creating a tracker entry.

Right.  rfcmarkup handles a number of cases where Section x.y refers to another
RFC or draft, but only when the RFC or draft is mentioned as 'rfc NNNN' or
'draft-....', and occurs adjacent to the 'Section x.y' words.  I can see that
it could be possible to cache the names of all drafts and RFCs, and try to
match text adjacent to 'Section x.y' to not only RFC... and draft-... but
also to this list of known titles, but some work is needed to make that happen.

> (Editorially, I believe a reference with an uppercase “Section”
> should always be one to the current document; a reference to a
> section in a different document should use lower case.  But I have no
> idea how wide-spread this convention is and whether this is the right
> thing to trigger on.)

I wasn't aware of this convention, and with the wild variations in text
produced by humans, I don't think one can rely on that in this setting.

Best regards,

	Henrik

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 16 Oct 2014 14:00:43 +0200

> produced by humans, I don't think one can rely on that in this setting.

Indeed, and a co-author just pointed me to:

                Referring to specific sections within another document
                This is mostly left to author preference.  However, […]

followed by examples using upper case “Section” in an external reference:

http://www.rfc-editor.org/rfc-style-guide/part2.html

(CMOS, which otherwise is generally the source of RFC style, actually appears to always prefer lower case for references to parts of documents:
http://www.chicagomanualofstyle.org/qanda/data/faq/topics/Capitalization.html?page=1 at the end.)

So none of this helps for the heuristics.

Grüße, Carsten

PS.: historically, the widespread convention to capitalize internal references was boosted by the use of automation; many notations for internal references generate snippets such as “Section 3.6” from the reference but did not have a way to indicate whether the context was in-sentence (lower case in CMOS) or sentence-start (upper case in English); that was of course irrelevant for external references.
For XML2RFC, one would have to use <xref format=“counter” …> and manually prefix that with “section” to get CMOS style for an internal reference.