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

[bclaise at cisco.com (Benoit Claise)]

Dear all,

Disclaimer:
	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 :-)
  

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


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

Alternatively,
OLD:
	The final XML will be self-contained.

NEW:
	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?
Because I see section 10.3 "Completion" section that says:
	Authors may submit XML (preferred) or plain text.

We should make it clear.
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
       format")
	- No PDF file for your current draft and future RFC ("The PDF file will not be derived from the plain-text publication
       format.")
	- maybe some others?


Regards, Benoit

(*)
Reading list:

1. The big picture

- - Flanagan, H., "RFC Format Framework",
   http://datatracker.ietf.org/doc/draft-iab-rfc-framework/

2. The underlying vocabulary

- - Hoffman, P., "The 'XML2RFC' version 3 Vocabulary",
    https://datatracker.ietf.org/doc/draft-iab-xml2rfc/

3. The outputs

- - Hildebrand, J. and P. Hoffman, "HyperText Markup
   Language Request For Comments Format?,
   https://datatracker.ietf.org/doc/draft-iab-html-rfc/

- - Flanagan, H., "Requirements for Plain Text RFCs?,
    https://datatracker.ietf.org/doc/draft-iab-rfc-plaintext/

- - Hansen, T., Masinter, L., and M. Hardy, "PDF for
   an RFC Series Output Document Format?,
   https://datatracker.ietf.org/doc/draft-hansen-rfc-use-of-pdf/
   Note that the filename may change to an IAB document soon.

- - Brownlee, N., "SVG Drawings for RFCs: SVG 1.2 RFC",
   https://datatracker.ietf.org/doc/draft-iab-svg-rfc/

4. Generalized requirements

- - Flanagan, H., "The Use of Non-ASCII Characters in RFCs",
   https://www.ietf.org/id/draft-iab-rfc-nonascii-00.pdf

- - Flanagan, H., ?CSS Requirements for RFCs?,
   https://datatracker.ietf.org/doc/draft-iab-rfc-css/

5. Workflow and tools (note that the examples draft will
   not become an RFC, but is necessary for the project)

- - Hildebrand, J. and P. Hoffman, "RFC v3 Prep Tool Description",
   https://datatracker.ietf.org/doc/draft-iab-rfcv3-preptool/

- - Hoffman, P. and T. Hansen, "Examples of the ?XML2RFC'
   Version 2 and 3 Vocabularies?,
   http://datatracker.ietf.org/doc/draft-hoffman-rfcexamples/

6. The Statements of Work

- -http://www.nostrum.com/~rjsparks/rfced/

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.rfc-editor.org/pipermail/rfc-interest/attachments/20160128/731cdf29/attachment.html>