Subject: [Xml-sg-cmt] Fwd: docName - Re: Fwd: [django-project] Weird Internal Metadata error in I-D HTML

From: Sandy Ginoza <[email-masked]>
Date: Fri, 3 Sep 2021 15:11:51 -0700

Hi All,

Forwarding this mail in hopes we can discuss docName a bit. 

Have a great weekend!

Thanks!
Sandy 

> Begin forwarded message:
> 
> From: Sandy Ginoza <[email-masked]>
> Subject: Re: docName - Re: Fwd: [django-project] Weird Internal Metadata error in I-D HTML
> Date: September 1, 2021 at 6:28:06 PM PDT
> To: Alice Russo <[email-masked]>
> Cc: Robert Sparks <[email-masked]>, Jean Mahoney <[email-masked]>
> 
> Hi Robert,
> 
> Regarding docname=“draft”, is inclusion of the version number required?  We’ve started running into the question of whether the version number should match a) the approved version, b) the current datatracker version (versions submitted after the document enters the queue), or c) the version approved by the ADs (could be a or b).  
> 
> Please let me know if you prefer I send this to the full xml-sg-cmt. 
> 
> Thanks!
> Sandy 
> 
> 
>> On Aug 24, 2021, at 9:57 AM, Alice Russo <[email-masked]> wrote:
>> 
>> Hi Robert,
>> 
>> You wrote:
>>> I note (and I am actually surprised - I've forgotten how we got here) that we are _publishing_ RFCs with docName not matching seriesInfo value, and I bet this will cause confusion in the future.
>> 
>> I'm forwarding the mail below from 2019 for background re: setting docName to the draft string.  (As a result of the exchange below, grep shows "docName=\"draft" in the 439 RFCs published in the v3 era.)
>> 
>> Alice
>> 
>>> Begin forwarded message:
>>> 
>>> From: Henrik Levkowetz <[email-masked]>
>>> Subject: Re: docName - was: Re: [v3] "é" (acute/aigu accent) no longer accepted
>>> Date: September 16, 2019 at 12:18:13 PM PDT
>>> To: Alice Russo <[email-masked]>
>>> Cc: RFC Editor <[email-masked]>
>>> 
>>> Hi Alice,
>>> 
>>> On 2019-09-16 20:56, Alice Russo wrote:
>>>> Hi Henrik,
>>>> 
>>>> On the topic of docName:
>>>> 
>>>> Re:
>>>>> On Sep 16, 2019, at 11:36 AM, Henrik Levkowetz <[email-masked]> wrote:
>>>>> 
>>>>>> draft-ietf-mptcp-rfc6824bis-18.xml(4): Warning: Expected a <link> with rel="prev" providing the datatracker url for the origin draft, or alternatively a "docName" attribute on <rfc> from which to construct such a <link> element.
>>>>> 
>>>>> You should fix this one, too.  Provide docName="..." with the draft name
>>>>> from which the RFC comes.
>>>> 
>>>> OK; we can update our internal documentation accordingly.
>>>> 
>>>> I must have misunderstood from a past thread bc I thought we weren't
>>>> setting docName at all. If we set it to the draft string, it creates
>>>> this in the HTML output: 
>>>> <link href="https://datatracker.ietf.org/doc/draft-foo-09" rel="prev">
>>> 
>>> That's right, that's the intention.
>>> 
>>>> Is the following accurate?
>>>> - This link element is not displayed in the browser-rendered HTML
>>>> (only viewable in the HTML source).
>>> 
>>> Yes.
>>> 
>>>> - This link element exists because it is specified in
>>>> <https://tools.ietf.org/html/rfc7998#section-5.6.3>.
>>> 
>>> Yes.
>>> 
>>>> Is there more understanding we should have?  From the RPC
>>>> perspective, it seems odd that the docName is set to the drafts
>>>> string (i.e., the RFC is no longer draft-foo-09).
>>> 
>>> Yes, I can see that.  The attribute name is not appropriate for the use
>>> it has when the document becomes an RFC.  "draftName" or "draft-name" would
>>> have been better.  But docName has been with us since Marshall Rose's first
>>> implementation of xml2rfc, I think, so I doubt we can fix that.
>>> 
>>> 
>>> Best regards,
>>> 
>>> 	Henrik
>>> 
>>>> 
>>>> Thanks,
>>>> Alice
>>>> 
>>>> Background from May thread:
>>>> 
>>>> On May 10, 2019, you wrote:
>>>>> No, the docName should not change to a number; the docName is used to add
>>>>> metadata about the draft from which an RFC is derived when writing a v3
>>>>> RFC in html format, and to insert the draft name when writing draft output.
>>>> 
>>>> And then later the same day:
>>>>>>> Warning: Expected a <link> with rel='prev' providing the datatracker url for the origin draft.
>>>>>> 
>>>>>> The v2v3 converter inserts a <link> with rel='prev' if docName is given;
>>>>>> for v3 xml you should set that.  I think, however, that this warning should
>>>>>> more correctly be a note or comment.
>>>>> 
>>>>> No, I'm wrong.  It should be at least a warning, possibly an error.  This is
>>>>> covered in https://tools.ietf.org/html/rfc7998#section-5.6.3 .  This is
>>>>> emitted only in RFC production mode.
>>>> 
>>>> 
>>>> 
>>>> 
>>> 
>> 
>

---

From: Robert Sparks <[email-masked]>
Date: Sat, 4 Sep 2021 12:22:06 -0500

Sandy and Alice have seen this before - repeating it here to help with 
the conversation:

Ultimately we're going to have to document the continued use of docname 
in v3 (vs the current 779* docs that say it is deprecated and unused), 
or put this information somewhere that's semantically well-labeled and 
stop using the older docname attribute.

Other people may be able to more quickly explain why continuing to use 
docname in the case Henrik points to below is the better choice - I 
suspect its so that we can treat older references and newer ones the same?

Kesara - could you code-mine and see what the code currently wants and 
does with any version in docname for a v3 document?

RjS

On 9/3/21 5:11 PM, Sandy Ginoza wrote:
>> *From: *Sandy Ginoza <[email-masked] <mailto:[email-masked]>>
>> *Subject: **Re: docName - Re: Fwd: [django-project] Weird Internal 
>> Metadata error in I-D HTML*
>> *Date: *September 1, 2021 at 6:28:06 PM PDT
>> *To: *Alice Russo <[email-masked] <mailto:[email-masked]>>
>> *Cc: *Robert Sparks <[email-masked] 
>> <mailto:[email-masked]>>, Jean Mahoney <[email-masked] 
>> <mailto:[email-masked]>>
>>
>> Hi Robert,
>>
>> Regarding docname=“draft”, is inclusion of the version number 
>> required?  We’ve started running into the question of whether the 
>> version number should match a) the approved version, b) the current 
>> datatracker version (versions submitted after the document enters the 
>> queue), or c) the version approved by the ADs (could be a or b).
>>
>>> On Aug 24, 2021, at 9:57 AM, Alice Russo <[email-masked] 
>>> <mailto:[email-masked]>> wrote:
>>>
>>> Hi Robert,
>>>
>>> You wrote:
>>>> I note (and I am actually surprised - I've forgotten how we got 
>>>> here) that we are _publishing_ RFCs with docName not matching 
>>>> seriesInfo value, and I bet this will cause confusion in the future.
>>>
>>> I'm forwarding the mail below from 2019 for background re: setting 
>>> docName to the draft string.  (As a result of the exchange below, 
>>> grep shows "docName=\"draft" in the 439 RFCs published in the v3 era.)
>>>
>>> Alice
>>>
>>>> Begin forwarded message:
>>>>
>>>> From: Henrik Levkowetz <[email-masked] 
>>>> <mailto:[email-masked]>>
>>>> To: Alice Russo <[email-masked] <mailto:[email-masked]>>
>>>> Cc: RFC Editor <[email-masked] 
>>>> <mailto:[email-masked]>>
>>>>
>>>> Hi Alice,
>>>>
>>>>>> On Sep 16, 2019, at 11:36 AM, Henrik Levkowetz 
>>>>>> <[email-masked] <mailto:[email-masked]>> wrote:
>>>>>>
>>>>>>> draft-ietf-mptcp-rfc6824bis-18.xml(4): Warning: Expected a 
>>>>>>> <link> with rel="prev" providing the datatracker url for the 
>>>>>>> origin draft, or alternatively a "docName" attribute on <rfc> 
>>>>>>> from which to construct such a <link> element.
>>>>>>
>>>>> <link href="https://datatracker.ietf.org/doc/draft-foo-09 
>>>>> <https://datatracker.ietf.org/doc/draft-foo-09>" rel="prev">
>>>>
>>>>> <https://tools.ietf.org/html/rfc7998#section-5.6.3 
>>>>> <https://tools.ietf.org/html/rfc7998#section-5.6.3>>.
>>>>
>>>> Yes.
>>>>
>>>>>> covered in https://tools.ietf.org/html/rfc7998#section-5.6.3 
>>>>>> <https://tools.ietf.org/html/rfc7998#section-5.6.3> .  This is

