RFC 7991: The "xml2rfc" Version 3 Vocabulary (original) (raw)

Internet Architecture Board (IAB) P. Hoffman Request for Comments: 7991 ICANN Obsoletes: 7749 December 2016 Category: Informational ISSN: 2070-1721

               The "xml2rfc" Version 3 Vocabulary

Abstract

This document defines the "xml2rfc" version 3 vocabulary: an XML-based language used for writing RFCs and Internet-Drafts. It is heavily derived from the version 2 vocabulary that is also under discussion. This document obsoletes the v2 grammar described in RFC 7749.

Status of This Memo

This document is not an Internet Standards Track specification; it is published for informational purposes.

This document is a product of the Internet Architecture Board (IAB) and represents information that the IAB has deemed valuable to provide for permanent record. It represents the consensus of the Internet Architecture Board (IAB). Documents approved for publication by the IAB are not a candidate for any level of Internet Standard; see Section 2 of RFC 7841.

Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7991.

Copyright Notice

Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.

Hoffman Informational [Page 1] RFC 7991 The "xml2rfc" Version 3 Vocabulary December 2016

Table of Contents

  1. Introduction ....................................................5 1.1. Expected Updates to the Specification ......................5 1.2. Design Criteria for the Changes in v3 ......................6 1.3. Differences from v2 to v3 ..................................6 1.3.1. New Elements in v3 ..................................6 1.3.2. New Attributes for Existing Elements ................7 1.3.3. Elements and Attributes Deprecated from v2 ..........8 1.3.4. Additional Changes from v2 ..........................9 1.4. Syntax Notation ...........................................10
  2. Elements .......................................................10 2.1. ................................................11 2.2.
    .................................................12 2.3. ..............................................12 2.4. ....................................................13 2.5. .................................................13 2.6.

Hoffman Informational [Page 2] RFC 7991 The "xml2rfc" Version 3 Vocabulary December 2016

  2.36. <phone> ..................................................43
  2.37. <postal> .................................................43
  2.38. <postalLine> .............................................44
  2.39. <refcontent> .............................................44
  2.40. <reference> ..............................................45
  2.41. <referencegroup> .........................................46
  2.42. <references> .............................................46
  2.43. <region> .................................................47
  2.44. <relref> .................................................47
  2.45. <rfc> ....................................................51
  2.46. <section> ................................................54
  2.47. <seriesInfo> .............................................57
  2.48. <sourcecode> .............................................59
  2.49. <street> .................................................61
  2.50. <strong> .................................................61
  2.51. <sub> ....................................................62
  2.52. <sup> ....................................................63
  2.53. <t> ......................................................64
  2.54. <table> ..................................................66
  2.55. <tbody> ..................................................67
  2.56. <td> .....................................................67
  2.57. <tfoot> ..................................................69
  2.58. <th> .....................................................69
  2.59. <thead> ..................................................71
  2.60. <title> ..................................................72
  2.61. <tr> .....................................................72
  2.62. <tt> .....................................................73
  2.63. <ul> .....................................................74
  2.64. <uri> ....................................................75
  2.65. <workgroup> ..............................................75
  2.66. <xref> ...................................................75
  1. Elements from v2 That Have Been Deprecated .....................78 3.1. .......................................................78 3.2. ...............................................78 3.3. ..................................................79 3.4. ....................................................79 3.5. ...............................................80 3.6. ................................................81 3.7. ...................................................81 3.8. ...............................................82 3.9. ...................................................83 3.10. .................................................84
  2. SVG ............................................................84
  3. Use of CDATA Structures and Escaping ...........................85
  4. Internationalization Considerations ............................85
  5. Security Considerations ........................................85

Hoffman Informational [Page 3] RFC 7991 The "xml2rfc" Version 3 Vocabulary December 2016

  1. IANA Considerations ............................................86 8.1. Internet Media Type Registration ..........................86 8.2. Link Relation Registration ................................87
  2. References .....................................................88 9.1. Normative References ......................................88 9.2. Informative References ....................................88 Appendix A. Front-Page ("Boilerplate") Generation .................93 A.1. The "ipr" Attribute ........................................93 A.1.1. Current Values: "*trust200902" .........................93 A.1.2. Historic Values ........................................95 A.2. The "submissionType" Attribute .............................96 A.3. The "consensus" Attribute ..................................97 Appendix B. The v3 Format and Processing Tools ....................98 B.1. Including External Text with XInclude ......................99 B.2. Anchors and IDs ...........................................100 B.2.1. Overlapping Values ....................................100 B.3. Attributes Controlled by the Prep Tool ....................102 Appendix C. RELAX NG Schema ......................................104 Appendix D. Schema Differences from v2 ...........................127 IAB Members at the Time of Approval ..............................151 Acknowledgements .................................................151 Author's Address .................................................151

Hoffman Informational [Page 4] RFC 7991 The "xml2rfc" Version 3 Vocabulary December 2016

  1. Introduction

This document describes version 3 ("v3") of the "xml2rfc" vocabulary: an XML-based language ("Extensible Markup Language" [XML]) used for writing RFCs [RFC7322] and Internet-Drafts [IDGUIDE].

This document obsoletes the version 2 vocabulary ("v2") [RFC7749], which contains the extended language definition. That document in turn obsoletes the original version ("v1") [RFC2629]. This document directly copies the material from [RFC7749] where possible.

The v3 format will be used as part of the new RFC Series format described in [RFC6949]. The new format will be handled by one or more new tools for preparing the XML and converting it to other representations. Features of the expected tools are described in Appendix B. That section defines some terms used throughout this document, such as "prep tool" and "formatter".

Note that the vocabulary contains certain constructs that might not be used when generating the final text; however, they can provide useful data for other uses (such as index generation, populating a keyword database, or syntax checks).

In this document, the term "format" is used when describing types of documents, primarily XML and HTML. The term "representation" is used when talking about a specific instantiation of a format, such as an XML document or an HTML document that was created by an XML document.

1.1. Expected Updates to the Specification

Non-interoperable changes in later versions of this specification are likely based on experience gained in implementing the new publication toolsets. Revised documents will be published capturing those changes as the toolsets are completed. Other implementers must not expect those changes to remain backwards-compatible with the details described in this document.

Hoffman Informational [Page 5] RFC 7991 The "xml2rfc" Version 3 Vocabulary December 2016

1.2. Design Criteria for the Changes in v3

The design criteria of the changes from v2 to v3 are as follows:

o The intention is that starting and editing a v3 document will be easier than for a v2 document.

o There will be good v2-to-v3 conversion tools for when an author wants to change versions.

o There are no current plans to make v3 XML the required submission format for drafts or RFCs. That might happen eventually, but it is likely to be years away.

There is a desire to keep as much of the v2 grammar as makes sense within the above design criteria and not to make gratuitous changes to the v2 grammar. Another way to say this is "we would rather encourage backwards compatibility but not be constrained by it." Still, the goal of starting and editing a v3 document being easier than for a v2 document is more important than backwards compatibility with v2, given the latter two design criteria.

v3 is upwards compatible with v2, meaning that a v2 document is meant to be a valid v3 document as well. However, some features of v2 are deprecated in v3 in favor of new elements. Deprecated features are listed in Section 1.3.3 and are described in [RFC7749].

1.3. Differences from v2 to v3

This is a (hopefully) complete list of all the technical changes between [RFC7749] and this document.

1.3.1. New Elements in v3

o Add

,