idnits 2.17.1 draft-reschke-xml2rfc-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- -- The document has an IETF Trust Provisions (28 Dec 2009) Section 6.c(i) Publication Limitation clause. -- The document has an IETF Trust Provisions (28 Dec 2009) Section 6.c(ii) Publication Limitation clause. If this document is intended for submission to the IESG for publication, this constitutes an error. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. -- The draft header indicates that this document obsoletes RFC2629, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 12, 2014) is 3604 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Obsolete informational reference (is this intentional?): RFC 2223 (Obsoleted by RFC 7322) -- Obsolete informational reference (is this intentional?): RFC 2629 (Obsoleted by RFC 7749) -- Obsolete informational reference (is this intentional?): RFC 3023 (Obsoleted by RFC 7303) -- Obsolete informational reference (is this intentional?): RFC 5741 (Obsoleted by RFC 7841) Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Reschke 3 Internet-Draft greenbytes 4 Obsoletes: 2629 (if approved) June 12, 2014 5 Intended status: Informational 6 Expires: December 14, 2014 8 The 'XML2RFC' version 2 Vocabulary 9 draft-reschke-xml2rfc-08 11 Abstract 13 This document defines the 'XML2RFC' version 2 vocabulary; an XML- 14 based language used for writing RFCs and Internet-Drafts. 16 Editorial Note (To be removed by RFC Editor) 18 Discussion of this draft takes place on the XML2RFC mailing list 19 (xml2rfc@ietf.org), which has its home page at 20 . 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on December 14, 2014. 39 Copyright Notice 41 Copyright (c) 2014 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 1.1. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 4 55 2. Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 2.1. . . . . . . . . . . . . . . . . . . . . . . . . 4 57 2.2.
. . . . . . . . . . . . . . . . . . . . . . . . 4 58 2.3. . . . . . . . . . . . . . . . . . . . . . . . 5 59 2.4. . . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 2.5. . . . . . . . . . . . . . . . . . . . . . . . . 6 61 2.6. . . . . . . . . . . . . . . . . . . . . . . . . . 8 62 2.7. . . . . . . . . . . . . . . . . . . . . . . . . . . 9 63 2.8. . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 64 2.9. . . . . . . . . . . . . . . . . . . . . . . . . . . 10 65 2.10. . . . . . . . . . . . . . . . . . . . . . . . . . . 10 66 2.11. . . . . . . . . . . . . . . . . . . . . . . . . 11 67 2.12. . . . . . . . . . . . . . . . . . . . . . . . . . . 11 68 2.13. . . . . . . . . . . . . . . . . . . . . . . . . . . 11 69 2.14. . . . . . . . . . . . . . . . . . . . . . . . . . 12 70 2.15. . . . . . . . . . . . . . . . . . . . . . . . . . . 12 71 2.16. . . . . . . . . . . . . . . . . . . . . . . . 13 72 2.17.
. . . . . . . . . . . . . . . . . . . . . . . . . 13 73 2.18. . . . . . . . . . . . . . . . . . . . . . . . . . 15 74 2.19. . . . . . . . . . . . . . . . . . . . . . . . . . 15 75 2.20. . . . . . . . . . . . . . . . . . . . . . . . . . . 16 76 2.21. . . . . . . . . . . . . . . . . . . . . . . . . 17 77 2.22. . . . . . . . . . . . . . . . . . . . . . . . . . . 17 78 2.23. . . . . . . . . . . . . . . . . . . . . . . . . . 19 79 2.24. . . . . . . . . . . . . . . . . . . . . . . . . . . 19 80 2.25. . . . . . . . . . . . . . . . . . . . . . . 20 81 2.26. . . . . . . . . . . . . . . . . . . . . . . . . . 20 82 2.27. . . . . . . . . . . . . . . . . . . . . . . . . . 20 83 2.28. . . . . . . . . . . . . . . . . . . . . . . . 21 84 2.29. . . . . . . . . . . . . . . . . . . . . . . . . 21 85 2.30. . . . . . . . . . . . . . . . . . . . . . . . 22 86 2.31. . . . . . . . . . . . . . . . . . . . . . . . 22 87 2.32. . . . . . . . . . . . . . . . . . . . . . . . . . 23 88 2.33. . . . . . . . . . . . . . . . . . . . . . . . . . . 23 89 2.34.
. . . . . . . . . . . . . . . . . . . . . . . . 27 90 2.35. . . . . . . . . . . . . . . . . . . . . . . . 28 91 2.36. . . . . . . . . . . . . . . . . . . . . . . . . . 28 92 2.37. . . . . . . . . . . . . . . . . . . . . . . . . . 29 93 2.38. . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 94 2.39. . . . . . . . . . . . . . . . . . . . . . . . 30 95 2.40. . . . . . . . . . . . . . . . . . . . . . . . . . 32 96 2.41. <ttcol> . . . . . . . . . . . . . . . . . . . . . . . . . 32 97 2.42. <uri> . . . . . . . . . . . . . . . . . . . . . . . . . . 33 98 2.43. <vspace> . . . . . . . . . . . . . . . . . . . . . . . . . 33 99 2.44. <workgroup> . . . . . . . . . . . . . . . . . . . . . . . 34 100 2.45. <xref> . . . . . . . . . . . . . . . . . . . . . . . . . . 34 101 3. Escaping for use in XML . . . . . . . . . . . . . . . . . . . 36 102 4. Special Unicode Code Points . . . . . . . . . . . . . . . . . 36 103 5. Including Files . . . . . . . . . . . . . . . . . . . . . . . 37 104 6. Internationalization Considerations . . . . . . . . . . . . . 38 105 7. Security Considerations . . . . . . . . . . . . . . . . . . . 38 106 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 107 8.1. Internet Media Type Registration . . . . . . . . . . . . . 38 108 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 39 109 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 40 110 10.1. Normative References . . . . . . . . . . . . . . . . . . . 40 111 10.2. Informative References . . . . . . . . . . . . . . . . . . 40 112 Appendix A. Front Page Generation . . . . . . . . . . . . . . . . 42 113 A.1. The /rfc/@category Attribute . . . . . . . . . . . . . . . 42 114 A.2. The /rfc/@ipr Attribute . . . . . . . . . . . . . . . . . 42 115 A.2.1. Current Values: '*trust200902' . . . . . . . . . . . . 43 116 A.2.2. Historic Values . . . . . . . . . . . . . . . . . . . 45 117 Appendix B. Changes from RFC 2629 ('v1') . . . . . . . . . . . . 45 118 B.1. Removed Elements . . . . . . . . . . . . . . . . . . . . . 45 119 B.2. Changed Defaults . . . . . . . . . . . . . . . . . . . . . 45 120 B.3. Changed Elements . . . . . . . . . . . . . . . . . . . . . 46 121 B.4. New Elements . . . . . . . . . . . . . . . . . . . . . . . 46 122 Appendix C. Relax NG Schema . . . . . . . . . . . . . . . . . . . 46 123 C.1. Checking Validity . . . . . . . . . . . . . . . . . . . . 52 124 Appendix D. Proposed Future Changes for 'v3' . . . . . . . . . . 52 125 D.1. Contact Information . . . . . . . . . . . . . . . . . . . 53 126 D.2. Figures . . . . . . . . . . . . . . . . . . . . . . . . . 53 127 D.3. Linking . . . . . . . . . . . . . . . . . . . . . . . . . 53 128 D.4. Lists . . . . . . . . . . . . . . . . . . . . . . . . . . 54 129 D.5. References . . . . . . . . . . . . . . . . . . . . . . . . 54 130 D.6. Archival Considerations . . . . . . . . . . . . . . . . . 54 131 D.7. Document Metadata . . . . . . . . . . . . . . . . . . . . 54 132 D.8. Including Material . . . . . . . . . . . . . . . . . . . . 55 133 D.9. Misc. . . . . . . . . . . . . . . . . . . . . . . . . . . 55 134 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 136 1. Introduction 138 This document describes version 2 ('v2') of the 'XML2RFC' vocabulary; 139 an XML-based language ('Extensible Markup Language', [XML]) used for 140 writing RFCs ([RFCSTYLE]) and Internet-Drafts ([IDGUIDE]). 142 It obsoletes the original version ("v1") [RFC2629], which contained 143 the original language definition, and which was subsequently extended 144 ("v2"). Furthermore, it discusses potential extensions in a future 145 revision ("v3"). 147 Note that the vocabulary contains certain constructs that might not 148 be used when generating the final text; however, they can provide 149 useful data for other uses (such index generation, populating a 150 keyword database, or syntax checks). 152 1.1. Syntax Notation 154 The XML vocabulary here is defined in prose, based on the Relax NG 155 schema ([RNC]) contained in Appendix C (specified in Relax NG Compact 156 Notation, "RNC"). 158 Note that the schema can be used for automated validity checks, but 159 certain constraints are only described in prose (example: the 160 conditionally required presence of the "abbrev" attribute). 162 2. Elements 164 The sections below describe all elements and their attributes. 166 Note that attributes not labeled "mandatory" are optional. 168 2.1. <abstract> 170 Contains the abstract of the document. The abstract ought to be 171 self-contained and thus should not contain references or unexpanded 172 abbreviations. See Section 4.3 of [RFCSTYLE] for more information. 174 This element appears as child element of: <front> (Section 2.19). 176 Content model: 178 One or more <t> elements (Section 2.38) 180 2.2. <address> 182 Provides address information for the author. 184 This element appears as child element of: <author> (Section 2.6). 186 Content model: 188 In this order: 190 1. One optional <postal> element (Section 2.27) 192 2. One optional <phone> element (Section 2.26) 194 3. One optional <facsimile> element (Section 2.16) 196 4. One optional <email> element (Section 2.14) 198 5. One optional <uri> element (Section 2.42) 200 2.3. <annotation> 202 Provides additional prose augmenting a bibliographical reference. 204 For instance: 206 <annotation> 207 Latest version available at <eref 208 target='http://www.w3.org/TR/xml'/>. 209 </annotation> 211 ...will generate the text used in the reference for [XML]. 213 This element appears as child element of: <reference> (Section 2.30). 215 Content model: 217 In any order: 219 o Text 221 o <xref> elements (Section 2.45) 223 o <eref> elements (Section 2.15) 225 o <iref> elements (Section 2.20) 227 o <cref> elements (Section 2.12) 229 o <spanx> elements (Section 2.36) 231 2.4. <area> 233 Provides information about the IETF area to which this document 234 relates (currently not used when generating documents). 236 The value ought to be either the fullname or the abbreviation of one 237 of the IETF areas as listed on <http://www.ietf.org/iesg/area.html>. 238 The list at the time that this document is being published is: 239 "Applications", "app", "General", "gen", "Internet", "int", 240 "Operations and Management", "ops", "Real-time Applications and 241 Infrastructure", "rai", "Routing", "rtg", "Security", "sec", 242 "Transport", "tsv". 244 This element appears as child element of: <front> (Section 2.19). 246 Content model: only text content. 248 2.5. <artwork> 250 This element allows the inclusion of "artwork" into the document. 252 <artwork> is the only element in the vocabulary that provides full 253 control of horizontal whitespace and line breaks, and thus is used 254 for a variety of things, such as: 256 o diagrams ("line art"), 258 o source code, 260 o formal languages (such as ABNF or the RNC notation used in this 261 document), 263 o complex tables, or 265 o protocol unit diagrams. 267 Alternatively, the "src" attribute allows referencing an external 268 graphics file, such as a bitmap or a vector drawing, using a URI. In 269 this case, the textual content acts as fallback for output formats 270 that do not support graphics, and thus ought to contain either a 271 "line art" variant of the graphics, or otherwise prose that describes 272 the included image in sufficient detail. Note that RFCs occasionally 273 are published with enhanced diagrams; a recent example is [RFC5598]. 275 This element appears as child element of: <figure> (Section 2.17). 277 Content model: 279 Text 281 2.5.1. 'align' attribute 283 Controls whether the artwork appears left (default), centered, or 284 right. 286 Allowed values: 288 o "left" (default) 290 o "center" 292 o "right" 294 2.5.2. 'alt' attribute 296 Alternative text description of the artwork (not just the caption). 298 2.5.3. 'height' attribute 300 The suggested height of the graphics included using the "src" 301 attribute. 303 This attribute is format-dependent and ought to be avoided. 305 When generating HTML output, current implementations copy the 306 attribute "as is". For other output formats it is usually ignored. 308 2.5.4. 'name' attribute 310 A filename suitable for the contents (such as for extraction to a 311 local file). 313 This attribute generally isn't used for document generation, but it 314 can be helpful for other kinds of tools (such as automated syntax 315 checkers which work by extracting the source code). 317 2.5.5. 'src' attribute 319 The URI of a graphics file. 321 Note that this can be a "data" URI ([RFC2397]) as well, in which case 322 the graphics file is wholly part of the XML file. 324 2.5.6. 'type' attribute 326 Specifies the type of the artwork. 328 The value either is a well-known keyword (such as "abnf"), or an 329 Internet Media Type (see [RFC2046]). 331 How it is used depends on context and application. For instance, a 332 formatter can attempt to syntax-highlight code in certain known 333 languages. 335 2.5.7. 'width' attribute 337 The suggested width of the graphics included using the "src" 338 attribute. 340 This attribute is format-dependent and ought to be avoided. 342 When generating HTML output, current implementations copy the 343 attribute "as is". For other output formats it is usually ignored. 345 2.5.8. 'xml:space' attribute 347 Determines whitespace handling. 349 "preserve" is both the default value and the only meaningful setting 350 anyway (because that's what the <artwork> element is for). 352 See also Section 2.10 of [XML]. 354 Allowed values: 356 o "default" 358 o "preserve" (default) 360 2.6. <author> 362 Provides information about a document's author. This is used both 363 for the document itself (at the beginning of the document) and for 364 referenced documents (inside of <reference>). 366 The <author> elements contained within the document's <front> element 367 are used to fill the boilerplate, and also to generate the "Author's 368 Address" section (see Section 4.12 of [RFCSTYLE]). 370 Note that an "author" can also be just an organization (by not 371 specifying any of the name attributes, but adding the <organization> 372 child element). 374 Furthermore, the "role" attribute can be used to mark an author as 375 "editor". This is reflected both on the front page and in 376 bibliographical references. Note that this specification does not 377 define a precise meaning for the term "editor". 379 See Section "Authors vs. Contributors" of [RFCPOLICY] for more 380 information. 382 This element appears as child element of: <front> (Section 2.19). 384 Content model: 386 In this order: 388 1. One optional <organization> element (Section 2.25) 390 2. One optional <address> element (Section 2.2) 392 2.6.1. 'fullname' attribute 394 The full name (used in the automatically generated "Author's Address" 395 section). 397 2.6.2. 'initials' attribute 399 Author initials (used on the front page and in references). 401 Initials should be provided as a whitespace separated list of pairs 402 of a letter and a dot. 404 2.6.3. 'role' attribute 406 Specifies the role the author had in creating the document. 408 Allowed values: 410 o "editor" 412 2.6.4. 'surname' attribute 414 The author's surname. 416 2.7. <back> 418 Contains the "back" part of the document: the references and 419 appendices. In <back>, <section> elements indicate appendices. 421 This element appears as child element of: <rfc> (Section 2.33). 423 Content model: 425 In this order: 427 1. Optional <references> elements (Section 2.31) 429 2. Optional <section> elements (Section 2.34) 431 2.8. <c> 433 Provides the content of a cell in a table. 435 This element appears as child element of: <texttable> (Section 2.39). 437 Content model: 439 In any order: 441 o Text 443 o <xref> elements (Section 2.45) 445 o <eref> elements (Section 2.15) 447 o <iref> elements (Section 2.20) 449 o <cref> elements (Section 2.12) 451 o <spanx> elements (Section 2.36) 453 2.9. <city> 455 Gives the city name in a postal address. 457 This element appears as child element of: <postal> (Section 2.27). 459 Content model: only text content. 461 2.10. <code> 463 Gives the postal region code. 465 This element appears as child element of: <postal> (Section 2.27). 467 Content model: only text content. 469 2.11. <country> 471 Gives the country in a postal address. 473 This element appears as child element of: <postal> (Section 2.27). 475 Content model: only text content. 477 2.12. <cref> 479 Represents a comment. 481 Comments can be used in a document while it is work-in-progress. 482 They usually appear either inline and visually highlighted, at the 483 end of the document (depending on file format and settings of the 484 formatter), or not at all (when generating an RFC). 486 This element appears as child element of: <annotation> (Section 2.3), 487 <c> (Section 2.8), <postamble> (Section 2.28), <preamble> 488 (Section 2.29), and <t> (Section 2.38). 490 Content model: only text content. 492 2.12.1. 'anchor' attribute 494 Document-wide unique identifier for this comment. The processor will 495 auto-generate an identifier when none is given. 497 The value needs to be a valid XML "Name" (Section 2.3 of [XML]), 498 additionally constrained to US-ASCII characters ([USASCII]). 500 2.12.2. 'source' attribute 502 Holds the "source" of a comment, such as the name or the initials of 503 the person who made the comment. 505 2.13. <date> 507 Provides information about the publication date. 509 Note that this element is used both for the boilerplate of the 510 document being produced, and also inside bibliographic references. 512 In the first case, it defines the publication date, which, when 513 producing Internet-Drafts, will be used for computing the expiration 514 date (see Section 8 of [IDGUIDE]). When "year", "month" or "day" are 515 left out, the processor will attempt to use the current system date 516 if the attributes that are specified do match the system date. 518 Note that in the first case, month names need to match the full 519 (English) month name ("January", "February", "March", "April", "May, 520 "June", "July", "August", "September", "October", "November", or 521 "December") in order for expiration calculations to work (some 522 implementations might support additional formats, though). 524 In the second case, the date information can have prose text for the 525 month or year. For example, vague dates (year="ca. 2000"), date 526 ranges (year="2012-2013") non-specific months (month="Second 527 quarter") and so on, are allowed. 529 This element appears as child element of: <front> (Section 2.19). 531 Content model: this element does not have any contents. 533 2.13.1. 'day' attribute 535 Day of publication; this is a number. 537 2.13.2. 'month' attribute 539 Month of publication; this is the English name of the month. 541 2.13.3. 'year' attribute 543 Year of publication. 545 2.14. <email> 547 Provides an email address. 549 The value is expected to be the scheme-specific part of a "mailto" 550 URI (so does not include the prefix "mailto:"). See Section 2 of 551 [RFC6068] for details. 553 This element appears as child element of: <address> (Section 2.2). 555 Content model: only text content. 557 2.15. <eref> 559 Represents an "external" link (as specified in the "target" 560 attribute). 562 If the element has text content, that content will be used. 563 Otherwise, the value of the target attribute will be inserted in 564 angle brackets ([RFC3986], Appendix C). 566 This element appears as child element of: <annotation> (Section 2.3), 567 <c> (Section 2.8), <postamble> (Section 2.28), <preamble> 568 (Section 2.29), and <t> (Section 2.38). 570 Content model: only text content. 572 2.15.1. 'target' attribute (mandatory) 574 URI of the link target (see Section 3 of [RFC3986]). 576 2.16. <facsimile> 578 Represents the phone number of a fax machine. 580 The value is expected to be the scheme-specific part of a "tel" URI 581 (so does not include the prefix "tel:"), using the "global numbers" 582 syntax. See Section 3 of [RFC3966] for details. 584 This element appears as child element of: <address> (Section 2.2). 586 Content model: only text content. 588 2.17. <figure> 590 This element is used to represent a figure, consisting of an optional 591 preamble, the actual figure, an optional postamble, and an optional 592 title. 594 This element appears as child element of: <section> (Section 2.34), 595 and <t> (Section 2.38). 597 Content model: 599 In this order: 601 1. Optional <iref> elements (Section 2.20) 603 2. One optional <preamble> element (Section 2.29) 605 3. One <artwork> element (Section 2.5) 607 4. One optional <postamble> element (Section 2.28) 609 2.17.1. 'align' attribute 611 Used to change the alignment of <preamble> and <postamble>. 613 Note: does not affect title or <artwork> alignment. 615 Allowed values: 617 o "left" (default) 619 o "center" 621 o "right" 623 2.17.2. 'alt' attribute 625 Duplicates functionality available on <artwork>; avoid it. 627 2.17.3. 'anchor' attribute 629 Document-wide unique identifier for this figure. 631 Furthermore, the presence of this attribute causes the figure to be 632 numbered. 634 The value needs to be a valid XML "Name" (Section 2.3 of [XML]). 636 2.17.4. 'height' attribute 638 Duplicates functionality available on <artwork>; avoid it. 640 2.17.5. 'src' attribute 642 Duplicates functionality available on <artwork>; avoid it. 644 2.17.6. 'suppress-title' attribute 646 Figures that have an "anchor" attribute will automatically get an 647 autogenerated title (such as "Figure 1"), even if the "title" 648 attribute is absent. Setting this attribute to "true" will prevent 649 this. 651 Allowed values: 653 o "true" 655 o "false" (default) 657 2.17.7. 'title' attribute 659 The title for the figure; this usually appears on a line after the 660 figure. 662 2.17.8. 'width' attribute 664 Duplicates functionality available on <artwork>; avoid it. 666 2.18. <format> 668 Provides a link to an additional format variant for a reference. 670 Note that these additional links are neither used in published RFCs, 671 nor supported by all tools. If the goal is to provide a single URI 672 for a reference, the "target" attribute on <reference> can be used 673 instead. 675 This element appears as child element of: <reference> (Section 2.30). 677 Content model: this element does not have any contents. 679 2.18.1. 'octets' attribute 681 Octet length of linked-to document. 683 2.18.2. 'target' attribute 685 URI of document. 687 2.18.3. 'type' attribute (mandatory) 689 The type of the linked-to document, such as "TXT", "HTML", or "PDF". 691 2.19. <front> 693 Represent the "front matter": metadata (such as author information), 694 abstract, and additional notes. 696 This element appears as child element of: <reference> (Section 2.30), 697 and <rfc> (Section 2.33). 699 Content model: 701 In this order: 703 1. One <title> element (Section 2.40) 705 2. One or more <author> elements (Section 2.6) 707 3. One <date> element (Section 2.13) 708 4. Optional <area> elements (Section 2.4) 710 5. Optional <workgroup> elements (Section 2.44) 712 6. Optional <keyword> elements (Section 2.21) 714 7. One optional <abstract> element (Section 2.1) 716 8. Optional <note> elements (Section 2.24) 718 2.20. <iref> 720 Provides terms for the document's index. 722 Index entries can be either single items (when just the "item" 723 attribute is given) or nested items (by specifying "subitem" as 724 well). 726 For instance: 728 <iref item="Grammar" subitem="item"/> 730 will produce an index entry for "Grammar, item". 732 This element appears as child element of: <annotation> (Section 2.3), 733 <c> (Section 2.8), <figure> (Section 2.17), <postamble> 734 (Section 2.28), <preamble> (Section 2.29), <section> (Section 2.34), 735 and <t> (Section 2.38). 737 Content model: this element does not have any contents. 739 2.20.1. 'item' attribute (mandatory) 741 The item to include. 743 2.20.2. 'primary' attribute 745 Setting this to "true" declares the occurrence as "primary", which 746 might cause it to be highlighted in the index. 748 Allowed values: 750 o "true" 752 o "false" (default) 754 2.20.3. 'subitem' attribute 756 The subitem to include. 758 2.21. <keyword> 760 Specifies a keyword applicable to the document. 762 Note that each element should only contain a single keyword; for 763 multiple keywords, the element can simply be repeated. 765 Keywords are used both in the RFC Index and in the metadata of 766 generated document formats. 768 This element appears as child element of: <front> (Section 2.19). 770 Content model: only text content. 772 2.22. <list> 774 Delineates a text list. 776 Each list item is represented by a <t> element. The vocabulary 777 currently does not directly support list items consisting of multiple 778 paragraphs; if this is needed, <vspace> (Section 2.43) can be used as 779 workaround. 781 This element appears as child element of: <t> (Section 2.38). 783 Content model: 785 One or more <t> elements (Section 2.38) 787 2.22.1. 'counter' attribute 789 This attribute holds a token that serves as an identifier for a 790 counter. The intended use is continuation of lists. 792 Note that this attribute functions only when the style attribute is 793 using the "format..." syntax (Section 2.22.3); otherwise, it is 794 ignored. 796 2.22.2. 'hangIndent' attribute 798 For list styles with potentially wide labels, this attribute can 799 override the default indentation level, measured in characters. 801 Note that it only affects style with variable-width labels 802 ("format..." and "hanging", see below), and it may not affect formats 803 in which the list item text appears _below_ the label. 805 2.22.3. 'style' attribute 807 This attribute is used to control the display of a list. 809 The value of this attribute is inherited by any nested lists that do 810 not have this attribute set. It may be set to: 812 "empty" (or not set) 814 For unlabeled list items; it can also be used for indentation 815 purposes (this is the default value). 817 "hanging" 819 For lists where the items are labeled with a piece of text. 821 The label text is specified in the 'hangText' attribute of the <t> 822 element (Section 2.38.2). 824 "letters" 826 For ordered lists using letters as labels (lowercase letters 827 followed by a period; after "z", it rolls over to a two-letter 828 format). For nested lists, processors usually flip between 829 uppercase and lowercase. 831 "numbers" 833 For ordered lists using numbers as labels. 835 "symbols" 837 For unordered (bulleted) lists. 839 The style of the bullets is chosen automatically be the processor 840 (some implementations allow overriding the default using a 841 processing instruction). 843 And, finally: 845 "format ..." 847 For lists with customized labels, consisting of fixed text and an 848 item counter in various formats. 850 The value is a free-form text that allows counter values to be 851 inserted using a "percent-letter" format. For instance, "[REQ%d]" 852 generates labels of the form "[REQ1]", where "%d" inserts the item 853 number as decimal number. 855 The following formats are supported: 857 %c lowercase letters (a, b, c, etc.) 859 %C uppercase letters (A, B, C, etc.) 861 %d decimal numbers (1, 2, 3, etc.) 863 %i lowercase Roman numerals (i, ii, iii, etc.) 865 %I uppercase Roman numerals (I, II, III, etc.) 867 %% represents a percent sign 869 Other formats are reserved for future use. 871 2.23. <middle> 873 Represents the main content of the document. 875 This element appears as child element of: <rfc> (Section 2.33). 877 Content model: 879 One or more <section> elements (Section 2.34) 881 2.24. <note> 883 Creates an unnumbered section that appears after the abstract. 885 It is usually used for additional information to reviewers (working 886 group information, mailing list, ...), or for additional publication 887 information such as "IESG Notes". 889 This element appears as child element of: <front> (Section 2.19). 891 Content model: 893 One or more <t> elements (Section 2.38) 895 2.24.1. 'title' attribute (mandatory) 897 The title of the note. 899 2.25. <organization> 901 Specifies the affiliation of an author. 903 This information appears in both the "Author's Address" section and 904 on the front page (see [RFCSTYLE], Section 4.1.1 for more 905 information). If the value is long, an abbreviated variant can be 906 specified in the "abbrev" attribute. 908 This element appears as child element of: <author> (Section 2.6). 910 Content model: only text content. 912 2.25.1. 'abbrev' attribute 914 Abbreviated variant. 916 2.26. <phone> 918 Represents a phone number. 920 The value is expected to be the scheme-specific part of a "tel" URI 921 (so does not include the prefix "tel:"), using the "global numbers" 922 syntax. See Section 3 of [RFC3966] for details. 924 This element appears as child element of: <address> (Section 2.2). 926 Content model: only text content. 928 2.27. <postal> 930 Contains child elements providing postal information. 932 This element appears as child element of: <address> (Section 2.2). 934 Content model: 936 In this order: 938 1. One or more <street> elements (Section 2.37) 940 2. In any order: 942 * <city> elements (Section 2.9) 944 * <region> elements (Section 2.32) 946 * <code> elements (Section 2.10) 948 * <country> elements (Section 2.11) 950 2.28. <postamble> 952 Gives text that appears at the bottom of a figure or table. 954 This element appears as child element of: <figure> (Section 2.17), 955 and <texttable> (Section 2.39). 957 Content model: 959 In any order: 961 o Text 963 o <xref> elements (Section 2.45) 965 o <eref> elements (Section 2.15) 967 o <iref> elements (Section 2.20) 969 o <cref> elements (Section 2.12) 971 o <spanx> elements (Section 2.36) 973 2.29. <preamble> 975 Gives text that appears at the top of a figure or table. 977 This element appears as child element of: <figure> (Section 2.17), 978 and <texttable> (Section 2.39). 980 Content model: 982 In any order: 984 o Text 986 o <xref> elements (Section 2.45) 988 o <eref> elements (Section 2.15) 989 o <iref> elements (Section 2.20) 991 o <cref> elements (Section 2.12) 993 o <spanx> elements (Section 2.36) 995 2.30. <reference> 997 Represents a bibliographical reference. 999 This element appears as child element of: <references> 1000 (Section 2.31). 1002 Content model: 1004 In this order: 1006 1. One <front> element (Section 2.19) 1008 2. Optional <seriesInfo> elements (Section 2.35) 1010 3. Optional <format> elements (Section 2.18) 1012 4. Optional <annotation> elements (Section 2.3) 1014 2.30.1. 'anchor' attribute (mandatory) 1016 Document-wide unique identifier for this reference. Usually, this 1017 will be used both to "label" the reference in the references section, 1018 and as an identifier in links to this reference entry. 1020 The value needs to be a valid XML "Name" (Section 2.3 of [XML]), 1021 additionally constrained to US-ASCII characters ([USASCII]). 1023 2.30.2. 'target' attribute 1025 Holds the URI for the reference. 1027 Note that depending on the <seriesInfo> element, a URI might not be 1028 needed, nor desirable, as it can be automatically generated (for 1029 instance, for RFCs). 1031 2.31. <references> 1033 Contains a set of bibliographical references. 1035 In the early days of the RFC series, there was only one "References" 1036 section per RFC. This convention was later changed to group 1037 references into two sets, "Normative" and "Informative" as described 1038 in Section 4.8.6 of [RFCSTYLE]). This vocabulary supports the split 1039 with the "title" attribute. 1041 This element appears as child element of: <back> (Section 2.7). 1043 Content model: 1045 One or more <reference> elements (Section 2.30) 1047 2.31.1. 'title' attribute 1049 Provides the title for the References section (defaulting to 1050 "References"). 1052 In general, the title should be either "Normative References" or 1053 "Informative References". 1055 2.32. <region> 1057 Provides the region name in a postal address. 1059 This element appears as child element of: <postal> (Section 2.27). 1061 Content model: only text content. 1063 2.33. <rfc> 1065 This is the root element of the xml2rfc vocabulary. 1067 Processors distinguish between RFC mode ("number" attribute being 1068 present) and Internet-Draft mode ("docName" attribute being present): 1069 it is invalid to specify both. Setting neither "number" nor 1070 "docName" can be useful for producing other types of document but is 1071 out-of-scope for this specification. 1073 Content model: 1075 In this order: 1077 1. One <front> element (Section 2.19) 1079 2. One <middle> element (Section 2.23) 1081 3. One optional <back> element (Section 2.7) 1083 2.33.1. 'category' attribute 1085 Document category (see Appendix A.1). 1087 Allowed values: 1089 o "std" 1091 o "bcp" 1093 o "info" 1095 o "exp" 1097 o "historic" 1099 2.33.2. 'consensus' attribute 1101 Affects the generated boilerplate. 1103 See [RFC5741] for more information. 1105 Allowed values: 1107 o "no" 1109 o "yes" 1111 2.33.3. 'docName' attribute 1113 For Internet-Drafts, this specifies the draft name (which appears 1114 below the title). 1116 A processor should give an error if both the "docName" and "number" 1117 attributes are given in the <rfc> element. 1119 Note that the file extension is not part of the draft, so in general 1120 it should end with the current draft number ("-", plus two digits). 1122 Furthermore, it is good practice to disambiguate current editor 1123 copies from submitted drafts (for instance, by replacing the draft 1124 number with the string "latest"). 1126 See Section 7 of [IDGUIDE] for further information. 1128 2.33.4. 'ipr' attribute 1130 Represents the Intellectual Property status of the document. See 1131 Appendix A.2 for details. 1133 Allowed values: 1135 o "full2026" 1137 o "noDerivativeWorks2026" 1139 o "none" 1141 o "full3667" 1143 o "noModification3667" 1145 o "noDerivatives3667" 1147 o "full3978" 1149 o "noModification3978" 1151 o "noDerivatives3978" 1153 o "trust200811" 1155 o "noModificationTrust200811" 1157 o "noDerivativesTrust200811" 1159 o "trust200902" 1161 o "noModificationTrust200902" 1163 o "noDerivativesTrust200902" 1165 o "pre5378Trust200902" 1167 2.33.5. 'iprExtract' attribute 1169 Identifies a single section within the document (by its 'anchor' 1170 attribute) for which extraction "as-is" is explicitly allowed (this 1171 is only relevant for historic values of the "ipr" attribute). 1173 2.33.6. 'number' attribute 1175 The number of the RFC to be produced. 1177 A processor should give an error if both the "docName" and "number" 1178 attributes are given in the <rfc> element. 1180 2.33.7. 'obsoletes' attribute 1182 A comma-separated list of RFC _numbers_ or Internet-Draft names. 1184 Processors ought to parse the attribute value, so that incorrect 1185 references can be detected and, depending on output format, 1186 hyperlinks can be generated. Also, the value ought to be reformatted 1187 to insert whitespace after each comma if not already present. 1189 2.33.8. 'seriesNo' attribute 1191 When producing a document within document series (such as "STD"): the 1192 number within that series. 1194 2.33.9. 'submissionType' attribute 1196 The document stream. 1198 See Section 2 of [RFC5741] for details. 1200 Allowed values: 1202 o "IETF" (default) 1204 o "IAB" 1206 o "IRTF" 1208 o "independent" 1210 2.33.10. 'updates' attribute 1212 A comma-separated list of RFC _numbers_ or Internet-Draft names. 1214 Processors ought to parse the attribute value, so that incorrect 1215 references can be detected and, depending on output format, 1216 hyperlinks can be generated. Also, the value ought to be reformatted 1217 to insert whitespace after each comma if not already present. 1219 2.33.11. 'xml:lang' attribute 1221 The natural language used in the document (defaults to "en"). 1223 See Section 2.12 of [XML] for more information. 1225 2.34. <section> 1227 Represents a section (when inside a <middle> element) or an appendix 1228 (when inside a <back> element). 1230 Sub-sections are created by nesting <section> elements inside 1231 <section> elements. 1233 This element appears as child element of: <back> (Section 2.7), 1234 <middle> (Section 2.23), and <section> (Section 2.34). 1236 Content model: 1238 In this order: 1240 1. In any order: 1242 * <t> elements (Section 2.38) 1244 * <figure> elements (Section 2.17) 1246 * <texttable> elements (Section 2.39) 1248 * <iref> elements (Section 2.20) 1250 2. Optional <section> elements (Section 2.34) 1252 2.34.1. 'anchor' attribute 1254 Document-wide unique identifier for this section. 1256 The value needs to be a valid XML "Name" (Section 2.3 of [XML]). 1258 2.34.2. 'title' attribute (mandatory) 1260 The title of the section. 1262 2.34.3. 'toc' attribute 1264 Determines whether the section is included in the Table Of Contents. 1266 The processor usually has defaults for whether a Table Of Contents 1267 will be produced at all, and sections of which maximal depth will be 1268 included (frequently: 3). "include" and "exclude" allow overriding 1269 the processor's default behavior for the element they are specified 1270 on (they do not affect nested elements). 1272 Allowed values: 1274 o "include" 1276 o "exclude" 1278 o "default" (default) 1280 2.35. <seriesInfo> 1282 Specifies the document series in which this document appears, and 1283 also specifies an identifier within that series. 1285 This element appears as child element of: <reference> (Section 2.30). 1287 Content model: this element does not have any contents. 1289 2.35.1. 'name' attribute (mandatory) 1291 The name of the series. 1293 The following names trigger specific processing (such as for auto- 1294 generating links, and adding descriptions such as "work in 1295 progress"): "BCP", "FYI", "Internet-Draft", "RFC", and "STD". 1297 2.35.2. 'value' attribute (mandatory) 1299 The identifier within the series specified by the "name" attribute. 1301 For BCPs, FYIs, RFCs, and STDs this is the number within the series. 1302 For Internet-Drafts, it is the full draft name (ending with the two- 1303 digit version number). 1305 2.36. <spanx> 1307 Wraps a piece of text, indicating special formatting styles. 1309 When generating plain text, processors usually emulate font changes 1310 using characters such as "*" and "_". 1312 The following styles are defined: 1314 emph Simple emphasis (this is the default). 1316 strong Strong emphasis. 1318 verb "Verbatim" text (usually displayed usign a monospaced font 1319 face). 1321 This element appears as child element of: <annotation> (Section 2.3), 1322 <c> (Section 2.8), <postamble> (Section 2.28), <preamble> 1323 (Section 2.29), and <t> (Section 2.38). 1325 Content model: only text content. 1327 2.36.1. 'style' attribute 1329 The style to be used (defaults to "emph"). 1331 2.36.2. 'xml:space' attribute 1333 Determines whitespace handling. 1335 According to the DTD, the default value is "preserve". Tests however 1336 show that it doesn't have any effect on processing; thus this 1337 attribute will be removed in future versions of the vocabulary. 1339 See also Section 2.10 of [XML]. 1341 Allowed values: 1343 o "default" 1345 o "preserve" (default) 1347 2.37. <street> 1349 Provides a street address. 1351 This element appears as child element of: <postal> (Section 2.27). 1353 Content model: only text content. 1355 2.38. <t> 1357 Contains a paragraph of text. 1359 This element appears as child element of: <abstract> (Section 2.1), 1360 <list> (Section 2.22), <note> (Section 2.24), and <section> 1361 (Section 2.34). 1363 Content model: 1365 In any order: 1367 o Text 1369 o <list> elements (Section 2.22) 1371 o <figure> elements (Section 2.17) 1373 o <xref> elements (Section 2.45) 1375 o <eref> elements (Section 2.15) 1377 o <iref> elements (Section 2.20) 1379 o <cref> elements (Section 2.12) 1381 o <spanx> elements (Section 2.36) 1383 o <vspace> elements (Section 2.43) 1385 2.38.1. 'anchor' attribute 1387 Document-wide unique identifier for this paragraph. 1389 The value needs to be a valid XML "Name" (Section 2.3 of [XML]). 1391 2.38.2. 'hangText' attribute 1393 Holds the label ("hanging text") for items in lists using the 1394 "hanging" style (see Section 2.22.3). 1396 2.39. <texttable> 1398 Contains a table, consisting of an optional preamble, a header line, 1399 rows, an optional postamble, and an optional title. 1401 The number of columns in the table is determined by the number of 1402 <ttcol> elements. The number of rows in the table is determined by 1403 the number of <c> elements divided by the number of columns. There 1404 is no requirement that the number of <c> elements be evenly divisible 1405 by the number of columns. 1407 This element appears as child element of: <section> (Section 2.34). 1409 Content model: 1411 In this order: 1413 1. One optional <preamble> element (Section 2.29) 1415 2. One or more <ttcol> elements (Section 2.41) 1417 3. Optional <c> elements (Section 2.8) 1419 4. One optional <postamble> element (Section 2.28) 1421 2.39.1. 'align' attribute 1423 Determines the horizontal alignment of the table. 1425 Allowed values: 1427 o "left" 1429 o "center" (default) 1431 o "right" 1433 2.39.2. 'anchor' attribute 1435 Document-wide unique identifier for this table. 1437 Furthermore, the presence of this attribute causes the table to be 1438 numbered. 1440 The value needs to be a valid XML "Name" (Section 2.3 of [XML]). 1442 2.39.3. 'style' attribute 1444 Selects which borders should be drawn, where 1446 o "all" means borders around all table cells, 1448 o "full" is like "all" except no horizontal lines between table rows 1449 (except below the column titles), 1451 o "headers" adds just a separator between column titles and rows, 1452 and 1454 o "none" means no borders at all. 1456 Allowed values: 1458 o "all" 1460 o "none" 1462 o "headers" 1464 o "full" (default) 1466 2.39.4. 'suppress-title' attribute 1468 Tables that have an "anchor" attribute will automatically get an 1469 autogenerated title (such as "Table 1"), even if the "title" 1470 attribute is absent. Setting this attribute to "true" will prevent 1471 this. 1473 Allowed values: 1475 o "true" 1477 o "false" (default) 1479 2.39.5. 'title' attribute 1481 The title for the table; this usually appears on a line below the 1482 table body. 1484 2.40. <title> 1486 Represents the document title. 1488 When this element appears in the <front> element of the current 1489 document, the title might also appear in page headers or footers. If 1490 it's long (~40 characters), the "abbrev" attribute is used to specify 1491 an abbreviated variant. 1493 This element appears as child element of: <front> (Section 2.19). 1495 Content model: only text content. 1497 2.40.1. 'abbrev' attribute 1499 Specifies an abbreviated variant of the document title. 1501 2.41. <ttcol> 1503 Contains a column heading in a table. 1505 This element appears as child element of: <texttable> (Section 2.39). 1507 Content model: only text content. 1509 2.41.1. 'align' attribute 1511 Determines the horizontal alignment within the table column. 1513 Allowed values: 1515 o "left" (default) 1517 o "center" 1519 o "right" 1521 2.41.2. 'width' attribute 1523 The desired column width (as integer 0..100 followed by "%"). 1525 2.42. <uri> 1527 Contains a web address associated with the author. 1529 The contents should be a valid URI (see Section 3 of [RFC3986]). 1531 This element appears as child element of: <address> (Section 2.2). 1533 Content model: only text content. 1535 2.43. <vspace> 1537 This element can be used to force the inclusion of a single line 1538 break or multiple blank lines. 1540 Note that this is a purely presentational element and thus its use 1541 ought to be avoided. 1543 This element appears as child element of: <t> (Section 2.38). 1545 Content model: this element does not have any contents. 1547 2.43.1. 'blankLines' attribute 1549 Number of blank lines to be inserted, where "0" indicates a single 1550 line break (defaults to "0"). 1552 For paged output formats, no additional blank lines should be 1553 generated after a page break. 1555 2.44. <workgroup> 1557 This element is used to specify the Working Group (IETF) or Research 1558 Group (IRTF) from which the document originates, if any. The 1559 recommended format is the official name of the Working Group (with 1560 some capitalization). 1562 In Internet-Drafts, this is used in the upper left corner of the 1563 boilerplate, replacing the "Network Working Group" string. 1564 Formatting software can append the words "Working Group" or "Research 1565 Group", depending on the "submissionType" property on the <rfc> 1566 element (Section 2.33.9). 1568 This element appears as child element of: <front> (Section 2.19). 1570 Content model: only text content. 1572 2.45. <xref> 1574 Inserts a reference to a different part of a document. 1576 The generated text depends on whether the <xref> is empty (in which 1577 case the processor will try to generate a meaningful text fragment), 1578 and the nature of the referenced document part. 1580 Any element that allows the "anchor" attribute can be referenced, 1581 however there are restrictions with respect to the text content being 1582 generated. For instance, a <t> can be a reference target, however, 1583 because paragraphs are not (visibly) numbered, the author will have 1584 to make sure that the prose is sufficient for a reader to understand 1585 what is being referred to. 1587 [[anchor2: This needs to be expanded with examples and with a 1588 discussion how the autogenerated text differs when <xref> is not 1589 empty]] 1591 This element appears as child element of: <annotation> (Section 2.3), 1592 <c> (Section 2.8), <postamble> (Section 2.28), <preamble> 1593 (Section 2.29), and <t> (Section 2.38). 1595 Content model: only text content. 1597 2.45.1. 'format' attribute 1599 This attribute is used to control the format of the generated 1600 reference text. 1602 "counter" 1603 Inserts a counter, such as the number of a section, figure, or 1604 table. 1606 "default" 1608 Inserts a text fragment that describes the referenced part 1609 completely, such as "Section 2", "Table 4", or "[XML]". 1611 "none" 1613 There will be no auto-generated text. 1615 "title" 1617 Inserts a title for the referenced element (usually obtained from 1618 the referenced element's "title" attribute; some processors also 1619 use the <title> child element or a <reference> target). 1621 Allowed values: 1623 o "counter" 1625 o "title" 1627 o "none" 1629 o "default" (default) 1631 2.45.2. 'pageno' attribute 1633 Unused. 1635 It's unclear what the purpose of this attribute is; processors seem 1636 to ignore it and it never was documented. 1638 Allowed values: 1640 o "true" 1642 o "false" (default) 1644 2.45.3. 'target' attribute (mandatory) 1646 Identifies the document component being referenced. 1648 The value needs to match the value of the "anchor" attribute of 1649 another element in the document. 1651 3. Escaping for use in XML 1653 Text in XML can not use the literal characters "<" and "&", as they 1654 have special meaning to the XML processor (starting entities, 1655 elements, etc.). Usually, these characters will need to be 1656 substituted by "<" and "&" (see Section 4.6 of [XML]). 1658 ">" does not require escaping, unless it appears in the sequence 1659 "]]>" (which indicates the end of a CDATA section, see below). 1661 Escaping the indivual characters can be a lot of work (when done 1662 manually), and also messes up alignment in artwork. Another approach 1663 to escaping is to use CDATA sections ([XML], Section 2.7). Within 1664 these, no further escaping is needed, except when the "end-of-CDATA" 1665 marker needs to be used (in that case, the CDATA section needs to be 1666 closed, and a new one needs to be started). 1668 4. Special Unicode Code Points 1670 Although the current RFC format does not allow non-ASCII Unicode 1671 characters ([UNICODE]), some of them can be used to enforce certain 1672 behaviors of formatters. 1674 For instance: 1676 non-breaking space (U+00A0) 1678 Represents a space character where no line break should happen. 1679 This is frequenly used in titles (by excluding certain space 1680 characters from the line breaking algorithm, the processor will 1681 use the remaining whitespace ocurrences for line breaks). 1683 non-breaking hyphen (U+2011) 1685 Similarly, this represents a hyphen character where nevertheless 1686 no line breaking ought to occur. 1688 word joiner (U+2060) 1690 Also called "zero width non-breaking space" -- can be used to 1691 disallow line breaking between two non-whitespace characters. 1693 Note that in order to use these characters by name, they need to be 1694 declared either in the Document Type Definition (DTD, [XML], Section 1695 2.9), or in the "internal subset" ([XML], Section 2.8), like that: 1697 <?xml version="1.0"?> 1699 <!DOCTYPE rfc [ 1701 <!-- declare nbsp and friends --> 1702 <!ENTITY nbsp " "> 1703 <!ENTITY nbhy "‑"> 1704 <!ENTITY wj "⁠"> 1705 ]> 1707 5. Including Files 1709 This version of the vocabulary does not support an inclusion 1710 mechanism on it's own -- thus, a document always needs to be self- 1711 contained. 1713 That being said, some processors do support file inclusion using 1714 processing instructions (Section 2.6 of [XML]). 1716 Furthermore, XML itself allows inclusion of external content using 1717 the "internal subset" (Section 2.8 of [XML]). Unfortunately, this 1718 requires declaring the external data in the DTD upfront. 1720 For instance: 1722 <?xml version="1.0"?> 1724 <!DOCTYPE rfc [ 1726 <!-- allow later RFC2616 reference using "&rfc2616;" --> 1727 <!-- the data will be fetched from xml.resource.org --> 1728 <!ENTITY rfc2616 PUBLIC 1729 "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml"> 1730 ]> 1732 ...declares the entity "rfc2616", which then can be used in the 1733 "references" section: 1735 <references> 1736 &rfc2616; 1737 </references> 1739 Note that this mechanism only works for well-formed XML fragments; 1740 thus any plain text that would need to be escaped in XML can't be 1741 included as-is. 1743 6. Internationalization Considerations 1745 This format is based on [XML], thus does not have any issues 1746 representing arbitrary Unicode [UNICODE] characters in text content. 1748 However, the current canonical RFC format is restricted to US-ASCII 1749 [USASCII] characters ([RFC2223], Section 3). Future versions are 1750 likely to relax this role, and it is expected that the vocabulary 1751 will be extended so that US-ACSII alternatives can be provided when 1752 that makes sense (for instance, in contact information). 1754 7. Security Considerations 1756 The "name" attribute on the <artwork> element (Section 2.5.4) can be 1757 used to derive a filename for saving to a local file system. 1758 Trusting this kind of information without pre-processing is a known 1759 security risk; see Section 4.3 of [RFC6266] for more information. 1761 Furthermore, the nature of XML, plus vocabulary features such as 1762 typed artwork, make it attractive to extract content from documents 1763 for further processing, such for the purpose of checking syntax, or 1764 computing/verifying examples. In the latter case, care needs to be 1765 taken that only trusted content is processed. 1767 Furthermore, all security considerations related to XML processing 1768 are relevant as well (see Section 7 of [RFC3470]). 1770 8. IANA Considerations 1772 8.1. Internet Media Type Registration 1774 IANA maintains the registry of Internet media types [BCP13] at 1775 <http://www.iana.org/assignments/media-types>. 1777 This document serves as the specification for the Internet media type 1778 "application/rfc+xml". The following is to be registered with IANA. 1780 Type name: application 1782 Subtype name: rfc+xml 1784 Required parameters: There are no required parameters. 1786 Optional parameters: "charset": This parameter has identical 1787 semantics as the charset parameter of the "application/xml" media 1788 type specified in [RFC3023]. 1790 Encoding considerations: Identical to those of "application/xml" as 1791 described in Section 3.2 of [RFC3023]. 1793 Security considerations: As defined in Section 7. In addition, as 1794 this media type uses the "+xml" convention, it inherits the 1795 security considerations described in Section 10 of [RFC3023]. 1797 Interoperability considerations: N/A 1799 Published specification: This specification. 1801 Applications that use this media type: Applications that either 1802 transform xml2rfc to output formats such as plain text or HTML, 1803 plus additional analysis tools. 1805 Fragment identifier considerations: The "anchor" attribute is used 1806 for assigning document-wide unique identifiers that can be uses as 1807 shorthand pointers, as described in Section 2.8 of [XPOINTER]. 1809 Additional information: 1811 Deprecated alias names for this type: None. 1813 Magic number(s): As specified for "application/xml" in Section 1814 3.2 of [RFC3023]. 1816 File extension(s): .xml or .rfcxml when disambiguation from other 1817 XML files is needed 1819 Macintosh file type code(s): TEXT 1821 Person & email address to contact for further information: See 1822 Authors Section. 1824 Intended usage: COMMON 1826 Restrictions on usage: N/A 1828 Author: See Authors Section. 1830 Change controller: RFC Series Editor (rse@rfc-editor.org) 1832 9. Acknowledgments 1834 Thanks to everybody who reviewed this document and provided feedback 1835 and/or specification text, in particular Brian Carpenter, Tony 1836 Hansen, Paul Hoffman, Henrik Levkowetz, Alice Russo, Tom Taylor, Jim 1837 Schaad, and Nico Williams. 1839 We also thank Marshall T. Rose for both the original design and the 1840 reference implementation of the "xml2rfc" formatter. 1842 10. References 1844 10.1. Normative References 1846 [XML] Maler, E., Yergeau, F., Paoli, J., Sperberg-McQueen, M., 1847 and T. Bray, "Extensible Markup Language (XML) 1.0 1848 (Fifth Edition)", W3C Recommendation REC-xml-20081126, 1849 November 2008, 1850 <http://www.w3.org/TR/2008/REC-xml-20081126/>. 1852 Latest version available at <http://www.w3.org/TR/xml>. 1854 10.2. Informative References 1856 [BCP13] Freed, N., Klensin, J., and T. Hansen, "Media Type 1857 Specifications and Registration Procedures", BCP 13, 1858 RFC 6838, January 2013. 1860 [IDGUIDE] Housley, R., "Guidelines to Authors of Internet-Drafts", 1861 December 2010, 1862 <http://www.ietf.org/id-info/guidelines.html>. 1864 [JING] Thai Open Source Software Center Ltd, "Jing - A RELAX NG 1865 validator in Java", W3C Recommendation REC-xptr- 1866 framework-20030325, 2008, 1867 <http://www.thaiopensource.com/relaxng/jing.html>. 1869 Downloads: 1870 <https://code.google.com/p/jing-trang/downloads/list>. 1872 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 1873 3", BCP 9, RFC 2026, October 1996. 1875 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1876 Extensions (MIME) Part Two: Media Types", RFC 2046, 1877 November 1996. 1879 [RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC 1880 Authors", RFC 2223, October 1997. 1882 [RFC2397] Masinter, L., "The "data" URL scheme", RFC 2397, 1883 August 1998. 1885 [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, 1886 June 1999. 1888 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 1889 Types", RFC 3023, January 2001. 1891 [RFC3470] Hollenbeck, S., Rose, M., and L. Masinter, "Guidelines 1892 for the Use of Extensible Markup Language (XML) within 1893 IETF Protocols", BCP 70, RFC 3470, January 2003. 1895 [RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers", 1896 RFC 3966, December 2004. 1898 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1899 Resource Identifier (URI): Generic Syntax", STD 66, 1900 RFC 3986, January 2005. 1902 [RFC5598] Crocker, D., "Internet Mail Architecture", RFC 5598, 1903 July 2009. 1905 PDF version: <http://www.rfc-editor.org/rfc/rfc5598.pdf> 1907 [RFC5741] Daigle, L. and O. Kolkman, "RFC Streams, Headers, and 1908 Boilerplates", RFC 5741, December 2009. 1910 [RFC6068] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' 1911 URI Scheme", RFC 6068, October 2010. 1913 [RFC6266] Reschke, J., "Use of the Content-Disposition Header 1914 Field in the Hypertext Transfer Protocol (HTTP)", 1915 RFC 6266, June 2011. 1917 [RFCPOLICY] RFC Editor, "RFC Editorial Guidelines and Procedures", 1918 February 2012, <http://www.rfc-editor.org/policy.html>. 1920 [RFCSTYLE] Heather, H. and S. Ginoza, "RFC Style Guide", 1921 draft-iab-styleguide-02 (work in progress), April 2014. 1923 [RNC] Clark, J., "RELAX NG Compact Syntax", OASIS , 1924 November 2002, <http://www.oasis-open.org/committees/ 1925 relax-ng/compact-20021121.html>. 1927 [TLP2.0] IETF Trust, "Legal Provisions Relating to IETF 1928 Documents", February 2009, 1929 <http://trustee.ietf.org/license-info/IETF-TLP-2.htm>. 1931 [TLP3.0] IETF Trust, "Legal Provisions Relating to IETF 1932 Documents", September 2009, 1933 <http://trustee.ietf.org/license-info/IETF-TLP-3.htm>. 1935 [TLP4.0] IETF Trust, "Legal Provisions Relating to IETF 1936 Documents", December 2009, 1937 <http://trustee.ietf.org/license-info/IETF-TLP-4.htm>. 1939 [UNICODE] The Unicode Consortium, "The Unicode Standard, Version 1940 6.3.0", September 2013, 1941 <http://www.unicode.org/versions/Unicode6.3.0/>. 1943 [USASCII] American National Standards Institute, "Coded Character 1944 Set -- 7-bit American Standard Code for Information 1945 Interchange", ANSI X3.4, 1986. 1947 [XINCLUDE] Marsh, J., Orchard, D., and D. Veillard, "XML Inclusions 1948 (XInclude) Version 1.0 (Second Edition)", W3C 1949 Recommendation REC-xinclude-20061115, November 2006, 1950 <http://www.w3.org/TR/2006/REC-xinclude-20061115/>. 1952 Latest version available at 1953 <http://www.w3.org/TR/xinclude/>. 1955 [XPOINTER] Grosso, P., Maler, E., Marsh, J., and N. Walsh, 1956 "XPointer Framework", W3C Recommendation REC-xptr- 1957 framework-20030325, March 2003, 1958 <http://www.w3.org/TR/2003/ 1959 REC-xptr-framework-20030325/>. 1961 Latest version available at 1962 <http://www.w3.org/TR/xptr-framework/>. 1964 Appendix A. Front Page Generation 1966 A.1. The /rfc/@category Attribute 1968 For RFCs, the "category" determines the "maturity level" (see Section 1969 4 of [RFC2026]). The allowed values are "std" for "Standards Track", 1970 "bcp" for "BCP", "info" for "Informational", "exp" for 1971 "Experimental", and "historic" for "Historic". 1973 For Internet-Drafts, the category attribute is not needed, but will 1974 appear on the front page as "Intended Status". Supplying this 1975 information can be useful to reviewers. 1977 A.2. The /rfc/@ipr Attribute 1979 This attribute value can take a long list of values, each of which 1980 describes an IPR policy for the document. This attribute's values 1981 are not the result of a grand plan, but remain simply for historic 1982 reasons. Of these values, only a few are currently in use; all 1983 others are supported by the various tools for backwards compatibility 1984 with old source files. 1986 Note: some variations of the boilerplate are selected based on the 1987 document's date; therefore it is important to specify the "year", 1988 "month" and "day" attributes of the "<date>" element when 1989 archiving the XML source of an Internet-Draft on the day of 1990 submission. 1992 _Disclaimer: THIS ONLY PROVIDES IMPLEMENTATION INFORMATION. IF YOU 1993 NEED LEGAL ADVICE, PLEASE CONTACT A LAWYER._ For further information, 1994 refer to <http://trustee.ietf.org/docs/IETF-Copyright-FAQ.pdf>. 1996 For the current "Status Of This Memo" text, the "submissionType" 1997 attribute determines whether a statement about "Code Components" is 1998 inserted (which is the case for the value "IETF", which is the 1999 default). Other values, such as "independent", suppress this part of 2000 the text. 2002 A.2.1. Current Values: '*trust200902' 2004 The name for these values refers to the "IETF TRUST Legal Provisions 2005 Relating to IETF Documents", sometimes simply called the "TLP, that 2006 went into effect on February 15, 2009 ([TLP2.0]). Updates to this 2007 document were published on September 12, 2009 ([TLP3.0]) and on 2008 December 28, 2009 ([TLP4.0]), modifying the license for code 2009 components (see <http://trustee.ietf.org/license-info/> for further 2010 information). The actual text is located in Section 6 ("Text To Be 2011 Included in IETF Documents") of these documents. 2013 The tools will automatically produce the "correct" text depending on 2014 the document's date information (see above): 2016 +----------+--------------------------------+ 2017 | TLP | starting with publication date | 2018 +----------+--------------------------------+ 2019 | [TLP3.0] | 2009-11-01 | 2020 | [TLP4.0] | 2010-04-01 | 2021 +----------+--------------------------------+ 2023 A.2.1.1. trust200902 2025 This should be the default, unless one of the more specific 2026 '*trust200902' values is a better fit. It produces the text in 2027 Sections 6.a and 6.b of the TLP. 2029 A.2.1.2. noModificationTrust200902 2031 This produces additional text from Section 6.c.i of the TLP: 2033 This document may not be modified, and derivative works of it may 2034 not be created, except to format it for publication as an RFC or 2035 to translate it into languages other than English. 2037 Note: this clause is incompatible with RFCs that are published on 2038 the Standards Track. 2040 A.2.1.3. noDerivativesTrust200902 2042 This produces the additional text from Section 6.c.ii of the TLP: 2044 This document may not be modified, and derivative works of it may 2045 not be created, and it may not be published except as an Internet- 2046 Draft. 2048 Note: this clause is incompatible with RFCs. 2050 A.2.1.4. pre5378Trust200902 2052 This produces the additional text from Section 6.c.iii of the TLP, 2053 frequently called the "pre-5378 escape clause": 2055 This document may contain material from IETF Documents or IETF 2056 Contributions published or made publicly available before November 2057 10, 2008. The person(s) controlling the copyright in some of this 2058 material may not have granted the IETF Trust the right to allow 2059 modifications of such material outside the IETF Standards Process. 2060 Without obtaining an adequate license from the person(s) 2061 controlling the copyright in such materials, this document may not 2062 be modified outside the IETF Standards Process, and derivative 2063 works of it may not be created outside the IETF Standards Process, 2064 except to format it for publication as an RFC or to translate it 2065 into languages other than English. 2067 See Section 4 of 2068 <http://trustee.ietf.org/docs/IETF-Copyright-FAQ.pdf> for further 2069 information about when to use this value. 2071 Note: this text appears under "Copyright Notice", unless the 2072 document was published before November 2009, in which case it 2073 appears under "Status Of This Memo". 2075 A.2.2. Historic Values 2077 A.2.2.1. Historic Values: '*trust200811' 2079 The attribute values "trust200811", "noModificationTrust200811" and 2080 "noDerivativesTrust200811" are similar to their "trust200902" 2081 counterparts, except that they use text specified in <http:// 2082 trustee.ietf.org/license-info/archive/ 2083 IETF-Trust-License-Policy_11-10-08.pdf>. 2085 A.2.2.2. Historic Values: '*3978' 2087 The attribute values "full3978", "noModification3978" and 2088 "noDerivatives3978" are similar to their counterparts above, except 2089 that they use text specified in RFC 3978 (March 2005). 2091 A.2.2.3. Historic Values: '*3667' 2093 The attribute values "full3667", "noModification3667" and 2094 "noDerivatives3667" are similar to their counterparts above, except 2095 that they use text specified in RFC 3667 (February 2004). 2097 A.2.2.4. Historic Values: '*2026' 2099 The attribute values "full2026" and "noDerivativeWorks2026" are 2100 similar to their counterparts above, except that they use text 2101 specified in RFC 2026 (October 1996). 2103 The special value "none" was also used back then, and denied the IETF 2104 any rights beyond publication as Internet-Draft. 2106 Appendix B. Changes from RFC 2629 ('v1') 2108 [[v1diff: See <http://greenbytes.de/tech/webdav/ 2109 draft-reschke-xml2rfc-02.html#rfc.section.E> for a comparison of the 2110 schemata.]] 2112 B.1. Removed Elements 2114 The <appendix> element has been removed; to generate an appendix, 2115 place a <section> inside <back>. 2117 B.2. Changed Defaults 2119 Many attributes have lost their "default" value; this is to avoid 2120 having document semantics differ based on whether a DTD was specified 2121 and evaluated. Processors will handle absent values the way the 2122 default value was specified before. 2124 B.3. Changed Elements 2126 <artwork>: Has a set of new attributes: "name", "type", "src", 2127 "align", "alt", "width", and "height". (Section 2.5) 2129 <author>: The <organization> element is now optional. The "role" 2130 attribute was added. (Section 2.6) 2132 <country>: The requirement to use ISO 3166 codes was removed. 2133 (Section 2.11) 2135 <date>: All attributes are now optional. (Section 2.13) 2137 <figure>: Has a set of new attributes: "suppress-title", "src", 2138 "align", "alt", "width", and "height". (Section 2.17) 2140 <iref>: Has a new "primary" attribute. (Section 2.20) 2142 <list>: The "style" attribute isn't restricted to a set of enumerated 2143 values anymore. The "hangIndent" and "counter" attributes have been 2144 added. (Section 2.22) 2146 <rfc>: The "ipr" attribute has gained additional values. The 2147 attributes "consensus", "iprExtract", "submissionType", and "xml: 2148 lang" have been added. (Section 2.33) 2150 <reference>: <annotation> allows adding prose to a reference. The 2151 "anchor" attribute has been made mandatory. (Section 2.30) 2153 <references>: Can now appear multiple times, and carry a "title" 2154 attribute (so that normative and informative references can be 2155 split). (Section 2.31) 2157 <section>: The new "toc" attribute controls whether it will appear in 2158 the Table Of Contents. <iref> can now appear as direct child element. 2159 (Section 2.34) 2161 <t>: The "anchor" attribute can now be used as well, however there 2162 are restrictions on how they can be referred to. (Section 2.38) 2164 B.4. New Elements 2166 The following elements have been added: <annotation> (Section 2.3), 2167 <c> (Section 2.8), <cref> (Section 2.12), <format> (Section 2.18), 2168 <spanx> (Section 2.36), <texttable> (Section 2.39). 2170 Appendix C. Relax NG Schema 2171 namespace a = "http://relaxng.org/ns/compatibility/annotations/1.0" 2173 rfc = 2174 element rfc { 2175 attribute number { text }?, 2176 [ a:defaultValue = "" ] attribute obsoletes { text }?, 2177 [ a:defaultValue = "" ] attribute updates { text }?, 2178 attribute category { "std" | "bcp" | "info" | "exp" | "historic" 2179 }?, 2180 attribute consensus { "no" | "yes" }?, 2181 attribute seriesNo { text }?, 2182 attribute ipr { 2183 "full2026" 2184 | "noDerivativeWorks2026" 2185 | "none" 2186 | "full3667" 2187 | "noModification3667" 2188 | "noDerivatives3667" 2189 | "full3978" 2190 | "noModification3978" 2191 | "noDerivatives3978" 2192 | "trust200811" 2193 | "noModificationTrust200811" 2194 | "noDerivativesTrust200811" 2195 | "trust200902" 2196 | "noModificationTrust200902" 2197 | "noDerivativesTrust200902" 2198 | "pre5378Trust200902" 2199 }?, 2200 attribute iprExtract { xsd:IDREF }?, 2201 [ a:defaultValue = "IETF" ] 2202 attribute submissionType { 2203 "IETF" | "IAB" | "IRTF" | "independent" 2204 }?, 2205 attribute docName { text }?, 2206 [ a:defaultValue = "en" ] attribute xml:lang { text }?, 2207 front, 2208 middle, 2209 back? 2210 } 2211 front = 2212 element front { 2213 title, author+, date, area*, workgroup*, keyword*, abstract?, 2214 note* 2215 } 2216 title = 2217 element title { 2218 attribute abbrev { text }?, 2219 text 2220 } 2221 author = 2222 element author { 2223 attribute initials { text }?, 2224 attribute surname { text }?, 2225 attribute fullname { text }?, 2226 attribute role { "editor" }?, 2227 organization?, 2228 address? 2229 } 2230 organization = 2231 element organization { 2232 attribute abbrev { text }?, 2233 text 2234 } 2235 address = element address { postal?, phone?, facsimile?, email?, 2236 uri? } 2237 postal = element postal { street+, (city | region | code | country)* 2238 } 2239 street = element street { text } 2240 city = element city { text } 2241 region = element region { text } 2242 code = element code { text } 2243 country = element country { text } 2244 phone = element phone { text } 2245 facsimile = element facsimile { text } 2246 email = element email { text } 2247 uri = element uri { text } 2248 date = 2249 element date { 2250 attribute day { text }?, 2251 attribute month { text }?, 2252 attribute year { text }?, 2253 empty 2254 } 2255 area = element area { text } 2256 workgroup = element workgroup { text } 2257 keyword = element keyword { text } 2258 abstract = element abstract { t+ } 2259 note = 2260 element note { 2261 attribute title { text }, 2262 t+ 2263 } 2264 middle = element middle { section+ } 2265 section = 2266 element section { 2267 attribute anchor { xsd:ID }?, 2268 attribute title { text }, 2269 [ a:defaultValue = "default" ] 2270 attribute toc { "include" | "exclude" | "default" }?, 2271 (t | figure | texttable | iref)*, 2272 section* 2273 } 2274 t = 2275 element t { 2276 attribute anchor { xsd:ID }?, 2277 attribute hangText { text }?, 2278 (text 2279 | \list 2280 | figure 2281 | xref 2282 | eref 2283 | iref 2284 | cref 2285 | spanx 2286 | vspace)* 2287 } 2288 \list = 2289 element list { 2290 attribute style { text }?, 2291 attribute hangIndent { text }?, 2292 attribute counter { text }?, 2293 t+ 2294 } 2295 xref = 2296 element xref { 2297 attribute target { xsd:IDREF }, 2298 [ a:defaultValue = "false" ] attribute pageno { "true" | "false" 2299 }?, 2300 [ a:defaultValue = "default" ] 2301 attribute format { "counter" | "title" | "none" | "default" }?, 2302 text 2303 } 2304 eref = 2305 element eref { 2306 attribute target { text }, 2307 text 2308 } 2309 iref = 2310 element iref { 2311 attribute item { text }, 2312 [ a:defaultValue = "" ] attribute subitem { text }?, 2313 [ a:defaultValue = "false" ] 2314 attribute primary { "true" | "false" }?, 2315 empty 2316 } 2317 cref = 2318 element cref { 2319 attribute anchor { xsd:ID }?, 2320 attribute source { text }?, 2321 text 2322 } 2323 spanx = 2324 element spanx { 2325 [ a:defaultValue = "preserve" ] 2326 attribute xml:space { "default" | "preserve" }?, 2327 [ a:defaultValue = "emph" ] attribute style { text }?, 2328 text 2329 } 2330 vspace = 2331 element vspace { 2332 [ a:defaultValue = "0" ] attribute blankLines { text }?, 2333 empty 2334 } 2335 figure = 2336 element figure { 2337 attribute anchor { xsd:ID }?, 2338 [ a:defaultValue = "" ] attribute title { text }?, 2339 [ a:defaultValue = "false" ] 2340 attribute suppress-title { "true" | "false" }?, 2341 attribute src { text }?, 2342 [ a:defaultValue = "left" ] 2343 attribute align { "left" | "center" | "right" }?, 2344 [ a:defaultValue = "" ] attribute alt { text }?, 2345 [ a:defaultValue = "" ] attribute width { text }?, 2346 [ a:defaultValue = "" ] attribute height { text }?, 2347 iref*, 2348 preamble?, 2349 artwork, 2350 postamble? 2351 } 2352 preamble = 2353 element preamble { (text | xref | eref | iref | cref | spanx)* } 2354 artwork = 2355 element artwork { 2356 [ a:defaultValue = "preserve" ] 2357 attribute xml:space { "default" | "preserve" }?, 2358 [ a:defaultValue = "" ] attribute name { text }?, 2359 [ a:defaultValue = "" ] attribute type { text }?, 2360 attribute src { text }?, 2361 [ a:defaultValue = "left" ] 2362 attribute align { "left" | "center" | "right" }?, 2364 [ a:defaultValue = "" ] attribute alt { text }?, 2365 [ a:defaultValue = "" ] attribute width { text }?, 2366 [ a:defaultValue = "" ] attribute height { text }?, 2367 text* 2368 } 2369 postamble = 2370 element postamble { (text | xref | eref | iref | cref | spanx)* } 2371 texttable = 2372 element texttable { 2373 attribute anchor { xsd:ID }?, 2374 [ a:defaultValue = "" ] attribute title { text }?, 2375 [ a:defaultValue = "false" ] 2376 attribute suppress-title { "true" | "false" }?, 2377 [ a:defaultValue = "center" ] 2378 attribute align { "left" | "center" | "right" }?, 2379 [ a:defaultValue = "full" ] 2380 attribute style { "all" | "none" | "headers" | "full" }?, 2381 preamble?, 2382 ttcol+, 2383 c*, 2384 postamble? 2385 } 2386 ttcol = 2387 element ttcol { 2388 attribute width { text }?, 2389 [ a:defaultValue = "left" ] 2390 attribute align { "left" | "center" | "right" }?, 2391 text 2392 } 2393 c = element c { (text | xref | eref | iref | cref | spanx)* } 2394 back = element back { references*, section* } 2395 references = 2396 element references { 2397 [ a:defaultValue = "References" ] attribute title { text }?, 2398 reference+ 2399 } 2400 reference = 2401 element reference { 2402 attribute anchor { xsd:ID }, 2403 attribute target { text }?, 2404 front, 2405 seriesInfo*, 2406 format*, 2407 annotation* 2408 } 2409 seriesInfo = 2410 element seriesInfo { 2411 attribute name { text }, 2412 attribute value { text }, 2413 empty 2414 } 2415 format = 2416 element format { 2417 attribute target { text }?, 2418 attribute type { text }, 2419 attribute octets { text }?, 2420 empty 2421 } 2422 annotation = 2423 element annotation { (text | xref | eref | iref | cref | spanx)* } 2424 start = rfc 2426 (This schema was derived from version 1.3.6 of the xml2rfc DTD 2427 ('Document Type Definition', [XML], Section 2.8), available from <htt 2428 p://svn.tools.ietf.org/svn/tools/xml2rfc/vocabulary/v2/03/ 2429 xml2rfcv2.dtd>). 2431 C.1. Checking Validity 2433 The validity of XML files can be checked with any tool that supports 2434 Relax NG ([RNC]). The reference implementation is the Java-based, 2435 open sourced "JING" ([JING]). 2437 To use JING, download the latest ZIP file from the downloads page 2438 (currently <https://code.google.com/p/jing-trang/downloads/ 2439 detail?name=jing-20091111.zip>), extract the archive, copy "jing.jar" 2440 from the "bin" folder, and make sure Java is installed). 2442 To check a file "test.xml" using the RNC file "schema.rnc", run (from 2443 a command line prompt): 2445 java -jar jing.jar -c schema.rnc test.xml 2447 In good Unix tradition, no output means the file is valid. 2449 Appendix D. Proposed Future Changes for 'v3' 2451 Discussion of "v3" changes takes place on the rfc-interest mailing 2452 list (rfc-interest@rfc-editor.org), which has its home page at 2453 <http://www.rfc-editor.org/mailman/listinfo/rfc-interest>. See also 2454 <https://www.rfc-editor.org/rse/wiki/doku.php?id=design:xml-tags> for 2455 a related Wiki page. 2457 D.1. Contact Information 2459 If contact information is changed to allow non-ASCII characters: add 2460 a place for a ASCII fallback (probably just for the author names). 2462 The content model for <postal> ought to be more strict to allow at 2463 most one of <city>, <region>, <code>, and <country>. 2465 It should be possible to have multiple <email> and <uri> elements 2466 (see also <http://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/36>). 2468 <facsimile> looks outdated, while a container for IM (messaging) URIs 2469 is missing. Maybe this area needs to be aligned with vCard. 2471 Section 4.11 of [RFCSTYLE] hints at a "Contributors" Section that 2472 could supply contact information similar to the one in the auto- 2473 generated "Authors' Address" Section. Consider how to capture 2474 contributor contact information (probably not using <author> to avoid 2475 confusion). Furthermore, consider ways to augment the contact 2476 information section with prose. 2478 D.2. Figures 2480 Cleanup the set of overlapping attributes between <figure> and 2481 <artwork>. 2483 For artwork that consists of a sequence of items (such as messages in 2484 a protocol example), it would be good if a <figure> element could 2485 contain multiple <artwork> elements (to assist code to find good 2486 places for page breaks). 2488 Extend <figure> to support different types of artwork (such as by 2489 specifying certain type attribute values, see <http://greenbytes.de/ 2490 tech/webdav/rfc2629xslt/rfc2629xslt.html#artwork.types>), and also 2491 avoid having to markup code (such as ABNF) as "artwork". 2493 It would be good if "code components" could be marked as such. 2495 Finally, even in preformatted text use of markup could be useful to 2496 support (a) references, or (b) highlighting the important bits (<http 2497 ://greenbytes.de/tech/webdav/rfc2629xslt/ 2498 rfc2629xslt.html#ext-rfc2629.artwork>). 2500 D.3. Linking 2502 Extend <xref> so that subsection/anchors can be specified (see <http: 2503 //greenbytes.de/tech/webdav/rfc2629xslt/ 2504 rfc2629xslt.html#ext-rfc2629.xref>). 2506 Remove the "pageno" attribute which seems to be both undocumented and 2507 non-functional. 2509 D.4. Lists 2511 Allow multiple paragraphs in list items; eliminating the need to use 2512 <vspace> -- this could be achieved by adding a list item container 2513 element ("<lt>", see <http://greenbytes.de/tech/webdav/rfc2629xslt/ 2514 rfc2629xslt.html#ext.element.lt> and 2515 <http://www.ietf.org/mail-archive/web/xml2rfc/current/ 2516 msg02010.html>). 2518 Add support for a "dictionary" style; eliminating the need to combine 2519 "hanging" with <vspace> to force new lines (see thread around <http:/ 2520 /www.rfc-editor.org/pipermail/rfc-interest/2013-December/ 2521 005876.html>). 2523 D.5. References 2525 Allow overriding the "anchor" attribute of an included <reference> 2526 element. 2528 Add a way to add prose to a reference that avoids abuse of 2529 <seriesInfo>. 2531 Allow <reference>s that identify a document set such as a BCP. 2533 Deprecate or remove the <format> element; right now it's not used for 2534 the generation of the plain text document anyway. 2536 The "anchor" attribute is optional because it is not needed when 2537 using numeric references (symrefs processing instruction), and the 2538 reference actually is not in use. This is an edge case that doesn't 2539 need special support in the vocabulary and thus should be removed. 2541 D.6. Archival Considerations 2543 When this vocabulary becomes the canonical RFC format, it will need 2544 to be able to capture all generated information, such as section/ 2545 figure/table numbers, plus any auto-generated boilerplate (copyright 2546 statements etc.). 2548 D.7. Document Metadata 2550 Extend the concept of language tagging to at least examples and 2551 contact information to address potential japanese/chinese font 2552 confusion. 2554 Provide a way to indicate the intended level on the standards track. 2556 Include feedback information in a way so that generated documents can 2557 provide usable feedback links (see <http://greenbytes.de/tech/webdav/ 2558 rfc2629xslt/rfc2629xslt.html#ext.element.feedback>). 2560 D.8. Including Material 2562 As discussed in Section 5, file inclusion currently uses out-of-the- 2563 box XML mechanisms or processor-specific directives. 2565 We need to decide whether the vocabulary should have its own 2566 inclusion mechanism, or whether it would be better to use a generic 2567 solution such as [XINCLUDE] instead. 2569 D.9. Misc. 2571 Make the <date> element optional; all of its content is optional 2572 already. 2574 <spanx> has both a weird whitespace model ("preserve") and 2575 problematic styling. Consider to deprecate it in favor of elements 2576 such as <b>, <i>, and <tt>. 2578 Indented paragraphs currently can be created by abusing the <list>. 2579 It would be good to have a special element for this purpose. 2581 Provide a special element for inserting block quotes (<http:// 2582 greenbytes.de/tech/webdav/rfc2629xslt/ 2583 rfc2629xslt.html#ext.element.blockquote>). 2585 The content model for <cref> should be extended to allow more flow 2586 elements, such as <xref> and <eref>. 2588 Section titles should really be elements, not attributes (this would 2589 allow them to contain markup). 2591 Text tables are currently very constrained. For instance, it would 2592 be good if alignment of headers and table cells could be de-coupled 2593 (<http://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/69>). 2595 Counters are currently restricted to lists, figures, and tables. 2596 Maybe there should be a generic mechanism that is not directly tied 2597 to other elements 2598 (<http://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/68>). 2600 Index 2602 A 2603 abbrev attribute 2604 in organization element 20 2605 in title element 32 2606 abstract element 4 2607 inside front 16 2608 address element 4 2609 inside author 9 2610 align attribute 2611 in artwork element 7 2612 in figure element 13 2613 in texttable element 31 2614 in ttcol element 33 2615 alt attribute 2616 in artwork element 7 2617 in figure element 14 2618 anchor attribute 2619 in cref element 11 2620 in figure element 14 2621 in reference element 22 2622 in section element 27 2623 in t element 30 2624 in texttable element 31 2625 annotation element 5 2626 inside reference 22 2627 application/rfc+xml Media Type 38 2628 area element 6 2629 inside front 16 2630 artwork element 6 2631 align attribute 7 2632 alt attribute 7 2633 height attribute 7 2634 inside figure 13 2635 name attribute 7 2636 src attribute 7 2637 type attribute 8 2638 width attribute 8 2639 xml:space attribute 8 2640 Attributes 2641 abbrev 20, 32 2642 align 7, 13, 31, 33 2643 alt 7, 14 2644 anchor 11, 14, 22, 27, 30-31 2645 blankLines 33 2646 category 24 2647 consensus 24 2648 counter 17 2649 day 12 2650 docName 24 2651 format 34 2652 fullname 9 2653 hangIndent 17 2654 hangText 30 2655 height 7, 14 2656 initials 9 2657 ipr 25 2658 iprExtract 25 2659 item 16 2660 month 12 2661 name 7, 28 2662 number 26 2663 obsoletes 26 2664 octets 15 2665 pageno 35 2666 primary 16 2667 role 9 2668 seriesNo 26 2669 source 11 2670 src 7, 14 2671 style 18, 29, 31 2672 subitem 17 2673 submissionType 26 2674 suppress-title 14, 32 2675 surname 9 2676 target 13, 15, 22, 35 2677 title 14, 20, 23, 27, 32 2678 toc 27 2679 type 8, 15 2680 updates 26 2681 value 28 2682 width 8, 15, 33 2683 xml:lang 27 2684 xml:space 8, 29 2685 year 12 2686 author element 8 2687 fullname attribute 9 2688 initials attribute 9 2689 inside front 15 2690 role attribute 9 2691 surname attribute 9 2693 B 2694 back element 9 2695 inside rfc 23 2697 blankLines attribute 2698 in vspace element 33 2700 C 2701 c element 10 2702 inside texttable 31 2703 category attribute 2704 in rfc element 24 2705 city element 10 2706 inside postal 21 2707 code element 10 2708 inside postal 21 2709 consensus attribute 2710 in rfc element 24 2711 counter attribute 2712 in list element 17 2713 country element 11 2714 inside postal 21 2715 cref element 11 2716 anchor attribute 11 2717 inside annotation 5 2718 inside c 10 2719 inside postamble 21 2720 inside preamble 22 2721 inside t 30 2722 source attribute 11 2724 D 2725 date element 11 2726 day attribute 12 2727 inside front 15 2728 month attribute 12 2729 year attribute 12 2730 day attribute 2731 in date element 12 2732 docName attribute 2733 in rfc element 24 2735 E 2736 Elements 2737 abstract 4, 16 2738 address 4, 9 2739 annotation 5, 22 2740 area 6, 16 2741 artwork 6, 13 2742 author 8, 15 2743 back 9, 23 2744 c 10, 31 2745 city 10, 21 2746 code 10, 21 2747 country 11, 21 2748 cref 5, 10-11, 21-22, 30 2749 date 11, 15 2750 email 5, 12 2751 eref 5, 10, 12, 21, 30 2752 facsimile 5, 13 2753 figure 13, 27, 30 2754 format 15, 22 2755 front 15, 22-23 2756 iref 5, 10, 13, 16, 21-22, 27, 30 2757 keyword 16-17 2758 list 17, 30 2759 middle 19, 23 2760 note 16, 19 2761 organization 9, 20 2762 phone 5, 20 2763 postal 5, 20 2764 postamble 13, 21, 31 2765 preamble 13, 21, 31 2766 reference 22-23 2767 references 10, 22 2768 region 21, 23 2769 rfc 23 2770 section 10, 19, 27 2771 seriesInfo 22, 28 2772 spanx 5, 10, 21-22, 28, 30 2773 street 20, 29 2774 t 4, 17, 19, 27, 29 2775 texttable 27, 30 2776 title 15, 32 2777 ttcol 31-32 2778 uri 5, 33 2779 vspace 30, 33 2780 workgroup 16, 34 2781 xref 5, 10, 21, 30, 34 2782 email element 12 2783 inside address 5 2784 eref element 12 2785 inside annotation 5 2786 inside c 10 2787 inside postamble 21 2788 inside preamble 21 2789 inside t 30 2790 target attribute 13 2792 F 2793 facsimile element 13 2794 inside address 5 2795 figure element 13 2796 align attribute 13 2797 alt attribute 14 2798 anchor attribute 14 2799 height attribute 14 2800 inside section 27 2801 inside t 30 2802 src attribute 14 2803 suppress-title attribute 14 2804 title attribute 14 2805 width attribute 15 2806 format attribute 2807 in xref element 34 2808 format element 15 2809 inside reference 22 2810 octets attribute 15 2811 target attribute 15 2812 type attribute 15 2813 front element 15 2814 inside reference 22 2815 inside rfc 23 2816 fullname attribute 2817 in author element 9 2819 H 2820 hangIndent attribute 2821 in list element 17 2822 hangText attribute 2823 in t element 30 2824 height attribute 2825 in artwork element 7 2826 in figure element 14 2828 I 2829 initials attribute 2830 in author element 9 2831 ipr attribute 2832 '*2026' 45 2833 '*3667' 45 2834 '*3978' 45 2835 '*trust200811' 45 2836 '*trust200902' 43 2837 'noDerivativesTrust200902' 44 2838 'noModificationTrust200902' 44 2839 'pre5378Trust200902' 44 2840 'trust200902' 43 2841 in rfc element 25 2842 iprExtract attribute 2843 in rfc element 25 2844 iref element 16 2845 inside annotation 5 2846 inside c 10 2847 inside figure 13 2848 inside postamble 21 2849 inside preamble 22 2850 inside section 27 2851 inside t 30 2852 item attribute 16 2853 primary attribute 16 2854 subitem attribute 17 2855 item attribute 2856 in iref element 16 2858 K 2859 keyword element 17 2860 inside front 16 2862 L 2863 list element 17 2864 counter attribute 17 2865 hangIndent attribute 17 2866 inside t 30 2867 style attribute 18 2868 list styles 2869 empty 18 2870 format ... 18 2871 hanging 18 2872 letters 18 2873 numbers 18 2874 symbols 18 2876 M 2877 Media Type 2878 application/rfc+xml 38 2879 middle element 19 2880 inside rfc 23 2881 month attribute 2882 in date element 12 2884 N 2885 name attribute 2886 in artwork element 7 2887 in seriesInfo element 28 2888 note element 19 2889 inside front 16 2890 title attribute 20 2891 number attribute 2892 in rfc element 26 2894 O 2895 obsoletes attribute 2896 in rfc element 26 2897 octets attribute 2898 in format element 15 2899 organization element 20 2900 abbrev attribute 20 2901 inside author 9 2903 P 2904 pageno attribute 2905 in xref element 35 2906 phone element 20 2907 inside address 5 2908 postal element 20 2909 inside address 5 2910 postamble element 21 2911 inside figure 13 2912 inside texttable 31 2913 preamble element 21 2914 inside figure 13 2915 inside texttable 31 2916 primary attribute 2917 in iref element 16 2919 R 2920 reference element 22 2921 anchor attribute 22 2922 inside references 23 2923 target attribute 22 2924 references element 22 2925 inside back 10 2926 title attribute 23 2927 region element 23 2928 inside postal 21 2929 rfc element 23 2930 category attribute 24 2931 consensus attribute 24 2932 docName attribute 24 2933 ipr attribute 25 2934 iprExtract attribute 25 2935 number attribute 26 2936 obsoletes attribute 26 2937 seriesNo attribute 26 2938 submissionType attribute 26 2939 updates attribute 26 2940 xml:lang attribute 27 2941 role attribute 2942 in author element 9 2944 S 2945 section element 27 2946 anchor attribute 27 2947 inside back 10 2948 inside middle 19 2949 inside section 27 2950 title attribute 27 2951 toc attribute 27 2952 seriesInfo element 28 2953 inside reference 22 2954 name attribute 28 2955 value attribute 28 2956 seriesNo attribute 2957 in rfc element 26 2958 source attribute 2959 in cref element 11 2960 spanx element 28 2961 inside annotation 5 2962 inside c 10 2963 inside postamble 21 2964 inside preamble 22 2965 inside t 30 2966 style attribute 29 2967 xml:space attribute 29 2968 src attribute 2969 in artwork element 7 2970 in figure element 14 2971 street element 29 2972 inside postal 20 2973 style attribute 2974 in list element 18 2975 in spanx element 29 2976 in texttable element 31 2977 subitem attribute 2978 in iref element 17 2979 submissionType attribute 2980 in rfc element 26 2981 suppress-title attribute 2982 in figure element 14 2983 in texttable element 32 2984 surname attribute 2985 in author element 9 2987 T 2988 t element 29 2989 anchor attribute 30 2990 hangText attribute 30 2991 inside abstract 4 2992 inside list 17 2993 inside note 19 2994 inside section 27 2995 target attribute 2996 in eref element 13 2997 in format element 15 2998 in reference element 22 2999 in xref element 35 3000 texttable element 30 3001 align attribute 31 3002 anchor attribute 31 3003 inside section 27 3004 style attribute 31 3005 suppress-title attribute 32 3006 title attribute 32 3007 title attribute 3008 in figure element 14 3009 in note element 20 3010 in references element 23 3011 in section element 27 3012 in texttable element 32 3013 title element 32 3014 abbrev attribute 32 3015 inside front 15 3016 toc attribute 3017 in section element 27 3018 ttcol element 32 3019 align attribute 33 3020 inside texttable 31 3021 width attribute 33 3022 type attribute 3023 in artwork element 8 3024 in format element 15 3026 U 3027 updates attribute 3028 in rfc element 26 3029 uri element 33 3030 inside address 5 3032 V 3033 value attribute 3034 in seriesInfo element 28 3035 vspace element 33 3036 blankLines attribute 33 3037 inside t 30 3039 W 3040 width attribute 3041 in artwork element 8 3042 in figure element 15 3043 in ttcol element 33 3044 workgroup element 34 3045 inside front 16 3047 X 3048 xml:lang attribute 3049 in rfc element 27 3050 xml:space attribute 3051 in artwork element 8 3052 in spanx element 29 3053 xref element 34 3054 format attribute 34 3055 inside annotation 5 3056 inside c 10 3057 inside postamble 21 3058 inside preamble 21 3059 inside t 30 3060 pageno attribute 35 3061 target attribute 35 3062 xref formats 3063 counter 34 3064 default 35 3065 none 35 3066 title 35 3068 Y 3069 year attribute 3070 in date element 12 3072 Author's Address 3074 Julian F. Reschke 3075 greenbytes GmbH 3076 Hafenweg 16 3077 Muenster, NW 48155 3078 Germany 3080 EMail: julian.reschke@greenbytes.de 3081 URI: http://greenbytes.de/tech/webdav/