---

From: "John R Levine" <[email-masked]>
Date: 4 Sep 2021 16:25:47 -0400

> docname in the case Henrik points to below is the better choice - I suspect 
> its so that we can treat older references and newer ones the same?

I think I see what Henrik did, but it doesn't agree with 7991 or 7998.

7991 says that docName is deprecated in favor of seriesInfo, so I think it 
is clearly wrong that the docName and seriesInfo don't match.

7998 says the preptool adds a <link> to the draft with rel="convertedFrom" 
attribute but in fact it has rel="prev"

I think the least wrong thing to do is for the preptool to add 
a link with rel="convertedFrom" and delete the docName.

This is not backward compatible but I am increasingly feeling that once we 
are done, we should have a flag day and republish the XML to match the 
final grammar.

R's,
John

>>> *Cc: *Robert Sparks <[email-masked] <mailto:[email-masked]>>, 
>>> Jean Mahoney <[email-masked] <mailto:[email-masked]>>
>>> 
>>> Hi Robert,
>>> 
>>> Regarding docname=“draft”, is inclusion of the version number required?
>>>  We’ve started running into the question of whether the version number 
>>> should match a) the approved version, b) the current datatracker version 
>>> (versions submitted after the document enters the queue), or c) the 
>>> version approved by the ADs (could be a or b).
>>> 
>>>>> I note (and I am actually surprised - I've forgotten how we got here) 
>>>>> that we are _publishing_ RFCs with docName not matching seriesInfo 
>>>>> value, and I bet this will cause confusion in the future.
>>>> 
>>>> docName to the draft string.  (As a result of the exchange below, grep 
>>>> shows "docName=\"draft" in the 439 RFCs published in the v3 era.)
>>>> 
>>>> Alice
>>>> 
>>>>> Begin forwarded message:
>>>>> 
>>>>>>> On Sep 16, 2019, at 11:36 AM, Henrik Levkowetz <[email-masked] 
>>>>>>> <mailto:[email-masked]>> wrote:
>>>>>>> 
>>>>>>>> draft-ietf-mptcp-rfc6824bis-18.xml(4): Warning: Expected a <link> 
>>>>>>>> with rel="prev" providing the datatracker url for the origin draft, 
>>>>>>>> or alternatively a "docName" attribute on <rfc> from which to 
>>>>>>>> construct such a <link> element.
>>>>>>> 

Regards,
John Levine, [email-masked], Taughannock Networks, Trumansburg NY
Please consider the environment before reading this e-mail. https://jl.ly

---

From: Kesara Rathnayake <[email-masked]>
Date: Mon, 6 Sep 2021 16:01:02 +1200

> does with any version in docname for a v3 document?

xml2rfc prep tool checks for a <link> with rel="prev" first.
If that is missing then xml2rfc looks for docName and construct a <link> 
with rel="prev" from the docName.

When both docName and a <link> with rel="prev" are missing, xml2rfc prep 
tool spitout a warning:
```
Warning: Expected a <link> with rel="prev" providing the datatracker url 
for the origin draft, or alternatively a "docName" attribute on <rfc> 
from which to construct such a <link> element.
```

Reference: 
https://trac.ietf.org/trac/xml2rfc/browser/trunk/cli/xml2rfc/writers/preptool.py#L2338

   -- Kesara

On 5/09/21 8:25 am, John R Levine wrote:
> 7991 says that docName is deprecated in favor of seriesInfo, so I think 
> it is clearly wrong that the docName and seriesInfo don't match.
> 
> 7998 says the preptool adds a <link> to the draft with 
> rel="convertedFrom" attribute but in fact it has rel="prev"
> 
> I think the least wrong thing to do is for the preptool to add a link 
> with rel="convertedFrom" and delete the docName.
> 
> This is not backward compatible but I am increasingly feeling that once 
> we are done, we should have a flag day and republish the XML to match 
> the final grammar.
> 
> R's,
> John
> 
>>>>  We’ve started running into the question of whether the version 
>>>> number should match a) the approved version, b) the current 
>>>> datatracker version (versions submitted after the document enters 
>>>> the queue), or c) the version approved by the ADs (could be a or b).
>>>>

-- 
Kesara Rathnayake
Senior Software Development Engineer - IETF LLC
[email-masked]