RFC 7998

"xml2rfc" Version 3 Preparation Tool Description

📅 published December 2016, from ietf

"xml2rfc" Version 3 Preparation Tool Description 🎀

Okay bestie, this is RFC 7998, and it's giving IAB realness 💅 It was written by P. Hoffman (ICANN) and J. Hildebrand (Mozilla) in December 2016. It's an Informational doc, not a standard, and its ISSN is 2070-1721. The header has no Obsoletes or Updates lines, so it isn't replacing or changing any other RFC 🦋

Abstract ✨

Okay so this doc describes some parts of the "prep tool" that's supposed to get built when the new xml2rfc version 3 spec rolls out 🧚

Status of This Memo 📚

Soooo this one is not an Internet Standards Track spec. It's just published for info purposes 💖

This document is a product of the Internet Architecture Board (IAB). It's basically the IAB saying "this is valuable, let's keep it on record forever," and it reflects the IAB's consensus 🌸 Anything the IAB approves for publication is not a candidate for any level of Internet Standard, see Section 2 of RFC 7841 💀

Want the latest on this doc's status, any errata, or how to send feedback? Check http://www.rfc-editor.org/info/rfc7998 ✨

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

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents, which you can find at http://trustee.ietf.org/license-info, as they were on the publication date. Read those carefully, bestie, because they explain your rights and restrictions for this doc 🔥

Table of Contents 🍓

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
2.  xml2rfc v3 Prep Tool Usage Scenarios  . . . . . . . . . . . .   4
3.  Internet-Draft Submission . . . . . . . . . . . . . . . . . .   4
4.  Canonical RFC Preparation . . . . . . . . . . . . . . . . . .   5
5.  What the v3 Prep Tool Does  . . . . . . . . . . . . . . . . .   5
  5.1.  XML Sanitization  . . . . . . . . . . . . . . . . . . . .   6
    5.1.1.  XInclude Processing . . . . . . . . . . . . . . . . .   6
    5.1.2.  DTD Removal . . . . . . . . . . . . . . . . . . . . .   6
    5.1.3.  Processing Instruction Removal  . . . . . . . . . . .   6
    5.1.4.  Validity Check  . . . . . . . . . . . . . . . . . . .   6
    5.1.5.  Check "anchor"  . . . . . . . . . . . . . . . . . . .   6
  5.2.  Defaults  . . . . . . . . . . . . . . . . . . . . . . . .   6
    5.2.1.  "version" Insertion . . . . . . . . . . . . . . . . .   6
    5.2.2.  "seriesInfo" Insertion  . . . . . . . . . . . . . . .   7
    5.2.3.  <date> Insertion  . . . . . . . . . . . . . . . . . .   7
    5.2.4.  "prepTime" Insertion  . . . . . . . . . . . . . . . .   7
    5.2.5.  <ol> Group "start" Insertion  . . . . . . . . . . . .   7
    5.2.6.  Attribute Default Value Insertion . . . . . . . . . .   7
    5.2.7.  Section "toc" attribute . . . . . . . . . . . . . . .   7
    5.2.8.  "removeInRFC" Warning Paragraph . . . . . . . . . . .   8
  5.3.  Normalization . . . . . . . . . . . . . . . . . . . . . .   8
    5.3.1.  "month" Attribute . . . . . . . . . . . . . . . . . .   8
    5.3.2.  ASCII Attribute Processing  . . . . . . . . . . . . .   8
    5.3.3.  "title" Conversion  . . . . . . . . . . . . . . . . .   9
  5.4.  Generation  . . . . . . . . . . . . . . . . . . . . . . .   9
    5.4.1.  "expiresDate" Insertion . . . . . . . . . . . . . . .   9
    5.4.2.  <boilerplate> Insertion . . . . . . . . . . . . . . .   9
      5.4.2.1.  Compare <rfc> "submissionType" and <seriesInfo>
                "stream"  . . . . . . . . . . . . . . . . . . . .   9
      5.4.2.2.  "Status of this Memo" Insertion . . . . . . . . .   9
      5.4.2.3.  "Copyright Notice" Insertion  . . . . . . . . . .  10
    5.4.3.  <reference> "target" Insertion  . . . . . . . . . . .  10
    5.4.4.  <name> Slugification  . . . . . . . . . . . . . . . .  10
    5.4.5.  <reference> Sorting . . . . . . . . . . . . . . . . .  10
    5.4.6.  "pn" Numbering  . . . . . . . . . . . . . . . . . . .  10
    5.4.7.  <iref> Numbering  . . . . . . . . . . . . . . . . . .  11
    5.4.8.  <xref> Processing . . . . . . . . . . . . . . . . . .  11
      5.4.8.1.  "derivedContent" Insertion (with Content) . . . .  11
      5.4.8.2.  "derivedContent" Insertion (without Content)  . .  11
    5.4.9.  <relref> Processing . . . . . . . . . . . . . . . . .  12
  5.5.  Inclusion . . . . . . . . . . . . . . . . . . . . . . . .  12
    5.5.1.  <artwork> Processing  . . . . . . . . . . . . . . . .  12
    5.5.2.  <sourcecode> Processing . . . . . . . . . . . . . . .  14

  5.6.  RFC Production Mode Cleanup . . . . . . . . . . . . . . .  14
    5.6.1.  <note> Removal  . . . . . . . . . . . . . . . . . . .  14
    5.6.2.  <cref> Removal  . . . . . . . . . . . . . . . . . . .  15
    5.6.3.  <link> Processing . . . . . . . . . . . . . . . . . .  15
    5.6.4.  XML Comment Removal . . . . . . . . . . . . . . . . .  15
    5.6.5.  "xml:base" and "originalSrc" Removal  . . . . . . . .  15
    5.6.6.  Compliance Check  . . . . . . . . . . . . . . . . . .  15
  5.7.  Finalization  . . . . . . . . . . . . . . . . . . . . . .  15
    5.7.1.  "scripts" Insertion . . . . . . . . . . . . . . . . .  16
    5.7.2.  Pretty-Format . . . . . . . . . . . . . . . . . . . .  16
