asciidoctor-rfc 0.8.0 → 0.8.2

Sign up to get free protection for your applications and to get access to all the features.
Files changed (137) hide show
  1. checksums.yaml +4 -4
  2. data/.hound.yml +3 -0
  3. data/.rubocop.ribose.yml +65 -0
  4. data/.rubocop.tb.yml +640 -0
  5. data/.rubocop.yml +13 -30
  6. data/.travis.yml +8 -3
  7. data/CODE_OF_CONDUCT.md +46 -0
  8. data/Gemfile +8 -1
  9. data/LICENSE +21 -17
  10. data/README.adoc +471 -52
  11. data/asciidoctor-rfc.gemspec +14 -13
  12. data/lib/asciidoctor-rfc.rb +4 -4
  13. data/lib/asciidoctor/rfc/common/base.rb +304 -58
  14. data/lib/asciidoctor/rfc/common/front.rb +3 -3
  15. data/lib/asciidoctor/rfc/v2/base.rb +71 -82
  16. data/lib/asciidoctor/rfc/v2/blocks.rb +33 -10
  17. data/lib/asciidoctor/rfc/v2/converter.rb +0 -3
  18. data/lib/asciidoctor/rfc/v2/inline_anchor.rb +35 -20
  19. data/lib/asciidoctor/rfc/v2/lists.rb +11 -13
  20. data/lib/asciidoctor/rfc/v2/table.rb +11 -9
  21. data/lib/asciidoctor/rfc/v2/validate.rb +18 -724
  22. data/lib/asciidoctor/rfc/v3/base.rb +75 -102
  23. data/lib/asciidoctor/rfc/v3/blocks.rb +7 -9
  24. data/lib/asciidoctor/rfc/v3/converter.rb +0 -1
  25. data/lib/asciidoctor/rfc/v3/front.rb +14 -7
  26. data/lib/asciidoctor/rfc/v3/inline_anchor.rb +12 -9
  27. data/lib/asciidoctor/rfc/v3/lists.rb +31 -45
  28. data/lib/asciidoctor/rfc/v3/table.rb +2 -2
  29. data/lib/asciidoctor/rfc/v3/validate.rb +19 -2153
  30. data/lib/asciidoctor/rfc/v3/validate.rng +1 -1
  31. data/lib/asciidoctor/rfc/version.rb +1 -1
  32. data/rfc2629-other.ent +61 -0
  33. data/rfc2629-xhtml.ent +165 -0
  34. data/rfc2629.dtd +312 -0
  35. data/spec/asciidoctor/rfc/v2/biblio_spec.rb +9 -0
  36. data/spec/asciidoctor/rfc/v2/comments_spec.rb +67 -1
  37. data/spec/asciidoctor/rfc/v2/crossref_spec.rb +127 -5
  38. data/spec/asciidoctor/rfc/v2/date_spec.rb +24 -28
  39. data/spec/asciidoctor/rfc/v2/dlist_spec.rb +5 -5
  40. data/spec/asciidoctor/rfc/v2/image_spec.rb +2 -2
  41. data/spec/asciidoctor/rfc/v2/inline_formatting_spec.rb +28 -0
  42. data/spec/asciidoctor/rfc/v2/listing_spec.rb +2 -2
  43. data/spec/asciidoctor/rfc/v2/literal_spec.rb +4 -4
  44. data/spec/asciidoctor/rfc/v2/preamble_spec.rb +1 -1
  45. data/spec/asciidoctor/rfc/v2/quote_spec.rb +1 -1
  46. data/spec/asciidoctor/rfc/v2/references_spec.rb +210 -3
  47. data/spec/asciidoctor/rfc/v2/section_spec.rb +33 -0
  48. data/spec/asciidoctor/rfc/v2/table_spec.rb +40 -1
  49. data/spec/asciidoctor/rfc/v2/text_spec.rb +71 -14
  50. data/spec/asciidoctor/rfc/v2/ulist_spec.rb +1 -1
  51. data/spec/asciidoctor/rfc/v3/biblio_spec.rb +13 -0
  52. data/spec/asciidoctor/rfc/v3/comments_spec.rb +71 -0
  53. data/spec/asciidoctor/rfc/v3/crossref_spec.rb +7 -0
  54. data/spec/asciidoctor/rfc/v3/dlist_spec.rb +4 -4
  55. data/spec/asciidoctor/rfc/v3/literal_spec.rb +1 -1
  56. data/spec/asciidoctor/rfc/v3/preamble_spec.rb +1 -1
  57. data/spec/asciidoctor/rfc/v3/references_spec.rb +208 -3
  58. data/spec/asciidoctor/rfc/v3/series_info_spec.rb +1 -1
  59. data/spec/asciidoctor/rfc/v3/table_spec.rb +70 -1
  60. data/spec/examples/README.adoc +42 -6
  61. data/spec/examples/biblio-insert-v2.adoc +29 -0
  62. data/spec/examples/biblio-insert-v3.adoc +30 -0
  63. data/spec/examples/davies-template-bare-06.adoc +1 -0
  64. data/spec/examples/draft-iab-html-rfc-bis.xml.adoc +2300 -0
  65. data/spec/examples/draft-iab-html-rfc-bis.xml.orig +1999 -0
  66. data/spec/examples/draft-iab-html-rfc-bis.xml.txt +2298 -0
  67. data/spec/examples/draft-iab-rfc-framework-bis.xml.adoc +662 -0
  68. data/spec/examples/draft-iab-rfc-framework-bis.xml.orig +476 -0
  69. data/spec/examples/draft-ietf-core-block-xx.mkd.adoc +8 -33
  70. data/spec/examples/hoffmanv2.xml.adoc +4 -0
  71. data/spec/examples/mib-doc-template-xml-06.adoc +6 -8
  72. data/spec/examples/refs-v2-database.xml +86 -0
  73. data/spec/examples/refs-v2.adoc +49 -0
  74. data/spec/examples/refs-v2.xml +50 -0
  75. data/spec/examples/refs-v2/AsciiDoc.xml +8 -0
  76. data/spec/examples/refs-v2/AsciiMathML.xml +8 -0
  77. data/spec/examples/refs-v2/IETF-BibXML.xml +9 -0
  78. data/spec/examples/refs-v2/MathJax.xml +8 -0
  79. data/spec/examples/refs-v2/NroffEdit.xml +8 -0
  80. data/spec/examples/refs-v2/TeX-LaTeX.xml +8 -0
  81. data/spec/examples/refs-v2/abarth +17 -0
  82. data/spec/examples/refs-v2/asciidoctor-bibliography.xml +19 -0
  83. data/spec/examples/refs-v2/asciidoctor-manual.xml +11 -0
  84. data/spec/examples/refs-v2/asciidoctor-rfc.xml +18 -0
  85. data/spec/examples/refs-v2/asciidoctor.xml +10 -0
  86. data/spec/examples/refs-v2/draftr.xml +8 -0
  87. data/spec/examples/refs-v2/kramdown-rfc2629.xml +8 -0
  88. data/spec/examples/refs-v2/lyx2rfc.xml +8 -0
  89. data/spec/examples/refs-v2/mmark.xml +9 -0
  90. data/spec/examples/refs-v2/pandoc2rfc.xml +8 -0
  91. data/spec/examples/refs-v2/reference.RFC.2119.xml +7 -0
  92. data/spec/examples/refs-v2/reference.RFC.5385.xml +7 -0
  93. data/spec/examples/refs-v2/reference.RFC.7328.xml +7 -0
  94. data/spec/examples/refs-v2/reference.RFC.7749.xml +7 -0
  95. data/spec/examples/refs-v2/reference.RFC.7763.xml +7 -0
  96. data/spec/examples/refs-v2/reference.RFC.7764.xml +7 -0
  97. data/spec/examples/refs-v2/reference.RFC.7990.xml +7 -0
  98. data/spec/examples/refs-v2/reference.RFC.7991.xml +7 -0
  99. data/spec/examples/refs-v3-database.xml +137 -0
  100. data/spec/examples/refs-v3.adoc +57 -0
  101. data/spec/examples/refs-v3.xml +90 -0
  102. data/spec/examples/refs-v3/AsciiDoc.xml +8 -0
  103. data/spec/examples/refs-v3/AsciiMathML.xml +8 -0
  104. data/spec/examples/refs-v3/IETF-BibXML.xml +9 -0
  105. data/spec/examples/refs-v3/MathJax.xml +8 -0
  106. data/spec/examples/refs-v3/NroffEdit.xml +8 -0
  107. data/spec/examples/refs-v3/TeX-LaTeX.xml +8 -0
  108. data/spec/examples/refs-v3/abarth +17 -0
  109. data/spec/examples/refs-v3/asciidoctor-bibliography.xml +19 -0
  110. data/spec/examples/refs-v3/asciidoctor-manual.xml +11 -0
  111. data/spec/examples/refs-v3/asciidoctor-rfc.xml +18 -0
  112. data/spec/examples/refs-v3/asciidoctor.xml +10 -0
  113. data/spec/examples/refs-v3/draftr.xml +8 -0
  114. data/spec/examples/refs-v3/kramdown-rfc2629.xml +8 -0
  115. data/spec/examples/refs-v3/lyx2rfc.xml +8 -0
  116. data/spec/examples/refs-v3/mathrefs.xml +19 -0
  117. data/spec/examples/refs-v3/mmark.xml +9 -0
  118. data/spec/examples/refs-v3/pandoc2rfc.xml +8 -0
  119. data/spec/examples/refs-v3/reference.RFC.2119.xml +7 -0
  120. data/spec/examples/refs-v3/reference.RFC.5385.xml +7 -0
  121. data/spec/examples/refs-v3/reference.RFC.7328.xml +7 -0
  122. data/spec/examples/refs-v3/reference.RFC.7749.xml +7 -0
  123. data/spec/examples/refs-v3/reference.RFC.7763.xml +7 -0
  124. data/spec/examples/refs-v3/reference.RFC.7764.xml +7 -0
  125. data/spec/examples/refs-v3/reference.RFC.7990.xml +7 -0
  126. data/spec/examples/refs-v3/reference.RFC.7991.xml +7 -0
  127. data/spec/examples/rfc2100.md.adoc +57 -44
  128. data/spec/examples/rfc3514.md.adoc +1 -1
  129. data/spec/examples/rfc6350.adoc +701 -695
  130. data/spec/examples/rfc6350.txt.orig +3372 -0
  131. data/spec/examples/rfc6350_refs.xml +774 -0
  132. data/spec/examples/rfc748.md.adoc +1 -1
  133. data/spec/examples/rfc7511.md.adoc +3 -3
  134. data/spec/examples/skel.mkd.adoc +1 -0
  135. data/spec/examples/stupid-s.mkd.adoc +4 -4
  136. metadata +94 -8
  137. data/spec/examples/rfc6350.bib +0 -763
