User Tools

Site Tools


formatreq

RFC 6949

Note that the requirements have been gathered and published as RFC 6949.


The RFC Series has been in existence for over 40 years. During much of that time, the limitations of character set, line and page length, and graphics restrictions of RFC documents met the most immediate needs of the majority of authors and readers. As technology changed, new formats that allowed for a richer set of features when editing, reading, searching, and displaying documents came in to use and tools were created to convert the plain ASCII documents in to other desired formats such as HTML, PDF, and Microsoft Word. While the converted versions of the RFC are widely available, the canonical display format remains the plain text, ASCII, line-printer structured one. The canonical source format is nroff.

Canonical source and display versions of an RFC exists for several reasons:

  • to provide verification of the content of a RFC in case inconsistencies are created when a document is converted to another format or mirrored to another location
  • to verify the final content of a document in cases of legal dispute
  • to aid in the conversion of the RFC in to formats requested by the community

The very basic format of RFC source and display documents have two persistent characteristics that are considered by the RFC Series Editor to be critical to the RFC Series, including:

  • persistence (tools to read, edit, and print the documents remain easily accessible to everyone)
  • convertibility (the plain text version is simple to convert to other formats)

That said, the very simple nature of the current display format in particular introduces a variety of limitations, the list of which has grown as changes in technology create new expectations:

  • ASCII art is considered by some to be a major limitation in expressing visually-oriented information
  • the internationalization of the authorship and the Internet is introducing characters not possible in plain ASCII
  • the more common forms of display (web pages, smaller devices) make the limitations of page and line length a hindrance to the reading of an RFC

So, the community and the RFC Editor have decided to review the canonical format of the RFC series and discuss whether it needs to change to address those limitations and, if change is required, what the change should look like. This wiki page attempts to capture the requirements of the community regarding format for the RFC, including suggestions that will be fed back to the IETF regarding similar changes to the Internet-Draft format.


Fundamental requirement

  • Any new format MUST continue the level of persistence found in the existing format
  • While the canonical source format MUST be easily converted in to a variety of other formats, a single canonical display format must exist to satisfy the requirements of legal and content disputes

Draft-Edit, Review (what authors, ADs, and other interested parties worry about when writing and reviewing an I-D)

Note that requiring change to I-D format is outside the purview of the RFC Series Editor. Information collected that suggests changes to I-D format will be submitted to the IESG.

Feature Current available Consensus Comments
Need broader character encoding for author names No Yes, with limitations [RSE] would note that at least one TLD registrar (AFNIC) is beginning to register domain names with diacritical marks and these will eventually show up in references and author's addresses; a potential compromise is to limit what characters are allowed, such as to the list allowed by DNS domain registrars; suggestion that all authors must also provide a transliteration of his/her name with ASCII-only characters
Need to be able to update documents easily and see how they might look when published Yes Yes
Need to be able to include non-ASCII graphics/images Not in canonical text version No [RSE] graphics, whether ASCII or other, have complications when considering resizeability (see small device request); [RSE] may point to a separate document such as PDF with different images/graphics for clarity
Need to be able to create new documents by hacking away at older ones Yes Yes
Need be able to diff versions of a draft Yes Yes
Need format to be easily rendered in to other, potentially undefined formats (.txt, .html, other) Yes Yes While current format can be rendered in other formats such as HTML, PDF, PS, there are arguments that that conversion is not perfect as it cannot take advantage of some of the features in the newer formats
Need to be able to search document and document repositories with tools such as *grep Yes Yes
Want broader character encoding for body of document No Yes, with limitations UTF-8, probably; need to determine what further limitations, if any, will be required
Want the ability to denote protocol examples using the character sets those examples support No Yes [RSE] similar to the general request for broader character encoding for the body of a document
Want the ability to semantically tag some document info, at least authors' names and references No No [RSE] implication here is that semantically tagging doc info would result in the canonical format of the RFC being source code, to be converted to a variety of display formats
Want to be able to include equations Limited No Does not seem to be sufficient need for this to make it an explicit requirement
Want a more flexible line length No Yes [RSE] should be rephrased to state want to make the new format display reasonably well on a variety of screen sizes
Want to be able to tag ownership/source of comments No No

RFC-Edit

additional requirements to the Draft Edit/Review list as provided by the RFC editors

Feature Current available Consensus Comments
Need source file to be editable by both authors and RFC editors Yes Yes Consensus within RFC Editor
Want a single, discrete source file for a draft (not multiple files and a make file) No Yes RFC Ed currently accepts XML and nroff and does all the necessary conversions as part of the editorial process
Want a publicly available “official” conversion tool (same source file producing the same output between I-D submission and RFC editing step) Yes (limited) Yes

RFC-Archive

what the RFC Editor worries about when publishing an RFC

Feature Current available Consensus Comments
Need source format to be easily rendered in to other, potentially undefined formats (.txt, .html, other) ? Yes
Need one source and display format to be the authoritative version, suitable for legal records Yes Yes
Need to be able to create new documents by hacking away at older ones Yes Yes
Need backward compatibility to recreate documents originally created in an older version of the output tools (backward compatibility issue doesn't apply to docs published prior to the format change) n/a Yes
Need a long-lived file format with an open specification, i.e., such that the community can continue to support it even if commercial support disappears Yes Yes

End consumption

Feature Consensus Comments
Need to be able to see non-ASCII graphics/images No No [RSE] may point to a separate document such as PDF with different images/graphics for clarity
Need to be able to search document and document repositories with tools such as *grep Yes Yes
Need to be able to create new documents by hacking away at older ones Yes Yes
Want intelligent html-style linking within references No No
Want the RFC to be suitable for small screens/mobile devices No Yes
Want to have neat printing (intelligent pagination) Yes (but limited to a narrowly defined page format) Yes But there is disagreement as to what that would actually look like
Want to be able to view equations Yes (limited to simple equations or contorted writing) No
Want a more flexible line length No No [RSE] should be rephrased to state want to make the new format display reasonably well on a variety of screen sizes
Want a single document to view (should not have to jump between two documents for complete information) Yes (usually) No [RSE] currently an RFC may include pointers to a separate document such as PDF with different images/graphics for clarity

This list is a union of suggestions made on the rfc-interest list, in conversations with the RFC Production Center, and RFC Series Advisory Group, with my take on prioritization based on list input and my professional input. I would like to see the various I-D on the topic of RFC Format to take in to account the “needed” items, and if some/any/many the “wanted” items can be solved for, great. I do not expect the solution(s) presented any one I-D to be able to meet every item on this list.

formatreq.txt · Last modified: 2013/05/31 16:25 by rsewikiadmin