J. Reschke greenbytes April 11, 2024 Transforming RFC7749-formatted XML through XSLT Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Supported RFC7749 elements . . . . . . . . . . . . . . . . . 5 2.1. Extension elements . . . . . . . . . . . . . . . . . . . 5 3. Processing Instructions . . . . . . . . . . . . . . . . . . . 6 3.1. Supported xml2rfc-compatible PIs . . . . . . . . . . . . 6 3.2. Unsupported xml2rfc-compatible PIs . . . . . . . . . . . 9 3.3. Extension PIs . . . . . . . . . . . . . . . . . . . . . . 9 3.3.1. abort-on - Log Level . . . . . . . . . . . . . . . . 9 3.3.2. allow-markup-in-artwork - Allow certain XML elements inside and . . . . . . . . . . 10 3.3.3. authors-section - Placement of 'Authors' Section . . 10 3.3.4. css-contents - CSS Contents . . . . . . . . . . . . . 10 3.3.5. css-resource - Custom CSS Resource . . . . . . . . . 11 3.3.6. dark-mode - Switch for Enabling 'Dark Mode' Support . 11 3.3.7. diff-uri - URI Template for Internet Draft Diff Links 11 3.3.8. doi-uri - URI Template for DOI Links . . . . . . . . 12 3.3.9. duplex - Support Duplex Printing . . . . . . . . . . 12 3.3.10. errata - Embed Errata Information . . . . . . . . . . 12 3.3.11. html-pretty-print - Switch for Enabling Pretty Printing of Code . . . . . . . . . . . . . . . . . . 13 3.3.12. include-generator - Switch for Disabling Generator Information in Output . . . . . . . . . . . . . . . . 13 3.3.13. include-index - Switch for Disabling Index Generation 14 3.3.14. include-references-in-index - Generate Index Entries for References . . . . . . . . . . . . . . . . . . . 14 3.3.15. insert-metadata - Dynamic Metadata Insertion in HTML 14 3.3.16. internet-draft-base-uri - base URI for RFC reference files . . . . . . . . . . . . . . . . . . . . . . . . 15 3.3.17. internet-draft-uri - URI Template for Interned Drafts 15 3.3.18. justification - Text Justification . . . . . . . . . 15 3.3.19. isbn-uri - URI Template for ISBNs . . . . . . . . . . 16 3.3.20. log-level - Log Level . . . . . . . . . . . . . . . . 16 3.3.21. maxwidth - Maximal Text Width in HTML . . . . . . . . 16 3.3.22. parse-xml-in-artwork - Parse and Check XML in artwork 17 3.3.23. rfc-errata-uri - URI Template for RFC Errata . . . . 17 3.3.24. rfc-erratum-uri - URI Template for a specific RFC Erratum . . . . . . . . . . . . . . . . . . . . . . . 17 3.3.25. rfc-reference--base-uri - base URI for RFC reference files . . . . . . . . . . . . . . . . . . . . . . . . 18 Reschke Expires October 13, 2024 [Page 1] Documentation RFC7749 through XSLT April 2024 3.3.26. rfc-uri - URI Template for HTML Version of RFCs . . . 18 3.3.27. sec-no-trailing-dots - Disable Trailing Dots in Section Numbers . . . . . . . . . . . . . . . . . . . 18 3.3.28. std-uri - URI Template for IETF Standards . . . . . . 19 3.3.29. support-highwire-press-tags - Support 'Highwire Press' Metadata . . . . . . . . . . . . . . . . . . . 19 3.3.30. support-open-graph-tags - Support 'Highwire Press' Metadata . . . . . . . . . . . . . . . . . . . . . . 20 3.3.31. support-rfc2731 - Support RFC 2731 Metadata . . . . . 20 3.3.32. ucd-file - Filename of Unicode Database . . . . . . . 20 3.3.33. xml2rfc-backend - Select xml2rfc Target Version . . . 21 3.3.34. xref-with-text-generate - Default Handling of with Text Content . . . . . . . . . . . . . . . . . . 21 4. Anchors . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 5. Supported XSLT engines . . . . . . . . . . . . . . . . . . . 23 5.1. Standalone Engines . . . . . . . . . . . . . . . . . . . 23 5.2. In-Browser Engines . . . . . . . . . . . . . . . . . . . 23 6. Transforming to HTML . . . . . . . . . . . . . . . . . . . . 24 6.1. HTML compliance . . . . . . . . . . . . . . . . . . . . . 25 6.2. Standard HTML LINK elements . . . . . . . . . . . . . . . 26 6.3. Standard HTML metadata . . . . . . . . . . . . . . . . . 27 6.4. Dublin Core (RFC2731) metadata . . . . . . . . . . . . . 27 6.5. Insertion of Live RFC Meta Data . . . . . . . . . . . . . 28 6.6. Insertion of RFC Errata Links . . . . . . . . . . . . . . 29 7. Transforming to XHTML . . . . . . . . . . . . . . . . . . . . 30 8. Transforming to CHM (Microsoft Compiled Help) . . . . . . . . 30 9. Transforming to PDF . . . . . . . . . . . . . . . . . . . . . 30 9.1. Via XSL-FO . . . . . . . . . . . . . . . . . . . . . . . 30 9.1.1. Example: producing output for Apache FOP . . . . . . 31 9.2. Via HTML . . . . . . . . . . . . . . . . . . . . . . . . 31 10. Transforming to ePub . . . . . . . . . . . . . . . . . . . . 31 11. Generic Extensions . . . . . . . . . . . . . . . . . . . . . 31 11.1. element . . . . . . . . . . . . . . 31 11.2. element . . . . . . . . . . . . . . . . . 32 11.3. element . . . . . . . . . . . . . . . . . . . . . . 32 11.4. element . . . . . . . . . . . . . . . . . . . . . . 32 11.5. element . . . . . . . . . . . . . . . . . . . . 32 11.6.
element . . . . . . . . . . . . . . . . . . 33 11.7. element . . . . . . . . . . . . . . . . . . . . . . 33 11.8. element . . . . . . . . . . . . . . . . . . . . . . 33 11.9. element . . . . . . . . . . . . . . . . . 34 11.10. element . . . . . . . . . . . . . . . . . . . . . 34 11.11. element . . . . . . . . . . . . . . . . . . . 34 11.12. element . . . . . . . . . . . . . . . . . . . . . . 34 11.13. element . . . . . . . . . . . . . . . . . . 34 11.14. element . . . . . . . . . . . . . . . . . . 34 11.15. element . . . . . . . . . . . . . . . . . . . . . 35 11.16. element . . . . . . . . . . . . . . . . . . . . . . 35 Reschke Expires October 13, 2024 [Page 2] Documentation RFC7749 through XSLT April 2024 11.17. element . . . . . . . . . . . . . . . . . . . . . 36 11.18. element . . . . . . . . . . . . . . . . . . 36 11.19. element . . . . . . . . . . . . . . . . . . . . 36 11.20. element . . . . . . . . . . . . . . . . . . . . . . 36 11.21. element . . . . . . . . . . . . . . . . . . . . . 36 11.22. element . . . . . . . . . . . . . . . . . . . . 37 11.23. element . . . . . . . . . . . . . . . . . . . . . 37 11.24. element . . . . . . . . . . . . . . . . . . . . 37 11.25. Extensions to element . . . . . . . . . . . . 37 11.26. Extensions to element . . . . . . . . . . . . . . 38 11.27. Extensions to element . . . . . . . . . . . . . . 38 11.28. Extensions to element . . . . . . . . . . . . . . 38 11.29. Extensions to element . . . . . . . . . . . . . . 39 11.30. Extensions to element . . . . . . . . . . . . . . 39 11.31. Extensions to
element . . . . . . . . . . . . 39 11.32. Extensions to element . . . . . . . . . . . . . . 39 12. Experimental Support for RFC7991bis Vocabulary . . . . . . . 40 12.1. artset Element . . . . . . . . . . . . . . . . . . . . . 40 12.2. aside Element . . . . . . . . . . . . . . . . . . . . . 40 12.3. bcp14 Element . . . . . . . . . . . . . . . . . . . . . 40 12.4. blockquote Element . . . . . . . . . . . . . . . . . . . 40 12.5. boilerplate Element . . . . . . . . . . . . . . . . . . 41 12.6. br Element . . . . . . . . . . . . . . . . . . . . . . . 41 12.7. cityarea Element . . . . . . . . . . . . . . . . . . . . 41 12.8. contact Element . . . . . . . . . . . . . . . . . . . . 41 12.9. displayreference Element . . . . . . . . . . . . . . . . 41 12.10. dd Element . . . . . . . . . . . . . . . . . . . . . . . 41 12.11. dl Element . . . . . . . . . . . . . . . . . . . . . . . 41 12.12. dt Element . . . . . . . . . . . . . . . . . . . . . . . 41 12.13. em Element . . . . . . . . . . . . . . . . . . . . . . . 41 12.14. extaddr Element . . . . . . . . . . . . . . . . . . . . 41 12.15. li Element . . . . . . . . . . . . . . . . . . . . . . . 41 12.16. link Element . . . . . . . . . . . . . . . . . . . . . . 42 12.17. name Element . . . . . . . . . . . . . . . . . . . . . . 42 12.18. ol Element . . . . . . . . . . . . . . . . . . . . . . . 42 12.19. pobox Element . . . . . . . . . . . . . . . . . . . . . 42 12.20. postalLine Element . . . . . . . . . . . . . . . . . . . 42 12.21. refcontent Element . . . . . . . . . . . . . . . . . . . 42 12.22. Extensions to reference Element . . . . . . . . . . . . 42 12.22.1. quoteTitle attribute . . . . . . . . . . . . . . . 42 12.23. referencegroup Element . . . . . . . . . . . . . . . . . 42 12.24. relref Element . . . . . . . . . . . . . . . . . . . . . 42 12.25. Extensions to section Element . . . . . . . . . . . . . 43 12.25.1. numbered attribute . . . . . . . . . . . . . . . . 43 12.25.2. removeInRFC attribute . . . . . . . . . . . . . . . 43 12.26. sortingcode Element . . . . . . . . . . . . . . . . . . 43 12.27. sourcecode Element . . . . . . . . . . . . . . . . . . . 43 12.28. strong Element . . . . . . . . . . . . . . . . . . . . . 43 Reschke Expires October 13, 2024 [Page 3] Documentation RFC7749 through XSLT April 2024 12.29. sub Element . . . . . . . . . . . . . . . . . . . . . . 43 12.30. sup Element . . . . . . . . . . . . . . . . . . . . . . 43 12.31. svg Element . . . . . . . . . . . . . . . . . . . . . . 43 12.32. table Element . . . . . . . . . . . . . . . . . . . . . 43 12.33. tbody Element . . . . . . . . . . . . . . . . . . . . . 43 12.34. td Element . . . . . . . . . . . . . . . . . . . . . . . 44 12.35. tfoot Element . . . . . . . . . . . . . . . . . . . . . 44 12.36. th Element . . . . . . . . . . . . . . . . . . . . . . . 44 12.37. thead Element . . . . . . . . . . . . . . . . . . . . . 44 12.38. tr Element . . . . . . . . . . . . . . . . . . . . . . . 44 12.39. tt Element . . . . . . . . . . . . . . . . . . . . . . . 44 12.40. u Element . . . . . . . . . . . . . . . . . . . . . . . 44 12.41. ul Element . . . . . . . . . . . . . . . . . . . . . . . 44 12.42. Extensions to xref Element . . . . . . . . . . . . . . . 44 12.42.1. relative attribute . . . . . . . . . . . . . . . . 45 12.42.2. section attribute . . . . . . . . . . . . . . . . . 45 12.42.3. sectionFormat attribute . . . . . . . . . . . . . . 45 12.43. xi:include Element . . . . . . . . . . . . . . . . . . . 45 13. Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . 45 13.1. Checking References . . . . . . . . . . . . . . . . . . 45 13.2. Generating Graphs from References . . . . . . . . . . . 47 13.3. Producing reference entries for books . . . . . . . . . 47 13.4. Down-converting to RFC 7749 Grammar . . . . . . . . . . 48 13.5. Extracting artwork . . . . . . . . . . . . . . . . . . . 49 13.6. GRRDL . . . . . . . . . . . . . . . . . . . . . . . . . 50 13.7. HTML Live Refresh . . . . . . . . . . . . . . . . . . . 50 13.8. Refreshing included material in the XML source . . . . . 51 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 55 14.1. Informative References . . . . . . . . . . . . . . . . . 55 14.2. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Appendix A. RELAX NG Compact Schema . . . . . . . . . . . . . . 57 Appendix B. Implementation Notes . . . . . . . . . . . . . . . . 84 B.1. Recognized type attributes for element . . . . 84 Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 85 C.1. Using the 'Internal Subset' . . . . . . . . . . . . . . . 86 C.2. Customization . . . . . . . . . . . . . . . . . . . . . . 86 Appendix D. Producing the IETF 'Boilerplate' . . . . . . . . . . 87 Appendix E. License . . . . . . . . . . . . . . . . . . . . . . 88 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 100 1. Introduction This document describes a set of XSLT transformations that can be used to transform "XML2RFC" XML ([RFC7749], updating [RFC2629]) to various output formats, such as HTML and PDF. The main topics are o compliance to the xml2rfc XML element set (Section 2), Reschke Expires October 13, 2024 [Page 4] Documentation RFC7749 through XSLT April 2024 o support for xml2rfc processing instructions (Section 3), o the names of anchor elements generated in HTML and PDF output (Section 4), o various XSLT engines that can be used (Section 5), o outputting HTML (Section 6) and XHTML (Section 7), o outputting CHM (Compiled Microsoft Help, Section 8), o outputting PDF (Section 9), o outputting ePub (Section 10), o extensions to the xml2rfc vocabulary (Section 11), o selected extensions from the proposed xml2rfc V3 vocabulary (Section 12), o various utilities (Section 13). The full distribution is available at . A mirror of the non-public source repository can be found at ; this is also a good place for reporting issues. _Note:_ RFC 2629 was the initial specification of the XML vocabulary; that's why the "2629" lives on in various parts, such as filenames. 2. Supported RFC7749 elements "rfc2629.xslt" supports both all grammar elements defined in [RFC7749], plus a subset of the new elements defined in [RFC7991bis]. 2.1. Extension elements "rfc2629.xslt" supports two kind of extension elements, using different XML namespaces. The first set contains (hopefully) generally useful extensions, see Section 11. The second set is used for change and issue tracking and currently is not documented here. Please email the author in case you're interested in using these extensions. Reschke Expires October 13, 2024 [Page 5] Documentation RFC7749 through XSLT April 2024 3. Processing Instructions All PIs can be set as XSLT parameter as well, overriding any value that is found in the source file to be transformed. Using processing instructions: Using XSLT parameters (Saxon): java -cp saxon.jar com.icl.saxon.StyleSheet source.xml rfc2629.xslt \ xml2rfc-toc=yes xml2rfc-ext-support-rfc2731=no > result.html Using XSLT parameters (xsltproc): xsltproc --param xml2rfc-toc '"yes"' \ --param xml2rfc-ext-support-rfc2731 '"no"' \ rfc2629.xslt source.xml > result.html (note the required quoting of string parameters) 3.1. Supported xml2rfc-compatible PIs +------+--------------+--------------------+-----------+------------+ | PI t | PI pseudo- | XSLT parameter | default | comment | | arge | attribute | name | | | | t | | | | | +------+--------------+--------------------+-----------+------------+ | rfc | authorship | xml2rfc-authorship | "yes" | when set | | | | | | to "no", | | | | | | the | | | | | | "Authors" | | | | | | section is | | | | | | suppressed | | | | | | | | rfc | background | xml2rfc-background | (not set) | | | | | | | | | rfc | compact | xml2rfc-compact | "no" | only | | | | | | applies to | | | | | | HTML | | | | | | output | | | | | | method | | | | | | when | | | | | | printing | | | | | | | | rfc | comments | xml2rfc-comments | "no" | | Reschke Expires October 13, 2024 [Page 6] Documentation RFC7749 through XSLT April 2024 | | | | ("yes" | | | | | | for v3 do | | | | | | cuments) | | | | | | | | | rfc | docmapping | | "yes" | This is | | | | | | the | | | | | | default | | | | | | for rfc262 | | | | | | 9.xslt | | | | | | anyway, | | | | | | and it can | | | | | | not be | | | | | | changed | | | | | | | | rfc | editing | xml2rfc-editing | "no" | | | | | | | | | rfc | footer | xml2rfc-footer | (not set) | | | | | | | | | rfc | header | xml2rfc-header | (not set) | | | | | | | | | rfc | include | | | only | | | | | | partly | | | | | | supported, | | | | | | use | | | | | | external | | | | | | entities | | | | | | instead | | | | | | (see Appen | | | | | | dix C.1) | | | | | | or other | | | | | | tools (Sec | | | | | | tion 13.8) | | | | | | instead | | | | | | | | rfc | inline | xml2rfc-inline | "no" | | | | | | ("yes" | | | | | | for v3 do | | | | | | cuments) | | | | | | | | | rfc | iprnotified | xml2rfc- | "no" | | | | | iprnotified | | | | | | | | | | rfc | linkmailto | xml2rfc-linkmailto | "yes" | | | | | | | | | rfc | multiple- | xml2rfc-multiple- | "no" | determines | | | initials | initials | | whether | | | | | | the | | | | | | processor | Reschke Expires October 13, 2024 [Page 7] Documentation RFC7749 through XSLT April 2024 | | | | | will | | | | | | attempt to | | | | | | truncate | | | | | | multiple | | | | | | initials | | | | | | to a | | | | | | single | | | | | | one; can | | | | | | be set | | | | | | globally | | | | | | (affecting | | | | | | the front | | | | | | page) but | | | | | | also as | | | | | | child | | | | | | element of | | | | | | | | | | | | | | rfc | private | xml2rfc-private | (not set) | | | | | | | | | rfc | refparent | xml2rfc-private | "Referenc | Title for | | | | | es" | References | | | | | | sections | | | | | | when autom | | | | | | atically | | | | | | inserted | | | | | | | | rfc | rfcedstyle | xml2rfc-rfcedstyle | (not set) | (limited | | | | | | support) | | | | | | | | rfc | sortrefs | xml2rfc-sortrefs | "no" | | | | | | | | | rfc | symrefs | xml2rfc-symrefs | "yes" | The | | | | | | default | | | | | | has | | | | | | changed | | | | | | from "no" | | | | | | to "yes" | | | | | | as of June | | | | | | 6, 2007 | | | | | | and | | | | | | xml2rfc | | | | | | 1.33pre4. | | | | | | | | rfc | toc | xml2rfc-toc | "no" | | | | | | ("yes" | | | | | | for | | Reschke Expires October 13, 2024 [Page 8] Documentation RFC7749 through XSLT April 2024 | | | | documents | | | | | | specifyin | | | | | | g "3" as | | | | | | vocabular | | | | | | y | | | | | | version) | | | | | | | | | rfc | tocdepth | xml2rfc-tocdepth | 99 | | | | | | | | | rfc | topblock | xml2rfc-topblock | "yes" | | +------+--------------+--------------------+-----------+------------+ 3.2. Unsupported xml2rfc-compatible PIs +-----------+---------------------+---------------------+ | PI target | PI pseudo-attribute | comment | +-----------+---------------------+---------------------+ | rfc | needLines | | | | | | | rfc | slides | | | | | | | rfc | strict | | | | | | | rfc | subcompact | | | | | | | rfc | tocindent | (defaults to "yes") | | | | | | rfc | tocompact | | +-----------+---------------------+---------------------+ 3.3. Extension PIs 3.3.1. abort-on - Log Level PI target rfc-ext PI pseudo-attribute abort-on XSLT parameter name xml2rfc-ext-abort-on default "OFF" Reschke Expires October 13, 2024 [Page 9] Documentation RFC7749 through XSLT April 2024 Controls at which log level a message causes the XSLT to be aborted (one of "OFF", "FATAL", "ERROR", "WARNING", "INFO", "DEBUG", "TRACE"). 3.3.2. allow-markup-in-artwork - Allow certain XML elements inside and PI target rfc-ext PI pseudo-attribute allow-markup-in-artwork XSLT parameter name xml2rfc-ext-allow-markup-in-artwork default "no" Enables support for specific elements inside and elements (using this extension makes the document incompatible to the RFC7749 grammar; see description of conversion XSLT in Section 13.4). 3.3.3. authors-section - Placement of 'Authors' Section PI target rfc-ext PI pseudo-attribute authors-section XSLT parameter name xml2rfc-ext-authors-section default "end" When "before-appendices", place the authors section between references and appendices (this ordering was used a long time ago). 3.3.4. css-contents - CSS Contents PI target rfc-ext PI pseudo-attribute css-contents Reschke Expires October 13, 2024 [Page 10] Documentation RFC7749 through XSLT April 2024 XSLT parameter name xml2rfc-ext-css-contents default none CSS content to use instead of the built-in (experimental). 3.3.5. css-resource - Custom CSS Resource PI target rfc-ext PI pseudo-attribute css-resource XSLT parameter name xml2rfc-ext-css-resource default none Name of CSS resource (URI or relate reference) to use instead of the built-in (experimental). 3.3.6. dark-mode - Switch for Enabling 'Dark Mode' Support PI target rfc-ext PI pseudo-attribute dark-mode XSLT parameter name xml2rfc-ext-dark-mode default "no" Set to 'auto' to enable "dark mode" CSS support. 3.3.7. diff-uri - URI Template for Internet Draft Diff Links PI target rfc-ext PI pseudo-attribute diff-uri Reschke Expires October 13, 2024 [Page 11] Documentation RFC7749 through XSLT April 2024 XSLT parameter name xml2rfc-ext-diff-uri default "https://www.ietf.org/rfcdiff?url2={internet-draft}" URI template for Internet Draft Diff links. 3.3.8. doi-uri - URI Template for DOI Links PI target rfc-ext PI pseudo-attribute doi-uri XSLT parameter name xml2rfc-ext-doi-uri default "https://dx.doi.org/{doi}" URI template for DOIs links. 3.3.9. duplex - Support Duplex Printing PI target rfc-ext PI pseudo-attribute duplex XSLT parameter name xml2rfc-ext-duplex default "no" When set to "yes", format printed output for doublesided printing. 3.3.10. errata - Embed Errata Information PI target rfc-ext PI pseudo-attribute errata Reschke Expires October 13, 2024 [Page 12] Documentation RFC7749 through XSLT April 2024 XSLT parameter name xml2rfc-ext-errata default none Can be used to specify an errata file; output will link to individual errata when possible. See Section 6.6. 3.3.11. html-pretty-print - Switch for Enabling Pretty Printing of Code PI target rfc-ext PI pseudo-attribute html-pretty-print XSLT parameter name xml2rfc-ext-html-pretty-print default none Used to specify a JS-based code pretty-printer; the value is the CSS class name to insert, followed by a blank space, followed by the URI of the JS library. For instance: "prettyprint https://cdn.rawgit.com/google/code-prettify/master/loader/ run_prettify.js" 3.3.12. include-generator - Switch for Disabling Generator Information in Output PI target rfc-ext PI pseudo-attribute include-generator XSLT parameter name xml2rfc-ext-include-generator default "yes" Set to 'no' in order to disable inclusion of generator version information. Reschke Expires October 13, 2024 [Page 13] Documentation RFC7749 through XSLT April 2024 3.3.13. include-index - Switch for Disabling Index Generation PI target rfc-ext PI pseudo-attribute include-index XSLT parameter name xml2rfc-ext-include-index default "yes" When set to "no", no index will be generated. 3.3.14. include-references-in-index - Generate Index Entries for References PI target rfc-ext PI pseudo-attribute include-references-in-index XSLT parameter name xml2rfc-ext-include-references-in-index default "no" When set to "yes", index entries are generated for all references. 3.3.15. insert-metadata - Dynamic Metadata Insertion in HTML PI target rfc-ext PI pseudo-attribute insert-metadata XSLT parameter name xml2rfc-ext-insert-metadata default "yes" Reschke Expires October 13, 2024 [Page 14] Documentation RFC7749 through XSLT April 2024 When set to "yes", include JS code that fetches current RFC/Internet- Draft metadata and inserts it into the front page (standards track, obsoletion, updates, errata, freshness of draft...). 3.3.16. internet-draft-base-uri - base URI for RFC reference files PI target rfc-ext PI pseudo-attribute internet-draft-reference-base-uri XSLT parameter name xml2rfc-ext-internet-draft-reference-base-uri default "https://bib.ietf.org/public/rfc/bibxml-ids/" Base URI for Internet-Draft referennces included using the "include" processing instruction. 3.3.17. internet-draft-uri - URI Template for Interned Drafts PI target rfc-ext PI pseudo-attribute internet-draft-uri XSLT parameter name xml2rfc-ext-internet-draft-uri default "https://datatracker.ietf.org/doc/html/{internet-draft}" URI template for Internet-Draft links (can be set locally inside the element as well to override the default). 3.3.18. justification - Text Justification PI target rfc-ext PI pseudo-attribute justification XSLT parameter name xml2rfc-ext-justification Reschke Expires October 13, 2024 [Page 15] Documentation RFC7749 through XSLT April 2024 default "never" "never": never emit justified text, "always": always emit justified text, "print": only emit justified text for print media. 3.3.19. isbn-uri - URI Template for ISBNs PI target rfc-ext PI pseudo-attribute isbn-uri XSLT parameter name xml2rfc-ext-isbn-uri default "https://www.worldcat.org/search?q=isbn:{isbn}" URI template for ISBN lookup. 3.3.20. log-level - Log Level PI target rfc-ext PI pseudo-attribute log-level XSLT parameter name xml2rfc-ext-log-level default "WARNING" Logging level, one of "OFF", "FATAL", "ERROR", "WARNING", "INFO", "DEBUG", "TRACE". 3.3.21. maxwidth - Maximal Text Width in HTML PI target rfc-ext PI pseudo-attribute maxwidth XSLT parameter name Reschke Expires October 13, 2024 [Page 16] Documentation RFC7749 through XSLT April 2024 xml2rfc-ext-maxwidth default 1000 For HTML output: maximal text width in CSS pixels. 3.3.22. parse-xml-in-artwork - Parse and Check XML in artwork PI target rfc-ext PI pseudo-attribute parse-xml-in-artwork XSLT parameter name xml2rfc-ext-parse-xml-in-artwork default "no" May be used to enable parsing of XML content in figures (MSXML only). 3.3.23. rfc-errata-uri - URI Template for RFC Errata PI target rfc-ext PI pseudo-attribute rfc-errata-uri XSLT parameter name xml2rfc-ext-rfc-errata-uri default "https://www.rfc-editor.org/errata/rfc{rfc}" URI template for all RFC Errata for a given RFC ("rfc" is the RFC number). 3.3.24. rfc-erratum-uri - URI Template for a specific RFC Erratum PI target rfc-ext PI pseudo-attribute rfc-erratum-uri Reschke Expires October 13, 2024 [Page 17] Documentation RFC7749 through XSLT April 2024 XSLT parameter name xml2rfc-ext-rfc-erratum-uri default "https://www.rfc-editor.org/errata/eid{eid}" URI template for a specific RFC erratum ("eid" is the "errata id"). 3.3.25. rfc-reference--base-uri - base URI for RFC reference files PI target rfc-ext PI pseudo-attribute rfc-reference-base-uri XSLT parameter name xml2rfc-ext-rfc-reference-base-uri default "https://bib.ietf.org/public/rfc/bibxml/" Base URI for RFC referennces included using the "include" processing instruction. 3.3.26. rfc-uri - URI Template for HTML Version of RFCs PI target rfc-ext PI pseudo-attribute rfc-uri XSLT parameter name xml2rfc-ext-rfc-uri default "https://www.rfc-editor.org/rfc/rfc{rfc}.html" (previously "https://tools.ietf.org/html/rfc{rfc}") URI Template for HTML Version of RFCs. 3.3.27. sec-no-trailing-dots - Disable Trailing Dots in Section Numbers PI target rfc-ext PI pseudo-attribute Reschke Expires October 13, 2024 [Page 18] Documentation RFC7749 through XSLT April 2024 sec-no-trailing-dots XSLT parameter name xml2rfc-ext-sec-no-trailing-dots default none When set to "no", do not add trailing dots to section numbers (this was the preference in the distant past). 3.3.28. std-uri - URI Template for IETF Standards PI target rfc-ext PI pseudo-attribute std-uri XSLT parameter name xml2rfc-ext-std-uri default "https://www.rfc-editor.org/info/std{std}" URI Template for IETF Standards. 3.3.29. support-highwire-press-tags - Support 'Highwire Press' Metadata PI target rfc-ext PI pseudo-attribute support-highwire-press-tags XSLT parameter name xml2rfc-ext-support-highwire-press-tags default "yes" Decides whether the HTML transformation should generate 'Highwire Press' META tags, as used by Google Scholar. Reschke Expires October 13, 2024 [Page 19] Documentation RFC7749 through XSLT April 2024 3.3.30. support-open-graph-tags - Support 'Highwire Press' Metadata PI target rfc-ext PI pseudo-attribute support-open-graph-tags XSLT parameter name xml2rfc-ext-support-open-graph-tags default "yes" Decides whether the HTML transformation should generate 'Open Graph' META tags, as used by Twitter. 3.3.31. support-rfc2731 - Support RFC 2731 Metadata PI target rfc-ext PI pseudo-attribute support-rfc2731 XSLT parameter name xml2rfc-ext-support-rfc2731 default "yes" Decides whether the HTML transformation should generate META tags according Section 6.4. 3.3.32. ucd-file - Filename of Unicode Database PI target rfc-ext PI pseudo-attribute ucd-file XSLT parameter name xml2rfc-ext-ucd-file default none Reschke Expires October 13, 2024 [Page 20] Documentation RFC7749 through XSLT April 2024 Specifies an external resource containing Unicode character database information, as described in Section 11.24. 3.3.33. xml2rfc-backend - Select xml2rfc Target Version PI target rfc-ext PI pseudo-attribute xml2rfc-backend XSLT parameter name xml2rfc-ext-xml2rfc-backend default based on document date Used in "clean-for-DTD.xslt" (see Section 13.4). 3.3.34. xref-with-text-generate - Default Handling of with Text Content PI target rfc-ext PI pseudo-attribute xref-with-text-generate XSLT parameter name xml2rfc-ext-xref-with-text-generate default "text" Determines whether with text content generates additional text as in traditional text output ("text"), or just generates a link around the text ("nothing"). Note that the default might change in the future in order to achieve compatibility with other formatters. 4. Anchors The transformation automatically generates anchors that are supposed to be stable and predictable and that can be used to identify specific parts of the document. Anchors are generated both in HTML and XSL-FO content (but the latter will only be used for PDF output when the XSL-FO engine supports producing PDF anchors). Reschke Expires October 13, 2024 [Page 21] Documentation RFC7749 through XSLT April 2024 The following anchors get auto-generated: +------------------------+---------------------------------------+ | Anchor name | Description | +------------------------+---------------------------------------+ | rfc.abstract | Abstract | | | | | rfc.authors | Authors section | | | | | rfc.copyright | Copyright section | | | | | rfc.copyrightnotice | Copyright notice | | | | | rfc.figure._n_ | Figures (titled) | | | | | rfc.figure.u._n_ | Figures (untitled) | | | | | rfc.index | Index | | | | | rfc.ipr | Intellectual Property | | | | | rfc.iref._n_ | Internal references | | | | | rfc.note._n_ | Notes (from front section) | | | | | rfc.references | References | | | | | rfc.references._n_ | Additional references | | | | | rfc.section._n_ | Section _n_ | | | | | rfc.section._n_.p._m_ | Section _n_, paragraph _m_ | | | | | rfc.status | Status of memo | | | | | rfc.table._n_ | Tables (titled) | | | | | rfc.table.u._n_ | Tables (untitled) | | | | | rfc.toc | Table of contents | | | | | rfc.xref._name_._n_ | References to reference _n_ to _name_ | +------------------------+---------------------------------------+ Reschke Expires October 13, 2024 [Page 22] Documentation RFC7749 through XSLT April 2024 5. Supported XSLT engines The transformation requires a non-standard extension function (see exsl:node-set [1]) which is however widely available. XSLT processors that do not support this extension (or a functional equivalent, such as msxsl:node-set) currently are not supported. Input documents do not always specify the date completely. In this case, the transformation attempts to let the XSLT engine to compute the system date, using either scripting in Microsoft's XSLT engine, or the exsl:date-time [2] extension function. 5.1. Standalone Engines The following XSLT engines are believed to work well: o Windows: MSXML3 and MSXML4 (; command line processor "msxsl" is available from Microsoft Download Center [3]) o Java: Saxon () o Java: Xalan () o C/C++: xsltproc (libxslt) (, make sure that you have a current version, also: does not support inclusion of "https" resources -- ) 5.2. In-Browser Engines The following browsers seem to work fine: o Internet Explorer 6 and newer o Firefox 3.0 and newer * Be aware that XSLT execution can be suppressed using NoScript [4] * There seems to be a new problem in Firefox 4 where it occasionally does the initial rendering with the wrong width (people who can reproduce this problem please comment on . Reschke Expires October 13, 2024 [Page 23] Documentation RFC7749 through XSLT April 2024 * Date computation is available in Firefox starting with Firefox 6 (see ) o Safari 3 (starting with version 3.0.4) * Date computation not available (see ) o Google Chrome * Date computation not available (see ) Note that browsers in general do not load external DTDs nor external entities (see, for instance, Mozilla Bug 22942 [5]) thus entities like   need to be declared in the internal subset (Appendix C.1). The following browsers are known not to work properly: o Firefox 1.*/2.*: (missing extension function - see change request at Mozilla BugZilla 193678 [6]) o Opera 9.21: execution fails, potentially to a somewhat complex XPath expression (reported to Opera as bug 245725). o Opera 9.5 and 9.6: transformation appears to work, but CSS isn't getting applied (reported to Opera as bug 337388 on 2008-06-12). o Safari 2.* supports client-side XSLT as of MacOS X 10.4, but misses required extension functions. A problem with stylesheets producing non-ASCII output (such as NBSP characters) has been fixed as of OSX 10.4.4. Both problems have been reported through Apple's bug tracking system, see and . 6. Transforming to HTML Transformation to HTML can be done inside the browser if it supports XSLT. To enable this, add the following processing instruction to the start of the source file: Reschke Expires October 13, 2024 [Page 24] Documentation RFC7749 through XSLT April 2024 (and ensure that "rfc2629.xslt" is present). 6.1. HTML compliance The transformation result is supposed to conform to HTML5 [HTML5]. This can be checked using the W3C's online validator at . XSLT 1.0 is not capable to directly emit the HTML doctype declaration, thus uses the SYSTEM ID "about:legacy-compat" instead (see Section 8.1.1 of [HTML5]). When not run in a browser, the doctype declaration can be adjusted using a small script, such as with: saxon test.xml rfc2629.xslt | awk -f html5doctype.awk with Reschke Expires October 13, 2024 [Page 25] Documentation RFC7749 through XSLT April 2024 #!/usr/bin/awk -f # waitfordoctype: # 0: wait for line starting with DOCTYPE and eat empty lines # 1: wait for line starting with \n") } else { print } } { if (waitfordoctype == 0 && $0 != "") { print } else if (waitfordoctype == 2) { print } } 6.2. Standard HTML LINK elements LINK elements exist since HTML 2.0. They can be used to embed content-independant links inside the document. Unfortunately, only few user agents support this element. Firefox users may want to check the Link Widgets [7] extension. Reschke Expires October 13, 2024 [Page 26] Documentation RFC7749 through XSLT April 2024 The following LINK elements are produced: +-----------+-------------------------------------------------------+ | LINK type | description | +-----------+-------------------------------------------------------+ | alternate | for RFCs, a link to the authorative ASCII version on | | | the IETF web site | | | | | appendic | pointer to all top-level appendics | | | | | author | pointer to "authors" section | | | | | chapter | pointer to all top-level sections | | | | | contents | pointer to table of contents | | | | | copyright | pointer to copyright statement | | | | | index | pointer to index | +-----------+-------------------------------------------------------+ The figure below shows how Mozilla Firefox 1.0 displays the Site Navigation Bar for rfc2396.xml. (LINK elements displayed in Mozilla Firefox for RFC2396.xml) 6.3. Standard HTML metadata The following standard HTML META elements are produced: +-----------+-------------------------------------------------+ | META name | description | +-----------+-------------------------------------------------+ | generator | from XSLT engine version and stylesheet version | | | | | keywords | from keyword elements in front section | +-----------+-------------------------------------------------+ 6.4. Dublin Core (RFC2731) metadata Unless turned off using the "rfc-ext support-rfc2731" processing instruction, the transformation will generate metadata according to [RFC2731] and [DC-HTML]. Reschke Expires October 13, 2024 [Page 27] Documentation RFC7749 through XSLT April 2024 The following DCMI properties are produced: +-------------------------+-----------------------------------------+ | META name | description | +-------------------------+-----------------------------------------+ | DC.Creator | from author information in front | | | section | | | | | DC.Date.Issued | from date information in front section | | | | | DC.Description.Abstract | from abstract | | | | | DC.Identifier | document URN [RFC2648] from "docName" | | | attribute | | | | | DC.isPartOf | RFC ISSN (for RFCs) | | | | | DC.Relation.Replaces | from "obsoletes" attribute | +-------------------------+-----------------------------------------+ 6.5. Insertion of Live RFC Meta Data RFCs are immutable; once published, they do not change anymore. What _does_ change though is their status, their relation to subsequent RFCs (such as when they are updated), and errata. "rfc2629toXHTML.xslt" by default inserts code that will pull the relevant information from . This can be disabled by specifying the parameter "xml2rfc-ext-insert-metadata=no" (or by inserting the equivalent processing instruction into the source code). An example for the generated information can be seen at . *Note:* the status information really should be available from the RFC Editor, right now it only exists only in HTML form (such as in . Furthermore, the service provided by is considered experimental, so this feature might be changed or removed without prior notice. ...and no, we currently can't obtain the exact list of errata, just a flag indicating whether errata exist. Reschke Expires October 13, 2024 [Page 28] Documentation RFC7749 through XSLT April 2024 6.6. Insertion of RFC Errata Links Unfortunately, the RFC Editor does not provide errata information in a well-defined machine readable format. What's available is "regular" HTML (and that could be the worst currently in use in standards bodies...). "parse-errata.xslt" attempts to parse useful information out of these pages. It can be run like that (requires an XSLT2 processor): # get the raw html and strip form feed characters curl -s https://www.rfc-editor.org/errata_search.php?rfc=2616 \ | tr -d '\f' > rfc2616.rawerrata # regexps are your friend saxon97he parse-errata.xslt parse-errata.xslt doc=2616 > rfc2616.errata The code tries to make sense of the HTML, in particular it tries to detect what RFC sections each erratum applies to. The resulting XML format is work-in-progress and just contains the information that will be useful in subsequent formatting of the RFC. When _formatting_ the RFC for HTML output, the errata file can be passed as stylesheet parameter ("xml2rfc-ext-errata"). The output will include errata links at the beginnings of the section they apply to, or at the beginning of Section 1 when the location is unknown. For the sake of embedding, three types of errata are relevant; their type is indicated with a symbol: o "held for update": reviewed and decided to be "held for document update" (these are mostly editorial); "scissors" symbol. o "submitted": submitted, but not reviewed; "letter" symbol. o "verified": reviewed and found to be correct; "checkmark" symbol. To recap: the errata information is passed into the transformation as additional parameter. The errata information will _not_ be automatically retrieved from the RFC Editor web site. Finally, here's an example for inserted errata links: . Reschke Expires October 13, 2024 [Page 29] Documentation RFC7749 through XSLT April 2024 7. Transforming to XHTML Transforming to XHTML requires slightly different XSLT output options and is implemented by the derived transformation script "rfc2629toXHTML.xslt". 8. Transforming to CHM (Microsoft Compiled Help) To generate a CHM file using Microsoft's HTML Help Compiler (hhc), three files are required in addition to the HTML file. 1. hhc - table of contents file (HTML) 2. hhk - index file (HTML) 3. hhp - project file (plain text) The three files are generated with three specific transformations, each requiring the additional XSLT parameter "basename" to specify the filename prefix. Example: saxon rfc2616.xml rfc2629toHhp.xslt basename=rfc2616 > rfc2616.hhp saxon rfc2616.xml rfc2629toHhc.xslt basename=rfc2616 > rfc2616.hhc saxon rfc2616.xml rfc2629toHhk.xslt basename=rfc2616 > rfc2616.hhk hhc rfc2616.hhp 9. Transforming to PDF 9.1. Via XSL-FO Transformation to XSL-FO [XSL-FO] format is available through "rfc2629toFO.xslt" (which includes "rfc2629.xslt", so keep both in the same folder). Compared to HTML user agents, XSL-FO engines unfortunately either come as open source (for instance, Apache FOP) or feature-complete (for instance, AntennaHouse XSL Formatter), but not both at the same time. As Apache FOP needs special workarounds (index generation), and some popular extensions aren't standardized yet, the translation produces a generic output (hopefully) conforming to [XSL-FO]. Specific backends ("xsl11toFop.xslt", "xsl11toXep.xslt", "xsl11toAn.xslt") then provide post-processing for the individual processors. Note: the output is currently targeted at Apache FOP 1.1. Reschke Expires October 13, 2024 [Page 30] Documentation RFC7749 through XSLT April 2024 9.1.1. Example: producing output for Apache FOP Example: saxon rfc2616.xml rfc2629toFo.xslt > tmp.fo saxon tmp.fo xsl11toFop.xslt > rfc2629.fo 9.2. Via HTML PDF output can also be produced directly from (X)HTML. One simple approach is to rely on the browser's printing function, and to use a printer driver that produces PDF. Depending on the brower's CSS capabilities, the output will behave properly with respect to table breaks etc. Alternatives are tools which can produce PDF directly from (X)HTML input, based on the CSS printing information. For instance: "PrinceXML" () and "WeasyPrint" (). For instance, PDF output can be produced with: saxon input.xml rfc2629.xslt > output.html weasyprint output.html output.pdf 10. Transforming to ePub Experimental transformation to ePub format is available through a set of stylesheets, and the Unix Shell script "mkepub.sh" (which requires that "zip" and either "saxon" or "xsltproc" are installed). For instance, an epub version of rfc2616.xml can be generated like this: mkepub.sh rfc2616.xml 11. Generic Extensions This section documents extensions implemented in "rfc2629.xslt", using the extension namespace "http://purl.org/net/xml2rfc/ext". 11.1. element Converts the contained quoted string into a hex-encoded character sequence, for use in case-sensitive ABNF productions. For instance, ""HTTP"" gets converted to "%x48.54.54.50". Reschke Expires October 13, 2024 [Page 31] Documentation RFC7749 through XSLT April 2024 11.2. element Using its "value" attribute, this element allows the definition of an internal link target alias for the enclosing element. This alias can then be used with the element for intra-document references. Note that the anchor alias is not subject to the naming constraints that apply to anchor elements (which are XML names [8]). 11.3. element Marking up a string as indicates that it represents the bottom line of a box drawing, replacing the "+" and "-" characters accordingly. 11.4. element Marking up a string as indicates that it represents a center line of a box drawing, replacing the "|" character accordingly. 11.5. element This element marks the content as being one of the normative keywords defined in [RFC2119]. Reschke Expires October 13, 2024 [Page 32] Documentation RFC7749 through XSLT April 2024 The DOCTYPE definition below allows using these keywords using XML entity expansion: such as in "...server &MUST; accept...". MAY"> MUST"> MUST NOT"> OPTIONAL"> RECOMMENDED"> REQUIRED"> SHALL"> SHALL NOT"> SHOULD"> SHOULD NOT">]> 11.6.
element This element is like the
element defined in Section 4.4.4 of [HTML5] (note this is a block-level element!). It should contain one or more child elements. 11.7. element Marking up a string as indicates that it represents the top line of a box drawing, replacing the "+" and "-" characters accordingly. 11.8. element Contains mapping information for a single Unicode code points. Attributes are "c" (the actual character), "n" (the code point), and "d" (the name/description). For instance: Reschke Expires October 13, 2024 [Page 33] Documentation RFC7749 through XSLT April 2024 (The format is deliberately terse so that the size of a mapping file containing the whole Unicode character database is minimized). 11.9. element This element can be used to include a contributor's contact information in place where a paragraph () would be allowed otherwise. See Section 12.8 for a standard alternative. 11.10. element This element is like the element defined in Section 4.5.8 of [HTML5]. 11.11. element This elements allows declaring a feedback link for document reviewers. The template string takes the form of a URI template, such as: where "docname" is substituted by the document name, "section" is substituted by section title (number and name), and "ref" is substituted by a URI pointing to the section being referenced. 11.12. element This element is like the "h [9]" element in [XHTML2]. 11.13. element Used to highlight text passages, currently only allowed in . Note: this is stripped when generating input for xml2rfc, so please use with care. 11.14. element This element can be used to insert the length of another formatted section (in decimal). Reschke Expires October 13, 2024 [Page 34] Documentation RFC7749 through XSLT April 2024 Example: computing the Content-Length header value ... Content-Length: 123456789 The lenght computation counts line ends as two characters (CRLF). Note that indentation characters in artwork _will_ be counted. The "indented" attribute allows to specify the amount of indentation to be substracted from the computed length. 11.15. element This element can be added as a top-level child element below to indicate additional link information. It's currently used only when generating HTML output, in which case an HTML [10] element with identical attributes gets generated. Example: generating HTML link element If the attribute "basename" is present, it is used to compute the target href based on the output format being generated (this is handy for "next"/"prev" links in a series of documents. In this case, the href attribute is not required. For instance: