RFC Format Change FAQ – 1 October 2015
- Where can I read a summary of requirements, drafts, and expected changes?
- Where are the high-level requirements for a change to the RFC Format published?
- What does this mean for authors who don’t use xml2rfc?
- How soon can authors start using non-ASCII characters in RFCs?
- What encodings will the RFC Editor accept?
- What do these changes mean for xml2rfc?
- What happens if an author wants to provide a plain text file rather than an XML file?
- What publication formats will be available when the cutover happens?
- Will you republish any RFCs in to the new Canonical format?
- How will images be handled for the plain text version of an RFC?
- What happens to paginated output?
- How will UTF-8 characters be handled when rendering the plain text version of an RFC?
- Where are the tools coming from to make all this happen?
- What Internet-Drafts are related to the RFC format effort?
- “Where can I read a summary of requirements, drafts, and expected changes?”
The RFC format work has been documented in a framework draft. This draft is still in progress.
- “Where are the high-level requirements for a change to the RFC format published?”
The high-level requirements were captured in RFC 6949, “RFC Series Format Requirements and Future Development.”
- “What does this mean for authors who don’t use xml2rfc?”
Authors will continue to be able to submit their final I-Ds (those already approved by the streams) as a text or XML file. Authors can expect additional questions regarding potential metadata and element tags as we explore a broader use of XML.
Long-term implications for authors who do not use xml2rfc will be better understood after we have explored the full implication of tool changes and determined what seems to work most effectively for the RFC Editor and the community.
- “How soon can authors start using non-ASCII characters in RFCs?”
Several questions remain regarding the inclusion of non-ASCII characters within RFCs. While we are moving ahead with the intent of permitting non-ASCII, UTF-8 encoded characters, these characters will only be allowed in RFCs after the details of where and how new characters will be supported have been determined, when we have tools that can support those characters deployed, and the RFC Production Center is trained in the handling of such characters. Guidance on the use of non-ASCII characters in RFCs is being developed and documented in draft-flanagan-nonascii.
- “What encodings will the RFC Editor accept?”
The RFC Editor will only accept files encoded as UTF-8.
- “What do these changes mean for xml2rfc?”
Several things, including (but not limited to) further encouraging the deprecation of xml2rfc v1, code enhancements for v2, some new or changed element definitions, and the archiving of different versions of the tool by the RFC Publisher after major updates. The v2 XML vocabulary is being documented in draft-reschke-xml2rfc-latest, and the proposed v3 XML vocabulary is being documented in draft-hoffman-xml2rfc.
- “What happens if an author wants to provide a plain text file rather than an XML file?”
Authors will be allowed to submit a plain text file. It will have to be converted to a basic XML file prior to publication, and a tool that will assist with that is necessary for both the RFC Editor and the authors. See also “What does this mean for authors who don’t use xml2rfc?“
- “What publication formats be available when the transition happens?”
HTML, TXT, and PDF will be the first publication formats available. EPUB is also expected, and will be offered at a later date.
- “Will you republish any RFCs in the new Canonical format?”
No. No changes will be made to already-published RFCs.
- “How will images be handled for the plain text version of an RFC?”
The RFC Editor will accept both ASCII art and SVG. If only ASCII art is provided, it will be included in all publication formats. If ASCII art and SVG are both provided, ASCII art will be included in the plain text, and SVG in all other outputs. A note indicating alternative artwork is available is strongly advised. If only SVG is provided, a URI will be included in the plain text publication format (destination TBD). All artwork and figures should have a complete written description.
- “What happens to paginated output?”
RFC 6949 retires the requirement for pagination. Pagination conflicts with the requirement for reflowable text, which is considered a more urgent requirement given the variety of devices and preferences of the readers and the ability to refer to specific locations within a document through other mechanisms. While some formats such as PDF are naturally paginated, other file formats such as HTML are not. Authors and readers are encouraged to refer to section numbers when referring to specific text within an RFC. Paragraph numbers (in addition to section numbers) are being discussed as a possibility for more granular reference targets.
- “How will non-ASCII characters be handled when rendering the plain text version of an RFC?”
The RFC Editor will be following the guidance provided in “The Use of Non-ASCII Characters in RFCs”. That draft will remain in draft form until the RFC Editor feels confident we have captured the necessary requirements and guidance needed for handling non-ASCII characters in RFCs.
- “Where are the tools coming from to make all this happen?”
The tools needed to create the publication outputs, to update idnits, to check the SVG, and more, are being created through the usual IETF tools process. The RFPs are currently out for community review and may be seen online at IAOC RFPs.
- “What are the Internet-Drafts related to the RFC format effort?”
The RFC Format is a large project that has required several documents to capture the requirements found in each aspect of the work. The documents depend on each other, and are moving through the community review and publication process as a set to help keep those relationships intact. Several documents require understanding a separate document for full comprehension of the material. Below is the suggested reading order for the drafts that describe the new RFC format requirements. The design team has done a great job in pulling all of this together, and many members of the community have reviewed these in parts and offered targeted feedback. Please take this time to review the drafts as a compendium, and then review the Statements of Work that describe the programming effort that will depend on these drafts as their requirements.
- The big picture
- Flanagan, H., “RFC Format Framework”, Work in Progress, draft-flanagan-rfc-framework-04, June 2015.
- The underlying vocabulary
- Hoffman, P., “The ‘XML2RFC’ version 3 Vocabulary”, Work in Progress, draft-hoffman-xml2rfc-23, September 2015.
- The outputs
- Hildebrand, J. and P. Hoffman, “HyperText Markup Language Request For Comments Format”, Work in Progress, draft-hildebrand-html-rfc-07, June 2015.
- Flanagan, H., “Requirements for Plain Text RFCs”, Work in Progress, draft-flanagan-plaintext-08, September 2015.
- Hansen, T., Masinter, L., and M. Hardy, “PDF for an RFC Series Output Document Format”, Work in Progress, draft-hansen-rfc-use-of-pdf-07, March 2015.
- Brownlee, N., “SVG Drawings for RFCs: SVG 1.2 RFC”, Work in Progress, draft-brownlee-svg-rfc-12, September 2015.
- Generalized requirements
- Flanagan, H., “The Use of Non-ASCII Characters in RFCs”, Work in Progress, draft-flanagan-nonascii-05, August 2015.
- Workflow and tools
- Hildebrand, J. and P. Hoffman, “RFC v3 Prep Tool Description”, Work in Progress, draft-hoffman-rfcv3-preptool-06, September 2015.
- Hoffman, P. and T. Hansen, “Examples of the ‘XML2RFC’ Version 2 and 3 Vocabularies”, Work in Progress, draft-hoffman-rfcexamples-03, May 2015. Not to be published as an RFC.
- The Statements of Work
- The big picture