RFC Format Change FAQ – 27 January 2021
See also: Infographic about the v3 RFC Format
- Where can I read a summary of requirements, documents, and changes?
- Where were the high-level requirements for a change to the RFC Format published?
- What does this mean for authors who don’t use xml2rfc?
- Where can I use non-ASCII characters in RFCs?
- What encodings does 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 are available now that we’ve transitioned to v3?
- Will you republish any RFCs in the new Canonical format?
- How are images handled for the plain text version of an RFC?
- What happens to paginated output?
- How are non-ASCII characters handled when rendering the plain text version of an RFC?
- What tools are available to create XML drafts?
- What tools do you recommend to create SVG files?
- What documents are related to the RFC format effort?
- Are these RFCs the final say on the format changes?
- “Where can I read a summary of requirements, documents, and changes?”
The framework of the RFC format work has been documented in RFC 7990.
- “Where were 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.
- “Where can I use non-ASCII characters in RFCs?”
UTF-8 characters are permitted in xml2rfc v3. For more details, see RFC 7997 and the xml2rfc FAQ.
- “What encodings does the RFC Editor accept?”
The RFC Editor accepts files encoded as ASCII or as UTF-8.
- “What do these changes mean for xml2rfc?”
The RFC Editor is now using xml2rfc v3. The v3 XML vocabulary is documented in RFC 7991 and the schema documentation. Authors with v2 drafts can mechanically translate them to v3 using xml2rfc --v2v3.
- “What happens if an author wants to provide a plain text file rather than an XML file?”
Authors are allowed to submit a plain text file. It will have to be converted to a basic XML file prior to publication using id2xml. See also “What does this mean for authors who don’t use xml2rfc?“
- “What publication formats are available now that we’ve transitioned to v3?”
HTML, TXT, and PDF are the first publication formats available. EPUB is also expected, and may 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. We provide HTMLized versions of pre-v3 RFCs (created mechanically using rfc2html). This allows proper linking from the text of a v3 RFC to an earlier RFC.
- “How are images 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 pointing to the HTML version. All artwork and figures should have a complete written description to support assisted reader technology.
- “What happens to paginated output?”
RFC 6949 retires the requirement for pagination. Pagination conflicts with the requirement for reflowable text. We are providing the ability to refer to specific locations within the document through other mechanisms. The PDF versions of RFCs are naturally paginated, while other file formats are not. Authors and readers should refer to section numbers when referring to specific text within an RFC. Paragraph numbers (in addition to section numbers) can be generated in the v3 HTML and PDF output formats for more granular reference targets.
- “How are non-ASCII characters handled when rendering the plain text version of an RFC?”
The RFC Editor follows the guidance provided in RFC 7997.
- “What tools are available to create XML drafts?”
The tools needed to create the publication outputs, to check the SVG, and more, have been developed through the usual IETF tools process. All tools have been released to the community. Several tools written in python can be downloaded from the pypi archive or installed with the python pip tool:
Also, xml2rfc and svgcheck can be run on the web at https://xml2rfc.tools.ietf.org/experimental.html.
- “What tools do you recommend to create SVG files?”
The author of RFC 7996, “SVG Drawings for RFCs: SVG 1.2 RFC” has made a few recommendations available here. See also the xml2rfc FAQ. Please note that the RFC Editor will not directly edit SVG images.
- “What documents are related to the RFC format effort?”
The RFC Format effort 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 they moved 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 documents 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. The documents were published as Informational RFCs within the IAB stream (except for the last one under “Workflow and tools”).
- The big picture
- [RFC7990] Flanagan, H., “RFC Format Framework”, RFC 7990, DOI 10.17487/RFC7990, December 2016, http://www.rfc-editor.org/info/rfc7990.
- The underlying vocabulary
- [RFC7991] Hoffman, P., “The ‘xml2rfc’ Version 3 Vocabulary”, RFC 7991, DOI 10.17487/RFC7991, December 2016, http://www.rfc-editor.org/info/rfc7991.
- The outputs
- [RFC7992] Hildebrand, J. and P. Hoffman, “HTML Format for RFCs”, RFC 7992, DOI 10.17487/RFC7992, December 2016, http://www.rfc-editor.org/info/rfc7992.
- [RFC7993] Flanagan, H. “Cascading Style Sheets (CSS) Requirements for RFCs”, RFC 7993, DOI 10.17487/RFC7993, December 2016, http://www.rfc-editor.org/info/rfc7993.
- [RFC7994] Flanagan, H., “Requirements for Plain-Text RFCs”, RFC 7994, DOI 10.17487/RFC7994, December 2016, http://www.rfc-editor.org/info/rfc7994.
- [RFC7995] Hansen, T., Masinter, L., and M. Hardy, “PDF Format for RFCs”, RFC 7995, DOI 10.17487/RFC7995, December 2016, http://www.rfc-editor.org/info/rfc7995.
- [RFC7996] Brownlee, N., “SVG Drawings for RFCs: SVG 1.2 RFC”, RFC 7996, DOI 10.17487/RFC7996, December 2016, http://www.rfc-editor.org/info/rfc7996.
- Generalized requirements
- [RFC7997] Flanagan, H., “The Use of Non-ASCII Characters in RFCs”, RFC 7997, DOI 10.17487/RFC7997, December 2016, http://www.rfc-editor.org/info/rfc7997.
- Workflow and tools
- [RFC7998] Hildebrand, J. and P. Hoffman, “‘xml2rfc’ Version 3 Preparation Tool Description”, RFC 7998, DOI 10.17487/RFC7998, December 2016, http://www.rfc-editor.org/info/rfc7998.
- Hoffman, P. and T. Hansen, “Examples of the ‘XML2RFC’ Version 2 and 3 Vocabularies”, Work in Progress, draft-hoffman-rfcexamples-04, May 2015. Not published as an RFC.
- The big picture
- “Are these RFCs the final say on the format changes?”
The published RFCs (RFCs 7990 through 7998) are the design documents as created by the RFC Format Design Team. We expect that the RFCs will need to be updated to capture what is practical and how the features are actually implemented. Issues and suggestions as offered by the community and the format tools developers will be tracked in the following GitHub repository: https://github.com/rfc-format. It is up to the project managers, John Levine (interim RFC series manager) and Robert Sparks, to discuss the issues and suggestions with the community and then offer clear direction back to the developers as to what should be implemented. When the development and testing are complete, a set of -bis documents that capture the “as built” description for the format requirements will be drafted.
- XML vocabulary (RFC 7991)
- HTML (RFC 7992)
- CSS (RFC 7993)
- TXT (RFC 7994)
- PDF (RFC 7995)
- SVG (RFC 7996)
- Non-ASCII chars (RFC 7997)
- preptool (RFC 7998)
The current version of xml2rfc accepts several vocabulary elements beyond what is in RFC 7991; the changes are marked “(New)” in the schema documentation (https://xml2rfc.tools.ietf.org/xml2rfc-doc.html). Running xml2rfc --docfile also creates the documentation.
- XML vocabulary (RFC 7991)