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

[Robert Sparks <[e-mail]>]

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:
> 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.
>>>>>
>>>>>
>>>>>
>>>>>
>>>>
>>>
>>
>
>