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

[John R Levine <[e-mail]>]

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

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

> On 9/3/21 5:11 PM, Sandy Ginoza wrote:
>> 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 <[e-mail] <mailto:[e-mail]>>
>>> *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 <[e-mail] <mailto:[e-mail]>>
>>> *Cc: *Robert Sparks <[e-mail] <mailto:[e-mail]>>, 
>>> Jean Mahoney <[e-mail] <mailto:[e-mail]>>
>>> 
>>> 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 <[e-mail] 
>>>> <mailto:[e-mail]>> 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 <[e-mail] 
>>>>> <mailto:[e-mail]>>
>>>>> 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 <[e-mail] <mailto:[e-mail]>>
>>>>> Cc: RFC Editor <[e-mail] 
>>>>> <mailto:[e-mail]>>
>>>>> 
>>>>> 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 <[e-mail] 
>>>>>>> <mailto:[e-mail]>> 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 
>>>>>> <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 
>>>>>> <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 
>>>>>>> <https://tools.ietf.org/html/rfc7998#section-5.6.3> .  This is
>>>>>>> emitted only in RFC production mode.
>>>>>> 
>>>>>> 
>>>>>> 
>>>>>> 
>>>>> 
>>>> 
>>> 
>> 
>> 
>

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