@@ -0,0 +1,476 @@
1
+ <?xml version="1.0" encoding="UTF-8"?>
2
+ <?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
3
+
4
+ <!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
5
+ <!ENTITY RFC5741 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5741.xml">
6
+ <!ENTITY RFC6949 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6949.xml">
7
+ <!ENTITY RFC4845 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4845.xml">
8
+ <!ENTITY RFC6635 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6635.xml">
9
+ <!ENTITY RFC7322 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7322.xml">
10
+ <!ENTITY I-D.iab-xml2rfc SYSTEM "http://xml2rfc.ietf.org/public/rfc/bibxml3/reference.I-D.iab-xml2rfc.xml">
11
+ <!ENTITY RFC7749 SYSTEM "http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7749.xml">
12
+ <!ENTITY I-D.iab-svg-rfc SYSTEM "http://xml2rfc.ietf.org/public/rfc/bibxml3/reference.I-D.iab-svg-rfc.xml">
13
+ <!ENTITY I-D.iab-rfc-use-of-pdf SYSTEM "http://xml2rfc.ietf.org/public/rfc/bibxml3/reference.I-D.iab-rfc-use-of-pdf.xml">
14
+ <!ENTITY I-D.iab-html-rfc SYSTEM "http://xml2rfc.ietf.org/public/rfc/bibxml3/reference.I-D.iab-html-rfc.xml">
15
+ <!ENTITY I-D.iab-rfc-plaintext SYSTEM "http://xml2rfc.ietf.org/public/rfc/bibxml3/reference.I-D.iab-rfc-plaintext.xml">
16
+ <!ENTITY I-D.iab-rfc-nonascii SYSTEM "http://xml2rfc.ietf.org/public/rfc/bibxml3/reference.I-D.iab-rfc-nonascii.xml">
17
+ <!ENTITY I-D.iab-rfc-css SYSTEM "http://xml2rfc.ietf.org/public/rfc/bibxml3/reference.I-D.iab-rfc-css.xml">
18
+
19
+ ]>
20
+
21
+ <rfc ipr="trust200902" docName="draft-iab-rfc-framework-06" category="info">
22
+
23
+ <?rfc toc="yes"?>
24
+
25
+ <front>
26
+ <title abbrev="RFC Format Framework">RFC Format Framework</title>
27
+
28
+ <author initials="H." surname="Flanagan" fullname="Heather Flanagan">
29
+ <organization>RFC Editor</organization>
30
+ <address>
31
+ <email>rse@rfc-editor.org</email>
32
+ <uri>http://orcid.org/0000-0002-2647-2220</uri>
33
+ </address>
34
+ </author>
35
+
36
+ <date year="2016" month="June" day="23"/>
37
+
38
+ <area>General</area>
39
+
40
+ <workgroup>Internet Architecture Board</workgroup>
41
+
42
+ <abstract>
43
+
44
+
45
+ <t>The canonical format for the RFC Series has been plain-text, ASCII-encoded for several decades. After extensive community discussion and debate, the RFC Editor will be transitioning to XML as the canonical format using the XML2RFC version 3 vocabulary. Different publication formats will be rendered from that base document. These changes are intended to increase the usability of the RFC Series by offering documents that match the needs of a wider variety of stakeholders. With these changes, however, comes an increase in complexity for authors, consumers, and the publisher of RFCs. This document serves as the framework that describes the problems being solved and summarizes the many documents that capture the specific requirements for each aspect of the change in format.</t>
46
+
47
+ </abstract>
48
+
49
+ <note title="Editorial Note (To be removed by RFC Editor)">
50
+ <t>Discussion of this draft takes place on the rfc-interest mailing list (rfc-interest@rfc-editor.org), which has its home page at https://www.rfc-editor.org/mailman/listinfo/rfc-interest.</t>
51
+ </note>
52
+
53
+
54
+
55
+
56
+ </front>
57
+
58
+ <middle>
59
+
60
+
61
+ <section anchor="introduction" title="Introduction">
62
+
63
+ <t>"RFC Series Format Requirements and Future Development" discussed the need for additional features within RFCs such as non-ASCII characters to respect author names, more advanced artwork than ASCII art, and documents that could display properly on a wide variety of devices <xref target="RFC6949"/>. Based on the discussions with the IETF community as well as other communities of interest, the RFC Series Editor decided to explore a change to the format of the Series <xref target="XML-ANNOUNCE"/>. This document serves as the framework that describes the problems being solved and summarizes the documents created to-date that capture the specific requirements for each aspect of the change in format. </t>
64
+
65
+ <t>Key changes to the publication of RFCs are highlighted, and a transition plan that will take the Series from a plain-text, ASCII-only format to the new formats is described on the rfc-interest mailing list <xref target="RFC-INTEREST"/>.</t>
66
+
67
+ <t>This document is concerned with the production of RFCs, focusing on the published formats. It does not address any changes to the processes each stream uses to develop and review their submissions (specifically, how Internet-Drafts will be developed). While I-Ds have a similar set of issues and concerns, directly addressing those issues for I-Ds will be discussed within each document stream.</t>
68
+
69
+ <t>The details described in this document are expected to change based on experience gained in implementing the RFC Production Center's toolset. Revised documents will be published capturing those changes as the toolset is completed. Other implementers must not expect those changes to remain backwards-compatible with the details described this document.</t>
70
+
71
+
72
+ </section>
73
+ <section anchor="problem-statement" title="Problem Statement">
74
+
75
+ <t>There are nearly three billion people connected to the Internet, and individuals from 45 countries or more regularly attending IETF meetings over the last five years <xref target="ISTATS"/>. The Internet is now global, and while the world has changed from when the first RFCs were published, the Series remains critical to defining protocols, standards, best practices, and more for this global network that continues to grow. In order to make RFCs easily viewable to the largest number of people possible, across a wide array of devices, and to respect the diversity of authors and reference materials while still recognizing the archival aspects of the Series, it is time to update the tightly prescribed format of the RFC Series.</t>
76
+
77
+ <t>All changes to the format of the RFC Series must consider the requirements of a wide set of communities, over an extended length of time. For example, existing authors and implementers, lawyers that argue Intellectual Property Rights (IPR), educators, managers, and policy-makers that need to know what to list in potential RFPs for their organizations, all have preferences and requirements for their specific needs. The immediate needs of today's communities must be balanced with the needs for long-term archival storage. </t>
78
+
79
+ </section>
80
+ <section anchor="terminology" title="Terminology">
81
+
82
+ <t>The following terminology is used as described in RFC 6949:</t>
83
+
84
+ <t><list style='empty'>
85
+ <t>ASCII: Coded Character Set - 7-bit American Standard Code for Information Interchange, ANSI X3.4-1986</t>
86
+ </list></t>
87
+
88
+ <t><list style='empty'>
89
+ <t>Canonical format: the authorized, recognized, accepted, and archived version of the document</t>
90
+ </list></t>
91
+
92
+ <t><list style='empty'>
93
+ <t>Metadata: information associated with a document so as to provide, for example, definitions of its structure, or of elements within the document such as its topic or author</t>
94
+ </list></t>
95
+
96
+ <t><list style='empty'>
97
+ <t>Publication format: display and distribution format as it may be read or printed after the publication process has completed</t>
98
+ </list></t>
99
+
100
+ <t><list style='empty'>
101
+ <t>Reflowable text: text that automatically wraps to the next line in a document as the user moves the margins of the text, either by resizing the window or changing the font size</t>
102
+ </list></t>
103
+
104
+ <t><list style='empty'>
105
+ <t>Revisable format: the format that will provide the information for conversion into a Publication format; it is used or created by the RFC Editor</t>
106
+ </list></t>
107
+
108
+ <t><list style='empty'>
109
+ <t>Submission format: the format submitted to the RFC Editor for editorial revision and publication</t>
110
+ </list></t>
111
+
112
+ </section>
113
+ <section anchor="overview-of-the-decision-making-process" title="Overview of the Decision Making Process">
114
+
115
+ <t>Requirements, use cases, concerns, and suggestions were collected from the communities of interest at every stage of the RFC format update project. Input was received through the rfc-interest mailing list, as well as in several face-to-face sessions at IETF meetings. Regular conversations were held with the IETF, IRTF, IAB, and IAOC chairs, and the Independent Stream Editor, to discuss high-level stream requirements. Updates regarding the status of the project were provided to the IETF community during the IETF Technical Plenary as well as Format BoFs or IAB sessions at IETF 84, IETF 85, IETF 88, IETF 89, and IETF 90 <xref target="IETF84"/> <xref target="IETF85"/> <xref target="IETF88"/> <xref target="IETF89"/> <xref target="IETF90"/>. </t>
116
+
117
+ <t>The first document published, RFC 6949, provided the first solid documentation on what the requirements were for the Series and in effect was the output from the first year of discussion on the topic of RFC format. That RFC, as with all of the RFCs that informed the format update work, was published as an IAB stream document, thus following the process described in RFC 4845, "Process for Publication of IAB RFCs" <xref target="RFC4845"/>. </t>
118
+
119
+ <t>After the high-level requirements were published, the RFC Series Editor (RSE) brought together an RFC Format Design Team to start working out the necessary details to develop the code needed to create new and changed formats. The design team discussed moving away from the existing xml2rfc vocabulary, but with such a strong existing support base within the community and no clear value with other XML vocabularies or schemas, the decision was made to work with the XML2RFC version 2 (xml2rfc v2) model and use it as the base for the new format world <xref target="RFC7749"/>. Part of this discussion included a decision to stop using an XML document type definition (DTD) in favor of a Regular Language for XML Next General (Relax NG) model using a defined vocabulary. While the bi-weekly calls for this team were limited to Design Team members, review of the decisions as documented in the drafts produced by this team were done publicly through requests for feedback on the rfc-interest mailing list. Several of the drafts produced by the Design Team, including the xml2rfc v2 and v3 drafts and the SVG profile drafts, were sent through an early GenART review before starting the process to be accepted as an IAB stream draft <xref target="GEN-ART"/> <xref target="I-D.iab-xml2rfc"/>. </t>
120
+
121
+ <t>While the IETF community provided the majority of input on the process, additional outreach opportunities were sought to gain input from an even broader audience. Informal discussions were held with participants at several International Association of Scientific, Technical, and Medical Publisher events, and presentations made at technical conferences such as the TERENA Networking Conference 2014 and NORDUnet 2014 <xref target="TNC2014"/> <xref target="NDN2014"/>.</t>
122
+
123
+ <t>In order to respond to concerns regarding responses to subpoenas and to understand the requirements for lawyers, advice was requested from the IETF Trust legal team regarding what format or formats would be considered reasonable when responding to a subpoena request for an RFC.</t>
124
+
125
+ <t>Given that several other standards development organizations (SDOs) do not offer plain-text documents, and in fact may offer more than one format for their standards, informal input was sought from them regarding their experience with supporting one or more non-plain-text formats for their standards.</t>
126
+
127
+ <t>Finally, the entire process was reviewed regularly with the RFC Series Oversight Committee and regular updates provided to the IAB and IESG <xref target="RSOC"/>. They have offered support and input throughout the process.</t>
128
+
129
+ <t>Where consensus was not reached during the process, the RSE made any necessary final decisions, as per the guidance in RFC 6635, "RFC Editor Model (Version 2)" <xref target="RFC6635"/>.</t>
130
+
131
+ </section>
132
+ <section anchor="key-changes" title="Key Changes">
133
+
134
+ <t>At the highest level, the changes being made to the RFC Format involve breaking away from a pure-ASCII plain text and moving to canonical format that includes all the information required for rendering a document into a wide variety of publication formats. The RFC Editor will become responsible for more than just the plain-text file and the PDF-from-text format created at time of publication; they will be creating several different formats in order to meet the diverse requirements of the community.</t>
135
+
136
+ <t>The final XML file produced by the RFC Editor will be considered the canonical format for RFCs; it is the lowest common denominator that holds all the information intended for an RFC. PDF/A-3 will be the publication format offered in response to subpoenas for RFCs published through this new process, and will be developed with an eye towards long-term archival storage. HTML will be the focus of providing the most flexible set of features for an RFC, including JavaScript to provide pointers to errata and other metadata. Plain-text will continue to be offered in order to support existing tool chains where practicable and the individuals who prefer to read RFCs in this format.</t>
137
+
138
+
139
+ </section>
140
+
141
+ <section anchor="canonical-format-documents" title="Canonical Format Documents">
142
+ <section anchor="xml" title="XML for RFCs">
143
+
144
+ <t>Key points regarding the XML format:</t>
145
+
146
+ <t><list style='symbols'>
147
+ <t>The canonical format for RFCs is XML using the XML2RFC version 3 (xml2rfc v3) vocabulary. This file must contain all information necessary to render a variety of formats; any question about what was intended in the publication will be answered from this format.</t>
148
+ <t>Authors may submit drafts in xml2rfc v2 vocabulary, but the final publication will convert that to xml2rfc v3 vocabulary.</t>
149
+ <t>SVG is supported and will be embedded in the final XML file.</t>
150
+ <t>There will be automatically generated identifiers for sections, paragraphs, figures, and tables in the final XML file.</t>
151
+ <t>The XML file will not contain any xml2rfc v3 vocabulary elements or attributes that have been marked deprecated. </t>
152
+ <t>A Document Type Definition (DTD) will no longer be used. The grammar will be defined using RelaxNG.</t>
153
+ <t>The final XML file will contain, verbatim, the appropriate boilerplate as applicable at time of publication specified by RFC 5741 or its successors <xref target="RFC5741"/>.</t>
154
+ <t>The final XML will be self-contained with all the information known at publication time. For instance, all features that reference externally-defined input will be expanded. This includes all uses of xinclude, src attributes (such as in &lt;artwork&gt; or &lt;sourcecode&gt; elements), include-like processing instructions, and externally defined entities.</t>
155
+ <t>The final XML will not contain comments or processing instructions.</t>
156
+ <t>The final XML will not contain src attributes for &lt;artwork&gt; or
157
+ &lt;sourcecode&gt; elements.</t>
158
+ </list></t>
159
+
160
+ <t><xref target="RFC7749"/> describes the xml2rfc v2 vocabulary. While in wide use today, this vocabulary previously had not been formally documented. In order to understand what needed to change in the vocabulary to allow for a more simple experience and additional features for authors, the current vocabulary needed to be fully described. This document will be obsoleted by the RFC published from draft-iab-xml2rfc.</t>
161
+
162
+ <t><xref target="I-D.iab-xml2rfc"/> Describes the xml2rfc v3 vocabulary. The design goals in this vocabulary were to make the vocabulary more intuitive for authors, and to expand the features to support the changes being made in the publication process. This draft, when published, will obsolete the RFC 7749.</t>
163
+
164
+ </section>
165
+ </section>
166
+ <section anchor="publication-format-documents" title="Publication Format Documents">
167
+
168
+ <section anchor="html" title="HTML">
169
+ <t><xref target="I-D.iab-html-rfc"/> - Describes the semantic HTML that will be produced by the RFC Editor from the xml2rfc v3 files.</t>
170
+
171
+ <t>Key points regarding the HTML output:</t>
172
+
173
+ <t><list style='symbols'>
174
+ <t>The HTML will be rendered from the XML file; it will not be derived from the plain-text publication format.</t>
175
+ <t>The body of the document will use a subset of HTML. The documents will include CSS for default visual presentation; it can be overwritten by a local CSS file.</t>
176
+ <t>SVG is supported and will be included in the HTML file.</t>
177
+ <t>Text will be reflowable.</t>
178
+ <t>JavaScript will be supported on a limited basis. It will not be permitted to overwrite or change any text present in the rendered html. It may, on a limited basis, add additional text that provides post-publication metadata or pointers if warranted. All such text will be clearly marked as additional.</t>
179
+ </list></t>
180
+
181
+
182
+ </section>
183
+ <section anchor="pdf" title="PDF">
184
+ <t><xref target="I-D.iab-rfc-use-of-pdf"/> - Describes the tags and profiles that will be used to create the new PDF format, including both the internal structure and the visible layout of the file. A review of the different versions of PDF is offered, with a recommendation of what PDF standard should apply to RFCs.</t>
185
+
186
+ <t>Key points regarding the PDF output:</t>
187
+
188
+ <t><list style='symbols'>
189
+ <t>The PDF file will be rendered from the XML file; it will not be derived from the plain-text publication format.</t>
190
+ <t>The PDF publication format will conform to the PDF/A-3 standard and will embed the canonical XML source.</t>
191
+ <t>The PDF will look more like the HTML publication format than the plain-text publication format.</t>
192
+ <t>The PDF will include a rich set of tags and metadata within the document</t>
193
+ <t>SVG is supported and will be included in the PDF file.</t>
194
+ </list></t>
195
+
196
+ </section>
197
+ <section anchor="plain-text" title="Plain Text">
198
+ <t><xref target="I-D.iab-rfc-plaintext"/> - Describes the details of the plain text format, focusing in particular on what is changing from the existing plain-text output.</t>
199
+
200
+ <t>Key points regarding the plain-text output:</t>
201
+
202
+ <t><list style='symbols'>
203
+ <t>The plain-text document will no longer be the canonical version of an RFC.
204
+ </t>
205
+ <t>The plain-text format will be UTF-8 encoded; non-ASCII characters will be allowed.</t>
206
+ <t>A Byte Order Mark (BOM) will be added at the start of each file.</t>
207
+ <t>Widow and orphan control for the plain-text publication format will not have priority for the developers creating the rendering code <xref target="TYPOGRAPHY"/>.</t>
208
+ <t>Authors may choose to have pointers to line art in other publication formats in place of ASCII art in the .txt file.</t>
209
+ <t>Both a paginated and an unpaginated plain-text file will be created.</t>
210
+ <t>Running headers and footers will not be used.</t>
211
+ </list></t>
212
+
213
+ </section>
214
+ <section anchor="potential-future-publication-formats" title="Potential Future Publication Formats">
215
+
216
+ <section anchor="epub" title="EPUB">
217
+ <t>This format is intended for use by ebook readers and will be available for RFCs after the requirements have been defined. No draft is currently available.</t>
218
+
219
+ </section>
220
+ </section>
221
+ </section>
222
+ <section anchor="figures-and-artwork" title="Figures and Artwork">
223
+
224
+ <section anchor="svg" title="SVG">
225
+ <t><xref target="I-D.iab-svg-rfc"/> Describes the profile for SVG line art. SVG is an XML-based vocabulary for creating line drawings; SVG information will be embedded within the canonical XML at time of publication.</t>
226
+
227
+ </section>
228
+ </section>
229
+ <section anchor="content-and-page-layout" title="Content and Page Layout">
230
+
231
+ <section anchor="non-ascii-characters" title="Non-ASCII Characters">
232
+ <t>There are security and readability implications to moving outside the ASCII range of characters. <xref target="I-D.iab-rfc-nonascii"/> focuses on exactly where and how non-ASCII characters may be used in an RFC, with an eye towards keeping the documents as secure and readable as possible given the information that needs to be expressed.</t>
233
+
234
+ </section>
235
+ <section anchor="style-guide" title="Style Guide">
236
+ <t>The RFC Style Guide <xref target="RFC7322"/> was revised to remove as much page formatting information as possible, focusing instead on grammar, structure, and content of RFCs. Some of the changes recommended, however, informed the XML v3 vocabulary.</t>
237
+
238
+ </section>
239
+ <section anchor="css-requirements" title="CSS Requirements">
240
+ <t><xref target="I-D.iab-rfc-css"/> describe how the CSS classes mentioned in the HTML format draft, "HyperText Markup Language Request for Comments Format", should be used to create an accessible and responsive design for the HTML format.</t>
241
+
242
+ </section>
243
+ </section>
244
+ <section anchor="transition-plan" title="Transition Plan">
245
+
246
+ <section anchor="tooldev-phase" title="Statement of Work and RFP for Tool Development">
247
+ <t>Existing tools for the creation of RFCs will need to be updated, and new tools created, to implement the updated format. As the requirements gathering effort, described in the various documents described earlier int this draft, finishes the bulk of the work, the Tools Development Team of the IETF will work with the RSE to develop Statements of Work (SoWs). Those SoWs will first be reviewed within the Tools Development Team, the Tools Management Committee, and go out for a public comment period. After public review, the SoWs will be attached to a Request for Proposal (RFP) and posted as per the IASA bid process <xref target="IASA-RFP"/>.</t>
248
+
249
+ <t>Once bids have been received, reviewed, and awarded, coding will begin.</t>
250
+
251
+ </section>
252
+ <section anchor="testing-phase" title="Testing and Transition">
253
+
254
+ <t>During the I-D review and approval process, authors and stream-approving bodies will select drafts to run through the proposed new publication process. While the final RFCs published during this time will continue as plain-text and immutable once published, the feedback process is necessary to bootstrap initial testing. These early tests will target finding issues with the proposed xml2rfc v3 vocabulary that result in poorly formed publication formats as well as issues that prevent proper review of submitted drafts.</t>
255
+
256
+ <t>Feedback will result in regular iteration of the basic code and XML vocabulary. In order to limit the amount of time the RFC Production Center (RPC) spends on testing and QA, their priority will be to edit and publish documents; therefore, community assistance will be necessary to help move this stage along. A mailing list and experimental source directory on the RFC Editor website will be created for community members willing to assist in the detailed review of the XML and publication formats. Editorial checks of the publication formats by the community are out of scope; the focus will be the QA of each available output, checking for inconsistencies across formats.</t>
257
+
258
+ <t>The purpose of testing phase is to work with the community to identify and fix bugs in the process and the code, before producing canonical, immutable XML, and to collect additional feedback on the usability of the new publication formats.</t>
259
+
260
+ <t>Any modifications to the draft review process, up to and including AUTH48, will happen with the community and the stream approving bodies as we learn more about the features and outputs of the new publication tools. Defining those processes is out of scope for this document.</t>
261
+
262
+ <t>Success will be measured by the closure of all bugs which had been identified by the RPC and the Tools Development team as fatal and consensus on the readiness of the XML vocabulary and final XML files for publication. The actual rendering engine can go through further review and iteration, as the publication formats may be republished as needed.</t>
263
+
264
+ <t>Authors are not required to submit their approved drafts in an XML format, though they are strongly encouraged to do so; plain-text will also remain an option for the foreseeable future. However, documents submitted as plain-text cannot include such features as SVG artwork. The RPC will generate an XML file if necessary for basic processing and subsequent rendering into the approved output formats.</t>
265
+
266
+ <t>A known risk at this point of the transition is the difficulty in quantifying the resources required from the RPC. This phase will require more work on the part of the RPC to support both old and new publication processes for at least six months. There is potential for confusion as consumers of RFCs find some documents published at this time with a full set of outputs, while other documents only have plain text. There may be a delay in publication as new bugs are found that must be fixed before the files can be converted into the canonical format and associated publication formats.</t>
267
+
268
+ <t>Final success of the transition will be measured by the closure of all bugs which had been identified by the RPC and the Tools Development team as major or critical. There must also be rough consensus from the community regarding the utility of the new formats.</t>
269
+
270
+ </section>
271
+ <section anchor="completion" title="Completion">
272
+ <t>Authors may submit XML (preferred) or plain text. The XML drafts submitted for publication will be converted to canonical XML format and published with all available publication formats. All authors will be expected to review the final documents as consistent with the evolving procedures for reviewing drafts.</t>
273
+
274
+ <t>Success for this phase will be measured by a solid understanding by the RSE and the IAOC of the necessary costs and resources required for long-term support of the new format model.</t>
275
+
276
+ </section>
277
+ </section>
278
+ <section anchor="iana-considerations" title="IANA Considerations">
279
+
280
+ <t>This document has no actions for IANA.</t>
281
+
282
+ </section>
283
+ <section anchor="security-considerations" title="Security Considerations">
284
+
285
+ <t>Changing the format for RFCs involves modifying a great number of components to publication. Understanding those changes and the implications for the entire tool chain is critical so as to avoid unintended bugs that would allow unintended changes to text. Unintended changes to text could in turn corrupt a standard, practice or critical piece of information about a protocol.</t>
286
+
287
+ </section>
288
+ <section anchor="acknowledgements" title="Acknowledgements">
289
+ <t>With many thanks to the RFC Format Design Team for their efforts in making this transition successful: Nevil Brownlee (ISE), Tony Hansen, Joe Hildebrand, Paul Hoffman, Ted Lemon, Julian Reschke, Adam Roach, Alice Russo, Robert Sparks (Tools Team liaison), and Dave Thaler.</t>
290
+
291
+ </section>
292
+
293
+ <section anchor="changelog" title="Appendix - Change log">
294
+ <t>To be removed by RFC Editor</t>
295
+ <section anchor="change06" title="draft-iab-rfc-framework-05 to -06">
296
+ <t>xml2rfcv2: minor clarifications</t>
297
+ </section>
298
+ <section anchor="change05" title="draft-iab-rfc-framework-04 to -05">
299
+ <t>Introduction: minor clarifications</t>
300
+ <t>Updated references</t>
301
+ </section>
302
+ <section anchor="change04" title="draft-iab-rfc-framework-03 to -04">
303
+ <t>Introduction: editorial changes</t>
304
+ <t>Clarified that submitted plain text will be converted to XML by the RPC; the XML will be used to render all output formats. </t>
305
+ </section>
306
+ <section anchor="change03" title="draft-iab-rfc-framework-02 to -03">
307
+ <t>HTML output: clarified expectations around use of JavaScript.
308
+ </t>
309
+ </section>
310
+ <section anchor="change02" title="draft-iab-rfc-framework-01 to -02">
311
+ <t>Introduction: Removed some unnecessary history.
312
+ </t>
313
+ </section>
314
+ <section anchor="change01" title="draft-iab-rfc-framework-00 to -01">
315
+ <t>Decision Making Process: noted taht other XML schemas and vocabularies were considered by the design team</t>
316
+ <t>XML for RFCs: "boilerplate at time of publication"</t>
317
+ <t>HTML: clarified that JavaScript should not impact readability of the document as it looked at time of publication</t>
318
+ </section>
319
+ </section>
320
+
321
+ </middle>
322
+
323
+ <back>
324
+
325
+ <references title='Normative References'>
326
+
327
+ &RFC6949;
328
+ &RFC7749;
329
+ &I-D.iab-xml2rfc;
330
+ &I-D.iab-svg-rfc;
331
+ &I-D.iab-html-rfc;
332
+ &I-D.iab-rfc-use-of-pdf;
333
+ &I-D.iab-rfc-plaintext;
334
+ &I-D.iab-rfc-nonascii;
335
+ &I-D.iab-rfc-css;
336
+
337
+ </references>
338
+
339
+ <references title='Informative References'>
340
+
341
+ &RFC4845;
342
+ &RFC5741;
343
+ &RFC6635;
344
+ &RFC7322;
345
+ <reference anchor="GEN-ART" target="http://www.ietf.org/iesg/directorate/gen-art.html">
346
+ <front>
347
+ <title>General Area Review Team (Gen-ART)</title>
348
+ <author>
349
+ <organization>IETF</organization>
350
+ </author>
351
+ <date year="n.d."/>
352
+ </front>
353
+ </reference>
354
+ <reference anchor="IASA-RFP" target="http://iaoc.ietf.org/rfps-rfis.html">
355
+ <front>
356
+ <title>RFPs and RFIs</title>
357
+ <author>
358
+ <organization>IETF Administrative Support Activity</organization>
359
+ </author>
360
+ <date year="n.d." />
361
+ </front>
362
+ </reference>
363
+ <reference anchor="IETF84" target="http://www.ietf.org/proceedings/84/rfcform.html">
364
+ <front>
365
+ <title>IETF 84 Proceedings: RFC Format (rfcform)</title>
366
+ <author initials="H." surname="Flanagan" fullname="Heather Flanagan">
367
+ <organization></organization>
368
+ </author>
369
+ <date year="n.d."/>
370
+ </front>
371
+ </reference>
372
+ <reference anchor="IETF85" target="http://www.ietf.org/proceedings/85/rfcform.html">
373
+ <front>
374
+ <title>IETF 85 Proceedings: RFC Format (rfcform)</title>
375
+ <author initials="H." surname="Flanagan" fullname="Heather Flanagan">
376
+ <organization></organization>
377
+ </author>
378
+ <date year="n.d."/>
379
+ </front>
380
+ </reference>
381
+ <reference anchor="IETF88" target="http://www.ietf.org/proceedings/88/rfcform.html">
382
+ <front>
383
+ <title>IETF 88 Proceedings: RFC Format (rfcform)</title>
384
+ <author initials="H." surname="Flanagan" fullname="Heather Flanagan">
385
+ <organization></organization>
386
+ </author>
387
+ <date year="n.d."/>
388
+ </front>
389
+ </reference>
390
+ <reference anchor="IETF89" target="http://www.ietf.org/proceedings/89/rfcform.html">
391
+ <front>
392
+ <title>IETF 89 Proceedings: RFC Format (rfcform)</title>
393
+ <author initials="H." surname="Flanagan" fullname="Heather Flanagan">
394
+ <organization></organization>
395
+ </author>
396
+ <date year="n.d."/>
397
+ </front>
398
+ </reference>
399
+ <reference anchor="IETF90" target="http://www.ietf.org/proceedings/90/rfcform.html">
400
+ <front>
401
+ <title>IETF 90 Proceedings: RFC Format (rfcform)</title>
402
+ <author initials="H." surname="Flanagan" fullname="Heather Flanagan">
403
+ <organization></organization>
404
+ </author>
405
+ <date year="n.d."/>
406
+ </front>
407
+ </reference>
408
+ <reference anchor="ISTATS" target="http://www.internetlivestats.com/internet-users/">
409
+ <front>
410
+ <title>Internet Live Stats</title>
411
+ <author >
412
+ <organization></organization>
413
+ </author>
414
+ <date year="n.d."/>
415
+ </front>
416
+ </reference>
417
+ <reference anchor="NDN2014" target="https://events.nordu.net/display/NORDU2014/BoF%27s+and+side+meetings">
418
+ <front>
419
+ <title>28th NORDUnet Conference 2014</title>
420
+ <author>
421
+ <organization></organization>
422
+ </author>
423
+ <date year="2014"/>
424
+ </front>
425
+ </reference>
426
+ <reference anchor="RFC-INTEREST" target="https://www.rfc-editor.org/mailman/listinfo/rfc-interest">
427
+ <front>
428
+ <title>rfc-interest -- A list for discussion of the RFC series and RFC Editor functions.</title>
429
+ <author >
430
+ <organization>RFC Editor</organization>
431
+ </author>
432
+ <date year="n.d."/>
433
+ </front>
434
+ </reference>
435
+ <reference anchor="RSOC" target="http://www.iab.org/activities/programs/rfc-editor-program/">
436
+ <front>
437
+ <title>RFC Editor Program: The RSOC</title>
438
+ <author >
439
+ <organization>IAB</organization>
440
+ </author>
441
+ <date year="n.d."/>
442
+ </front>
443
+ </reference>
444
+ <reference anchor="TNC2014" target="https://tnc2014.terena.org/core/presentation/84">
445
+ <front>
446
+ <title>IETF Update - 'What's Hot?' - RFC Update</title>
447
+ <author initials="H." surname="Flanagan" fullname="Heather Flanagan">
448
+ <organization></organization>
449
+ </author>
450
+ <date year="n.d."/>
451
+ </front>
452
+ </reference>
453
+ <reference anchor="TYPOGRAPHY" target="http://practicaltypography.com/widow-and-orphan-control.html">
454
+ <front>
455
+ <title>Butterick's Practical Typography</title>
456
+ <author initials="M." surname="Butterick" fullname="Matthew Butterick"/>
457
+ <date year="n.d."/>
458
+ </front>
459
+ </reference>
460
+ <reference anchor="XML-ANNOUNCE" target="http://www.rfc-editor.org/pipermail/rfc-interest/2013-May/005584.html">
461
+ <front>
462
+ <title>Subject: [rfc-i] Direction of the RFC Format Development effort</title>
463
+ <author >
464
+ <organization></organization>
465
+ </author>
466
+ <date year="n.d."/>
467
+ </front>
468
+ </reference>
469
+
470
+
471
+ </references>
472
+
473
+
474
+
475
+ </back>
476
+ </rfc>