[rfc-i] draft-iab-rfc-framework-02 feedback

Heather Flanagan rse at rfc-editor.org
Tue Feb 2 14:26:23 PST 2016

Hello Benoit, and thank you for the feedback!

On January 28, 2016 at 7:09:53 AM, Benoit Claise (bclaise at cisco.com) wrote:

Dear all,

        this is the first time I read those RFC format documents,  
        I've not been following the rfc-interest mailing list,  
        and I'm reading the documents in sequence (*)

- Editorial:

   Key changes to the publication of RFCs are highlighted, and a
   transition plan that will take the Series from a plain-text, ASCII-
   only format to the new formats is described [RFC-INTEREST].

Do you want to say: "... is discussed on the rfc-interest mailing list [RFC-INTEREST]"
By using "is described [RFC-INTEREST]", I was not too sure whether I should read the entire mailing list to understand the transition plan.
Hopefully not :-)
Well, there has been a LOT of discussion on the list. This pointer is merely to make sure people know where to find that list, and then they can look at the archives for any specific topics of interest.

- Editorial:
   Input was received through the rfc-interest mailing
   list, as well as in several face-to-face sessions at IETF meetings.
   Input was received through the rfc-interest mailing
   list [RFC-INTEREST], as well as in several face-to-face sessions at IETF meetings.

Since the list was already cited earlier, it shouldn’t be cited again in the document.

- I read "self-contained" in
   o  The final XML will be self-contained.  For instance, all features
      that reference externally-defined input will be expanded.  This
      includes all uses of xinclude, src attributes (such as in
      <artwork> or <sourcecode> elements), include-like processing
      instructions, and externally defined entities.

What about errata? Contained or not in the XML?  
I was puzzled because I read this early:  
   HTML will be the focus of
   providing the most flexible set of features for an RFC, including
   JavaScript to provide pointers to errata and other metadata.
Reading again, I found my answer:  
   The final XML file produced by the RFC Editor will be considered the
   canonical format for RFCs

I guess I was after some text like this (maybe obvious now that I researched this further):

      The final XML will not be updated with post-publication metadata, such
      as errata or obsoletion.

        The final XML will be self-contained.

        The final XML will be self-contained with all the information known at  
        publication time.


Section 10.2.  "Testing and Transition" mentions:
   Authors are not required to submit their approved drafts in an XML
   format, though they are strongly encouraged to do so; plain-text will
   also remain an option for the foreseeable future.  However, documents
   submitted as plain-text cannot include such features as SVG artwork.
So plain-text will remain an option for the "testing and transition period" only, or even after?
Plain text will remain an option well past the testing and transition period. I do not see that changing any time soon. As you noted below, it would be better for a variety of reasons for authors to submit XML instead, but it will not be required. The RPC will create the XML when an author submits just the plain text.

Because I see section 10.3 "Completion" section that says:
        Authors may submit XML (preferred) or plain text.

We should make it clear.
I’m not sure how to make it any more clear that we’ll continue to accept plain text into the far, far future.

Also, I believe we need a big warning section to authors who still want to use .txt:
        - extra work for RPC
        - no CVG artwork available  
        - No HTML file for your current draft and future RFC ("The HTML will not be derived from the plain-text publication

The output formats will be derived from the XML. If plain text is submitted, then it will be converted by the RPC into XML, and the outputs rendered from that XML file. So, yes, there will be an HTML, PDF, and TXT for drafts submitted as plain text. But the RPC will not try to create the SVG or add other features as allowed through the xml2rfc v3 vocabulary.

        - No PDF file for your current draft and future RFC ("The PDF file will not be derived from the plain-text publication
See above.

        - maybe some others?

Do you think that belongs here in the framework document, or somewhere else?

Heather Flanagan
RFC Series Editor
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.rfc-editor.org/pipermail/rfc-interest/attachments/20160202/6afbae76/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 101 bytes
Desc: Message signed with OpenPGP using AMPGpg
URL: <http://www.rfc-editor.org/pipermail/rfc-interest/attachments/20160202/6afbae76/attachment-0001.asc>

More information about the rfc-interest mailing list