6.  Additional Uses for the Prep Tool . . . . . . . . . . . . . .  16
7.  Security Considerations . . . . . . . . . . . . . . . . . . .  16
8.  Informative References  . . . . . . . . . . . . . . . . . . .  17
IAB Members at the Time of Approval . . . . . . . . . . . . . . .  18
Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  18
Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  18

1. Introduction 🦋

Okay so, as first described in [RFC6949], the canonical format of the RFC Series (the data that's the authorized, recognized, accepted, and archived version of the doc) has been plain text up until now. It's changing to XML, using the xml2rfc v3 vocabulary [RFC7991] 💜

But most people are going to read RFCs in other formats, like HTML, PDF, ASCII text, or formats that don't even exist yet 📱 To keep the output as uniform as possible across formats (and with the canonical XML itself), the goal is that translating the XML into those other formats is a straightforward syntactic translation. To make that happen, a lot of data needs to be in the XML that isn't there today. That data gets added by a program called the "prep tool", which will often run as part of the xml2rfc process ✨

This document specifies the steps the prep tool has to take. Whenever the xml2rfc v3 vocabulary [RFC7991] changes, this doc will probably get updated at the same time 🌸

Heads up, though: the details here (especially the vocabularies) are expected to change based on what people learn while building the new publication toolsets. Revised docs will be published to capture those changes as the toolsets get finished. Other implementers must not expect those changes to stay backwards-compatible with what's described here 🙈

2. xml2rfc v3 Prep Tool Usage Scenarios 🎀

The prep tool has several settings:

  • Internet-Draft preparation
  • Canonical RFC preparation

Only a few things differ between the two settings, like the boilerplate output and the date output on the front page 💅

Note that this doc only describes what the IETF-sponsored prep tool does. Others might build their own work-alike prep tools for their own formatting needs 🧚 But an output format developer doesn't need to change the prep tool to make their own formatter. They just need to be able to consume prepped text. The IETF-sponsored prep tool runs in two modes: "I-D" mode, when it's run during Internet-Draft submission and processing, and "RFC production mode", when the RFC Production Center runs it while producing an RFC 👑

This tool is described as if it's a separate tool so we can reason about its architecture. In real life, it might be part of a bigger suite of functionality 🫶

5. What the v3 Prep Tool Does ✨

okay so this part is where the prep tool actually gets to work 🛠️ the steps are listed in the order it runs them, so the sequence matters. one rule runs through everything: if the tool would "add" an attribute or element and it's already there, the tool checks that the value is valid. if it's wrong, the tool warns you with the old and new values, then swaps in the new one 🔄

the IETF has been using a tool called "idnits" [IDNITS] to check text for the Internet-Drafts posting process. idnits flags anything it considers an error and explains every warning and error in plain human-readable text. the prep tool should probably catch as many of those issues as it can while it's processing the XML input 🧐 for now, tooling might just run idnits on the text output of the prepared XML instead. the list below covers some of those checks, but the version of the prep tool that actually ships might have extra steps that bring in more of idnits' checks 💅

5.1. XML Sanitization 🧼

these steps make sure the input is well formatted and all of the XML processing has been done.

5.1.1. XInclude Processing 🔗

process every <x:include> element. heads up that an <x:include> can pull in more <x:include> elements of its own, and their relative references get resolved against the base URI, which might have been changed by an xml:base attribute inserted earlier. the tool may be configurable with a limit on how deep the recursion goes 🌀

5.1.2. DTD Removal 🗑️

fully process any Document Type Definitions (DTDs) in the input, then remove the DTD. at the very least this means handling the entity references and the includes for external files 📂

5.1.3. Processing Instruction Removal 🧹

remove processing instructions. bye bye 👋

5.1.4. Validity Check ✅

check the input against the RELAX NG (RNG) schema in [RFC7991]. if the input isn't valid, the tool gives an error 🚨

5.1.5. Check "anchor" 🔍

check every element for "anchor" attributes. if any "anchor" attribute starts with "s-", "f-", "t-", or "i-", that's an error 🙅‍♀️

5.2. Defaults 🎀

these steps fill in every default value so the XML is complete, just in case the defaults change later on. steps in this section never overwrite values that were already in the input file 💖

5.2.1. "version" Insertion 🏷️

if the <rfc> element has a "version" attribute whose value isn't "3", that's an error. if <rfc> has no "version" attribute at all, the tool adds one with the value "3" ✨

5.2.2. "seriesInfo" Insertion 📚

if the <front> element inside <rfc> doesn't already have a <seriesInfo> element, the tool adds one. its name attribute depends on the mode the prep tool is running in: "Internet-Draft" for Draft mode, and "RFC" for RFC production mode. the value is the input filename minus any extension for Internet-Drafts, and a number the RFC Editor specifies for RFCs 🔢

5.2.3. <date> Insertion 📅

if the <front> element inside <rfc> has no <date> element, the tool adds one and fills in the "day", "month", and "year" attributes from today's date 🗓️ if the <date> already has all three of "day", "month", and "year" but the date is more than three days in the past or is in the future, that's a warning. if it has only some of those three attributes, that's an error 😬

5.2.4. "prepTime" Insertion ⏰

if the input has a "prepTime" attribute on <rfc>, the tool exits with an error. otherwise it fills in the "prepTime" attribute of <rfc> with the current datetime 🕰️

5.2.5. <ol> Group "start" Insertion 🔢

add a "start" attribute to every <ol> element that contains a group but doesn't have a start yet 🌸

5.2.6. Attribute Default Value Insertion 🧩

fill in default values for attributes on elements, EXCEPT "keepWithNext" and "keepWithPrevious" on <t>, and "toc" on <section>. some defaults live in the RELAX NG schema, and others are described in the prose about each element in [RFC7991] 📖

5.2.7. Section "toc" attribute 📑

for each <section>, the "toc" attribute gets set to either "include" or "exclude". the rules run in this order:

  • for sections with an ancestor of <boilerplate>, use "exclude"
  • else, for sections that have a descendant with toc="include", use "include". if the ancestor section has toc="exclude" in the input, that's an error
  • else, for sections that are children of a section with toc="exclude", use "exclude"
  • else, for sections that are deeper than rfc/@tocDepth, use "exclude"
  • else use "include"

5.2.8. "removeInRFC" Warning Paragraph 📣

in I-D mode, if a <note> or <section> has a "removeInRFC" attribute set to "true", the tool adds a paragraph to the top of that element. the text is "This note is to be removed before publishing as an RFC." or "This section...", depending on the element. the tool skips this if a paragraph with that exact text is already there 🙃

5.3. Normalization 🪄

these steps make sure that ideas which can be written in more than one way only show up in one way in the prepared document. tidy tidy 🧽

5.3.1. "month" Attribute 🌙

normalize the values of "month" attributes in every <date> element inside <front> inside <rfc> so they're numeric 🔢

5.3.2. ASCII Attribute Processing 🔤

in every <email>, <organization>, <street>, <city>, <region>, <country>, and <code> element, if there's an "ascii" attribute and its value is the same as the element's content, the tool removes the "ascii" attribute and issues a warning about it 🧹

in every <author> element, if there's an "asciiFullname", "asciiInitials", or "asciiSurname" attribute, the tool compares the content with the matching "fullname", "initials", or "surname" element. if they match, it removes that "ascii*" attribute and warns about the removal ✨

5.3.3. "title" Conversion 🏷️

for every <section>, <note>, <figure>, <references>, and <texttable> element that still has the (deprecated) "title" attribute, the tool removes the "title" attribute and inserts a <name> element with the title from that attribute 💜

5.4. Generation 🌈

these steps create new content, overwriting similar content that's already in the input. some of them are important enough that they generate a warning whenever the content being overwritten doesn't match the new content 🚨

5.4.1. "expiresDate" Insertion ⏳

if the tool is in I-D mode, it fills in the "expiresDate" attribute of <rfc> based on the <date> element in the document's <front> 🗓️

5.4.2. <boilerplate> Insertion 🧾

create a <boilerplate> element if one doesn't exist. if the <boilerplate> element already has children, the tool produces this warning and removes the existing children:

"Existing boilerplate being removed. Other tools, specifically the draft submission tool, will treat this condition as an error"

the draft submission tool treats that same situation as an error, so this one's a big deal 😭

5.4.2.1. Compare <rfc> "submissionType" and <seriesInfo> "stream" 🔍

verify that the "submissionType" of <rfc> and the "stream" of <seriesInfo> are the same, if both are present. if either one is missing, add it. both have a default value of "IETF" 🫶

5.4.2.2. "Status of this Memo" Insertion 📜

add the "Status of this Memo" section to the <boilerplate> element using the current values. the application looks at the "submissionType" and "consensus" attributes of <rfc>, the <workgroup> element, and the "status" and "stream" attributes of <seriesInfo> to figure out which boilerplate from [RFC7841] to include. Appendix A of [RFC7991] has the details 🧠

add the "Copyright Notice" section to the <boilerplate> element. the application uses the "ipr" and "submissionType" attributes of <rfc> and the <date> element to decide which portions and which version of the Trust Legal Provisions (TLP) to use. A.1 of [RFC7991] explains how 📝

5.4.3. <reference> "target" Insertion 🎯

for any <reference> element that doesn't already have a "target" attribute, fill it in if the element has one or more <seriesinfo> child elements and the "name" attribute of that <seriesinfo> is "RFC", "Internet-Draft", or "DOI", or some other value where it's clear what the target should be. the actual URLs for RFCs, Internet-Drafts, and Digital Object Identifiers (DOIs) will be specified later by the RFC Editor and the IESG. those URLs might also change before and after the v3 format gets adopted 🔗

5.4.4. <name> Slugification 🐌

add a "slugifiedName" attribute to each <name> element that doesn't have one. if the attribute already has a value starting with "n-", replace it 🍓

5.4.5. <reference> Sorting 🔤

if the "sortRefs" attribute of <rfc> is true, sort the <reference> and <referencegroup> elements lexically by the value of their "anchor" attribute, after applying any "to" attribute from a <displayreference> element. the RFC Editor still needs to decide what the lexical sorting rules are. the authors of this document admit that getting consensus on this will be a tough job 😅

5.4.6. "pn" Numbering 🔢

add "pn" attributes to all parts. here are the parts and their formats:

  • <section> in <middle>: pn='s-1.4.2'
  • <references>: pn='s-12' or pn='s-12.1'
  • <abstract>: pn='s-abstract'
  • <note>: pn='s-note-2'
  • <section> in <boilerplate>: pn='s-boilerplate-1'
  • <table>: pn='t-3'
  • <figure>: pn='f-4'
  • <artwork>, <aside>, <blockquote>, <dt>, <li>, <sourcecode>, <t>: pn='p-[section]-[counter]'

5.4.7. <iref> Numbering 🦋

in every <iref> element, create a "pn" attribute that's unique across the whole document. its value starts with 'i-' and uses the item attribute, the subitem attribute (if there is one), and a counter so it stays unique. for example, the first <iref item='foo' subitem='bar'> gets the "irefid" attribute set to 'i-foo-bar-1' 🧚

5.4.8. <xref> Processing 🔗

5.4.8.1. "derivedContent" Insertion (with Content) 🫧

for each <xref> element that has content, fill in "derivedContent" with that content, after trimming the whitespace from the ends of the text. if "derivedContent" already exists with a different value than what's being filled in, issue a warning 👀

5.4.8.2. "derivedContent" Insertion (without Content) ✨

okay so for every <xref> element that has NO content, we fill in the "derivedContent" attribute based on its "format" attribute 💅🎀

  • for a value of counter, the "derivedContent" gets set to the section, figure, table, or ordered list number of the element that has an anchor equal to the <xref> target 🔢
  • for format='default' where the "target" attribute points to a <reference> or <referencegroup> element, the "derivedContent" is the value of the "target" attribute (or the "to" attribute of a <displayreference> element for the targeted <reference>) 🦋
  • for format='default' where the "target" attribute points to a <section>, <figure>, or <table>, the "derivedContent" is the name of the thing it points to, like "Section 2.3", "Figure 12", or "Table 4" 🌸
  • for format='title', if the target is a <reference> element, the "derivedContent" attribute is the name of the reference, pulled out of the <title> child of the <front> child of the reference 📚
  • for format='title', if the target element has a <name> child element, the "derivedContent" attribute is the text content of that <name> element, joined with the text content of each descendant node of <name> (so basically strip out all the XML markup and keep only the text) ✨
  • for format='title', if the target element does NOT have a <name> child element, the "derivedContent" attribute is just the value of the "target" attribute with no other adornment 🧚
  • heads up: if the "derivedContent" attribute already exists and has a different value from what we were about to fill in, issue a warning 🚨⚠️

5.4.9. <relref> Processing 🫶

if any <relref> element's "target" attribute points at anything other than a <reference> element, give an error 💀

then, for each <relref> element, fill in the "derivedLink" attribute 🔗

5.5. Inclusion 🌈

these steps pull external files into the output document, so it's giving "bring everything together" energy 🧺

5.5.1. <artwork> Processing 🎨

  1. if an <artwork> element has a "src" attribute where no scheme is specified, copy the "src" value over to the "originalSrc" attribute, then swap the "src" value for a URI that uses the "file:" scheme with a path relative to the file being processed. see Section 7 for warnings about this step. this will probably be one of the most common ways people write these 🙈
  2. if an <artwork> element has a "src" attribute with a "file:" scheme, and processing that URL would make the processor grab a file that isn't in the same directory (or a subdirectory) as the file being processed, give an error. if the "src" has any shellmeta strings (like `, $USER, and so on) that would get processed, give an error too. then replace the "src" attribute with a URI that uses the "file:" scheme with a path relative to the file being processed. this rule is there to stop things like <artwork src='file:///etc/passwd'> and similar security issues 😭🔒. see Section 7 for warnings about this step.
  3. if an <artwork> element has a "src" attribute AND the element has content, give an error 🙅‍♀️
  4. if an <artwork> element has type='svg' and there's a "src" attribute, the data needs to be moved into the content of the <artwork> element.
    • if the "src" URI scheme is "data:", fill the content of the <artwork> element with that data and remove the "src" attribute 🧁
    • if the "src" URI scheme is "file:", "http:", or "https:", fill the content of the <artwork> element with the resolved XML from the URI in the "src" attribute. if there's no "originalSrc" attribute, add one with the value of the URI, then remove the "src" attribute 🌷
    • if the <artwork> element has an "alt" attribute, and the SVG doesn't have a <desc> element, add a <desc> element with the contents of the "alt" attribute 📝
  5. if an <artwork> element has type='binary-art', the data needs to live in a "src" attribute with a URI scheme of "data:". if the "src" URI scheme is "file:", "http:", or "https:", resolve the URL. then replace the "src" attribute with a "data:" URI and add an "originalSrc" attribute with the value of the URI. for the "http:" and "https:" URI schemes, the mediatype of the "data:" URI will be the Content-Type of the HTTP response. for the "file:" URI scheme, the mediatype of the "data:" URI has to be guessed with heuristics (this is possibly a bad idea 💀). this also fails for content that includes binary images but uses a type other than "binary-art". Note: since this feature can't be used for RFCs at the moment, this entire feature might be
  6. if an <artwork> element does NOT have type='svg' or type='binary-art' and there's a "src" attribute, the data needs to be moved into the content of the <artwork> element. note that this step assumes all the preferred types other than "binary-art" are text, which is possibly wrong 🤷‍♀️
    • if the "src" URI scheme is "data:", fill the content of the <artwork> element with the correctly escaped form of that data and remove the "src" attribute 🍓
    • if the "src" URI scheme is "file:", "http:", or "https:", fill the content of the <artwork> element with the correctly escaped form of the resolved text from the URI in the "src" attribute. if there's no "originalSrc" attribute, add one with the value of the URI, then remove the "src" attribute 💜

5.5.2. <sourcecode> Processing 💻

  1. if a <sourcecode> element has a "src" attribute where no scheme is specified, copy the "src" value to the "originalSrc" attribute and replace the "src" value with a URI that uses the "file:" scheme with a path relative to the file being processed. see Section 7 for warnings about this step. this will likely be one of the most common ways people write these too ✨
  2. if a <sourcecode> element has a "src" attribute with a "file:" scheme, and processing that URL would make the processor grab a file that isn't in the same directory (or a subdirectory) as the file being processed, give an error. if the "src" has any shellmeta strings (like `, $USER, and so on) that would get processed, give an error. then replace the "src" attribute with a URI that uses the "file:" scheme with a path relative to the file being processed. this rule stops things like <sourcecode src='file:///etc/passwd'> and similar security issues 🛡️. see Section 7 for warnings about this step.
  3. if a <sourcecode> element has a "src" attribute AND the element has content, give an error 🙃
  4. if a <sourcecode> element has a "src" attribute, the data needs to be moved into the content of the <sourcecode> element.
    • if the "src" URI scheme is "data:", fill the content of the <sourcecode> element with that data and remove the "src" attribute 🫧
    • if the "src" URI scheme is "file:", "http:", or "https:", fill the content of the <sourcecode> element with the resolved XML from the URI in the "src" attribute. if there's no "originalSrc" attribute, add one with the value of the URI, then remove the "src" attribute 🌸

5.6. RFC Production Mode Cleanup 🧹

these steps give the output document some extra glow-up cleanup when we're in RFC production mode ✨💅

5.6.1. <note> Removal 🗑️

in RFC production mode, if there's a <note> or <section> element with a "removeInRFC" attribute that has the value "true", remove that element. bye bye 👋

5.6.2. <cref> Removal 🦋

if we're in RFC production mode, remove ALL <cref> elements. no exceptions, bestie 🙅‍♀️

  1. if we're in RFC production mode, remove all <link> elements whose "rel" attribute has the value "alternate" 🙈
  2. if we're in RFC production mode, check for a <link> element with the current ISSN for the RFC series (2070-1721). if there isn't one, add <link rel="item" href="urn:issn:2070-1721"> 📖
  3. if we're in RFC production mode, check for a <link> element with a DOI for this RFC. if there isn't one, add one of the form <link rel="describedBy" href="https://dx.doi.org/10.17487/rfcdd">, where "dd" is the number of the RFC, like "https://dx.doi.org/10.17487/rfc2109". The URI is described in [RFC7669]. if there was already a <link> element with a DOI for this RFC, check that the "href" value has the right format. the content of the href attribute is expected to change in the future 🔮
  4. if we're in RFC production mode, check for a <link> element with the file name of the Internet-Draft that became this RFC, in the form <link rel="convertedFrom" href="https://datatracker.ietf.org/doc/draft-tttttttttt/">. if one does not exist, give an error 🚨

5.6.4. XML Comment Removal 🫧

if we're in RFC production mode, remove XML comments. bye, little notes 💜

5.6.5. "xml:base" and "originalSrc" Removal 🧼

if we're in RFC production mode, remove all "xml:base" or "originalSrc" attributes from all elements. clean slate ✨

5.6.6. Compliance Check 📋

if we're in RFC production mode, make sure the result is in full compliance with the v3 schema, without any deprecated elements or attributes. if any issues are found, give an error. no slacking 😤

5.7. Finalization 👑

these steps are the finishing touches on the output document, the last coat of nail polish 💅🌈

5.7.1. "scripts" Insertion 🌍

figure out all the characters used in the document and fill in the "scripts" attribute for <rfc>. every letter counts 🔤

5.7.2. Pretty-Format 🎀

pretty-format the XML output. (Note: there are many tools that do an adequate job.) 🫶

6. Additional Uses for the Prep Tool 🧚

there's going to be a need for Internet-Draft authors who include files from their local disk (like for <artwork src="mydrawing.svg"/>) to have those files' contents inlined into their drafts before submitting them to the Internet-Draft processor. (There is a possibility that the Internet-Draft processor will allow XML files and accompanying files to be submitted at the same time, but this seems troublesome from a security, portability, and complexity standpoint.) for these users, a local copy of the prep tool with an option to just inline all local files would be terribly useful 🙌. that option would be a proper subset of the steps given in Section 5.

a feature that might be useful in a local prep tool would be the inverse of the "just inline" option, which would be "extract all" 🍓. this would let a user who has a v3 RFC or Internet-Draft dump all of the <artwork> and <sourcecode> elements into local files, instead of having to hunt down each one in the XML. this option might even do as much validation as possible on the extracted <sourcecode> elements 🔍. this feature might also remove some of the features added by the prep tool (like part numbers and "slugifiedName" attributes starting with "n-") to make the resulting file easier to edit ✏️💖

7. Security Considerations 🔒

okay so this part is seriously important bestie 🚨 The steps in this doc try to stop the <artwork> and <sourcecode> entities from leaking the contents of files outside the directory where the document being processed lives 🙅‍♀️📁 For example, values starting with /, ./, or ../ should generate errors. no sneaking out of the folder 💅

The security considerations in [RFC3470] apply here too 🫶 Specifically, processing XML-external references can expose a prep-tool implementation to various threats, because it ends up accessing external resources automatically 😭 It is important to disallow arbitrary access to those external references inside XML data from untrusted sources. Not giving strangers' XML free rein to fetch whatever it wants is giving responsible 🛡️✨

8. Informative References 📚

these are the sources I pointed to, and here they are in full, so nobody has to go hunting 🧚

[IDNITS]   IETF Tools, "Idnits Tool",
           <https://tools.ietf.org/tools/idnits/>.

[PUB-PROCESS]
           RFC Editor, "Publication Process",
           <https://www.rfc-editor.org/pubprocess/>.

[RFC3470]  Hollenbeck, S., Rose, M., and L. Masinter, "Guidelines for
           the Use of Extensible Markup Language (XML) within IETF
           Protocols", BCP 70, RFC 3470, DOI 10.17487/RFC3470,
           January 2003, <http://www.rfc-editor.org/info/rfc3470>.

[RFC6949]  Flanagan, H. and N. Brownlee, "RFC Series Format
           Requirements and Future Development", RFC 6949,
           DOI 10.17487/RFC6949, May 2013,
           <http://www.rfc-editor.org/info/rfc6949>.

[RFC7669]  Levine, J., "Assigning Digital Object Identifiers to
           RFCs", RFC 7669, DOI 10.17487/RFC7669, October 2015,
           <http://www.rfc-editor.org/info/rfc7669>.

[RFC7841]  Halpern, J., Ed., Daigle, L., Ed., and O. Kolkman, Ed.,
           "RFC Streams, Headers, and Boilerplates", RFC 7841,
           DOI 10.17487/RFC7841, May 2016,
           <http://www.rfc-editor.org/info/rfc7841>.

[RFC7991]  Hoffman, P., "The "xml2rfc" Version 3 Vocabulary",
           RFC 7991, DOI 10.17487/RFC7991, December 2016,
           <http://www.rfc-editor.org/info/rfc7991>.

IAB Members at the Time of Approval 🎀

these are the IAB members when this memo got approved, listed alphabetically because we love a tidy list 💖

Jari Arkko
Ralph Droms
Ted Hardie
Joe Hildebrand
Russ Housley
Lee Howard
Erik Nordmark
Robert Sparks
Andrew Sullivan
Dave Thaler
Martin Thomson
Brian Trammell
Suzanne Woolf

Acknowledgements 🫶

so many people brought valuable ideas to this doc, and they deserve all the love 🌸 Special thanks to Robert Sparks for his in-depth review and contributions early on, and to Julian Reschke for helping get the document structured more clearly. the main character glow-up is real 🌈

Authors' Addresses 💌

the people who wrote this 🦋

Paul Hoffman
ICANN

Email: paul.hoffman@icann.org


Joe Hildebrand
Mozilla

Email: joe-ietf@cursive.net
📦 where this page comes from