====== RFC 6949 ====== Note that the requirements have been gathered and published as [[http://www.rfc-editor.org/rfc/rfc6949.txt|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.