This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
design:start [2013/09/15 08:37] rsewikiadmin added page to discuss impact on errata system |
design:start [2019/05/07 09:31] (current) rsewikiadmin General update |
||
---|---|---|---|
Line 1: | Line 1: | ||
RFC Design Team wiki space | RFC Design Team wiki space | ||
- | ==== Expected Outputs of the Design Team ==== | + | ===== Introduction ===== |
- | - examples of Publication outputs (they may be done manually and are designed to show what things will look like) a specification or set of specifications on what needs to be done to create the necessary tools for XML to be the canonical format that in turn creates four publication formats | + | |
- | - documentation on what areas we have discussed and resolved internally so when I take this back out to the community, I can point to something that says "we discussed that issue, not discussing it again unless you have some new information that is relevant" | + | |
- | - clear guidelines on how different scripts (see RFC 6365 for terminology clarification) will be allowed in specific sections of an RFC now that the UTF-8 encoding will be allowed in the Author' | + | |
- | - an SVG profile for tags allowed/ | + | |
- | - document the requirements for the XML format and the transformation tool(s) | + | |
- | ==== Open Questions ==== | + | During IETF 86, the IAB formally approved the publication of "RFC Format Requirements and Future Development" |
- | - How will unintentional variations in output be dealt with? | + | |
- | - Will the Publication formats be allowed to change, allowing for modifications if the transformation from XML introduces format-specific errors? | + | |
- | - How does xml2rfc fit in to this work? What needs to change? | + | |
- | - Given the end goals, | + | |
- | - Will we have one or more " | + | |
- | ==== Additional Pages on this Wiki ==== | + | The direction we are exploring is one where the Canonical format - the format that is authoritative for content of an RFC - is XML using the xml2rfc DTD. From that format, four Publication formats will be rendered: Text, HTML, PDF, and EPUB. We are focusing |
- | * [[design: | + | * well-known by many in the authoring community as well as the RFC Editor; |
- | * [[design: | + | * has a start on meeting most of the requirements |
- | * [[design: | + | * is based on a solid mark-up language that is expected to exist for the foreseeable future. |
- | * [[design: | + | |
- | * [[design: | + | |
- | * [[design: | + | |
- | * [[design: | + | |
- | * [[design: | + | |
- | * [[design: | + | |
- | * [[design: | + | |
- | ==== Format Requirements pulled from RFC 6949 ==== | + | Authors may continue to submit XML or text files when their I-Ds are approved for publication. |
- | | + | By allowing for multiple Publication formats, readers can choose a format that works best for their circumstances. |
- | | + | |
- | + | The [[design: | |
- | 2. The Canonical format must be persistent and reliable across a | + | |
- | | + | ==== Project Implementation ==== |
- | | + | * [[https:// |
- | | + | * [[design: |
- | | + | |
+ | ==== Reading list ==== | ||
+ | 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 fo 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. | ||
+ | |||
+ | 1. The big picture | ||
+ | |||
+ | [RFC7990] Flanagan, H., “RFC Format Framework”, | ||
+ | |||
+ | 2. The underlying vocabulary | ||
+ | |||
+ | [RFC7991] Hoffman, P., “The ‘xml2rfc’ Version 3 Vocabulary”, | ||
+ | |||
+ | 3. The outputs | ||
+ | |||
+ | [RFC7992] Hildebrand, J. and P. Hoffman, “HTML Format for RFCs”, RFC 7992, DOI 10.17487/ | ||
+ | |||
+ | [RFC7993] Flanagan, H. “Cascading Style Sheets (CSS) Requirements for RFCs”, RFC 7993, DOI 10.17487/ | ||
+ | |||
+ | [RFC7994] Flanagan, H., “Requirements for Plain-Text RFCs”, RFC 7994, DOI 10.17487/ | ||
+ | |||
+ | [RFC7995] Hansen, T., Masinter, L., and M. Hardy, “PDF Format for RFCs”, RFC 7995, DOI 10.17487/ | ||
+ | |||
+ | [RFC7996] Brownlee, N., “SVG Drawings for RFCs: SVG 1.2 RFC”, RFC 7996, DOI 10.17487/ | ||
+ | |||
+ | 4. Generalized requirements | ||
+ | |||
+ | [RFC7997] Flanagan, H., “The Use of Non-ASCII Characters in RFCs”, RFC 7997, DOI 10.17487/ | ||
+ | |||
+ | 5. Workflow and tools | ||
+ | |||
+ | [RFC7998] Hildebrand, J. and P. Hoffman, “‘xml2rfc’ Version 3 Preparation Tool Description”, | ||
+ | |||
+ | Hoffman, P. and T. Hansen, “Examples of the ‘XML2RFC’ Version 2 and 3 Vocabularies”, | ||
+ | |||
+ | |||
+ | ==== Format Requirements from RFC 6949 ==== | ||
+ | |||
+ | - The content of an RFC must not change, regardless of format, once published. | ||
+ | | ||
+ | - While several Publication formats must be allowed, in order to continue support for the most basic reading and search tools and to provide continuity for the Series, at least one Publication format must be plain text. | ||
+ | - The boilerplate and overall structure of the RFC must be in accordance with current RFC and Style Guide requirements (see RFC 5741). | ||
+ | - The documents must be made accessible to people with visual disabilities through such means as including alternative text for images and limiting the use of color. See the W3C's accessibility documents | ||
+ | - The official language of the RFC Series is English. | ||
+ | - The Submission and Publication formats need to permit extending the set of metadata tags, for the addition of labeled metadata. | ||
+ | - Graphics may include ASCII art and a more complex form to be defined, such as SVG line art [SVG]. | ||
+ | - The Canonical format must be renderable into self-contained Publication formats in order to be easily downloaded and read offline. | ||
+ | - Fixed-width fonts and non-reflowable text are required for ASCII-art sections, source code examples, and other places where strict alignment is required. | ||
+ | - At least one Publication format must support readable print to standard paper sizes. | ||
+ | - The Canonical format should be structured to enable easy program identification and parsing of code or specifications, | ||
| | ||
- | 3. While several Publication formats must be allowed, in order to | + | |
- | continue support for the most basic reading and search tools | + | |
- | and to provide continuity for the Series, at least one | + | |
- | Publication format must be plain text. | + | |
- | + | ||
- | 4. The boilerplate and overall structure of the RFC must be in | + | |
- | accordance with current RFC and Style Guide requirements (see | + | |
- | [RFC5741]). | + | |
- | + | ||
- | 5. The documents must be made accessible to people with visual | + | |
- | disabilities through such means as including alternative text | + | |
- | for images and limiting the use of color. | + | |
- | accessibility documents [WCAG20] and the United Nations | + | |
- | " | + | |
- | [UN2006] for guidance. | + | |
- | desirable but focus on the creation of Internet-Drafts, | + | |
- | topic outside the scope of the RFC Editor. | + | |
- | + | ||
- | 6. The official language of the RFC Series is English. | + | |
- | required for all text that must be read to understand or | + | |
- | implement the technology described in the RFC. Use of non- | + | |
- | ASCII characters, expressed in a standard Unicode Encoding | + | |
- | Form (such as UTF-8), must receive explicit approval from the | + | |
- | document stream manager and will be allowed after the rules | + | |
- | for the common use cases are defined in the Style Guide. | + | |
- | + | ||
- | 7. The Submission and Publication formats need to permit | + | |
- | extending the set of metadata tags, for the addition of | + | |
- | labeled metadata. | + | |
- | created to make use of metadata tags consistent for the life | + | |
- | of the Series. | + | |
- | + | ||
- | 8. Graphics may include ASCII art and a more complex form to be | + | |
- | defined, such as SVG line art [SVG]. | + | |
- | not be accepted. | + | |
- | black-and-white to allow for monochrome displays, black-and- | + | |
- | white printing, and support for visual disabilities. | + | |
- | + | ||
- | 9. The Canonical format must be renderable into self-contained | + | |
- | Publication formats in order to be easily downloaded and read | + | |
- | offline. | + | |
- | + | ||
- | 10. Fixed-width fonts and non-reflowable text are required for | + | |
- | ASCII-art sections, source code examples, and other places | + | |
- | where strict alignment is required. | + | |
- | + | ||
- | 11. At least one Publication format must support readable print to | + | |
- | standard paper sizes. | + | |
- | + | ||
- | 12. The Canonical format should be structured to enable easy | + | |
- | program identification and parsing of code or specifications, | + | |
- | such as MIB modules and ABNF. | + |