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

[Kesara Rathnayake <[e-mail]>]

 > Kesara - could you code-mine and see what the code currently wants and
 > 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:
>> 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
> 

-- 
Kesara Rathnayake
Senior Software Development Engineer - IETF LLC
[e-mail]