draft-iab-rfcv3-preptool-latest.xml

<?xml version="1.0" encoding="UTF-8"?>
  <?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
  <!-- generated by https://github.com/cabo/kramdown-rfc2629 version 1.0.30 -->

<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
]>

<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<?rfc sortrefs="yes"?>
<?rfc symrefs="yes"?>

<rfc ipr="trust200902" docName="draft-iab-rfcv3-preptool-03" category="info">

  <front>
    <title>RFC v3 Prep Tool Description</title>

    <author initials="P." surname="Hoffman" fullname="Paul Hoffman">
      <organization>ICANN</organization>
      <address>
        <email>paul.hoffman@icann.org</email>
      </address>
    </author>
    <author initials="J." surname="Hildebrand" fullname="Joe Hildebrand">
      <organization>Cisco</organization>
      <address>
        <email>jhildebr@cisco.com</email>
      </address>
    </author>

    <date year="2016" month="July" day="18"/>

    
    
    <keyword>Internet-Draft</keyword>

    <abstract>


<t>This document describes some aspects of the “prep tool” that is expected
to be created when the new RFC v3 specification is deployed.</t>

<!--

Notes between the authors go here. Nothing at the moment.

-->



    </abstract>


  </front>

  <middle>


<section anchor="introduction" title="Introduction">

<t>For the future of the RFC format, the RFC Editor has decided that XML (using the
XML2RFCv3 vocabulary <xref target="I-D.iab-xml2rfc"/>) is the canonical format, in the sense
that it is the data that is
the authorized, recognized, accepted, and  archived version of the document. See
<xref target="RFC6949"/> for more detail on this.</t>

<t>Most people will read other formats, such as HTML, PDF, ASCII text, or other
formats of the future, however.  In order to ensure each of these formats is as
similar as possible to one another as well as the canonical XML, there is a
desire that the translation from XML into the other formats will be
straightforward syntactic translation. To make that happen, a good amount of
data will need to be in the XML format that is not there today. That data will
be added by a program called the “prep tool”, which will often run as a part of
the xml2rfc process.</t>

<t>This draft specifies the steps that the prep tool will have to take.
As changes to <xref target="I-D.iab-xml2rfc"/> are made, this document will be updated.</t>

<t>The details (particularly any vocabularies) described in this document are
expected to change based on experience gained in implementing the RFC Production
Center’s (RPC) toolset. Revised documents will be published capturing those changes as
the toolset is completed. Other implementers must not expect those changes to
remain backwards-compatible with the details described in this document.</t>

</section>
<section anchor="v3-prep-tool-usage-scenarios" title="v3 Prep Tool Usage Scenarios">

<t>The prep tool will have several settings:</t>

<t><list style="symbols">
  <t>Internet-Draft preparation</t>
  <t>Canonical RFC preparation</t>
</list></t>

<t>There are only a few differences between the two settings. For example, the
boilerplate output will be different, as will the date output on the front page.</t>

<t>Note that this only describes what the IETF-sponsored prep tool does. Others
might create their own work-alike prep tools for their own formatting needs.
However, an output format developer does not need to change the prep tool in
order to create their own formatter: they only need to be able to consume
prepared text. The IETF-sponsored prep tool runs in two different modes: “I-D”
mode when the tool is run during Internet-Draft submission and processing, and
“RFC production mode” when the tool is run by the RFC Production Center
while producing an RFC.</t>

<t>This tool is described as if it is a separate tool so that we can reason about
its architectural properties. In actual implementation, it might be a part of a
larger suite of functionality.</t>

</section>
<section anchor="internet-draft-submission" title="Internet-Draft Submission">

<t>When the IETF draft submission tool accepts v3 XML as an input format, the
submission tool runs the submitted file through the prep tool. This is called
“I-D mode” in this document. If the tool finds no errors, it keeps two XML
files: the submitted file and the prepped file.</t>

<t>The prepped file provides a record of what a submitter was attesting to at the
time of submission. It represents a self-contained record of what any external
references resolved to at the time of submission.</t>

<t>The prepped file is used by the IETF
formatters to create outputs such as HTML, PDF, and text (or the tools act in a
way indistinguishable from this). The message sent out by the draft submission
tool includes a link to the original XML as well as the other outputs, including
the prepped XML.</t>

<t>The prepped XML can be used by tools not yet developed to output new formats
that have as similar output as possible to the current IETF formatters. For
example, if the IETF creates a .mobi output renderer later, it can run that
renderer on all of the prepped XML that has been saved, ensuring that the
content of included external references and all of the part numbers and
boilerplate will be the same as what was produced by the previous IETF
formatters at the time the document was first uploaded.</t>

</section>
<section anchor="canonical-rfc-preparation" title="Canonical RFC Preparation">

<t>During AUTH48, the RPC will run the prep tool in canonical RFC production mode
and make the results available to the authors so they can see what the final
output might look like. When the document has passed AUTH48 review, the RPC
runs the prep tool in canonical RFC production mode one last time, locks down
the canonicalized XML, runs the formatters for the publication
formats, and publishes all of those.</t>

<t>This document assumes that the prep tool will be used in the following manner by
the RPC; they may use something different, or with different
configuration.</t>

<t>Similarly to I-D’s, the prepped XML can be used later to re-render the output
formats, or to generate new formats.</t>

</section>
<section anchor="steps" title="What the v3 Prep Tool Does">

<t>The steps listed here are in order of processing. In all cases where the prep
tool would “add” an attribute or element, if that attribute or element already
exists, the prep tool will check that the attribute or element has valid values. If
the value is incorrect, the prep tool will warn with the old and new values,
then replace the incorrect value with the new value.</t>

<t>Currently, the IETF uses a tool called “idnits” to check text input to the
Internet-Drafts publishing process. idnits indicates if it encountered any
errors, and also provide text with all of the warnings and errors in a
human-readable form. The prep tool should probably check for as many of these
errors and warnings as possible when it is processing the XML input. For the
moment, tooling might run idnts on the text output from the prepared XML. The
list below contains some of those errors and warnings, but the deployed version
of the prep tool may contain additional steps to include more or the checks from
idnits.</t>

<section anchor="sanitization" title="XML Sanitization">

<t>These steps will ensure that the input document is properly formatted, and that
all XML processing has been performed.</t>

<section anchor="xinclude-processing" title="XInclude Processing">

<t>Process all &lt;x:include&gt; elements. Note: &lt;x:include&gt;d XML may
include more &lt;x:include&gt;s (with relative references resolved against the base URI potentially modified by a previously inserted xml:base attribute). The
tool may be configurable with a limit on the depth of recursion.</t>

</section>
<section anchor="dtd-removal" title="DTD Removal">

<t>Fully process any Document Type Definitions (DTDs) in the input document, then remove the DTD.
At a minimum, this entails processing the entity references and includes for external
files.</t>

</section>
<section anchor="pi-removal" title="Processing Instruction Removal">

<t>Remove processing instructions.</t>

</section>
<section anchor="validity-check" title="Validity Check">

<t>Check the input against the RNG in <xref target="I-D.iab-xml2rfc"/>. If the input is not
valid, give an error.</t>

</section>
<section anchor="check-anchor" title="Check “anchor”">

<t>Check all elements for “anchor” attributes. If any “anchor” attribute
begins with “s-“, “f-“, “t-“, or “i-“, give an error.</t>

</section>
</section>
<section anchor="defaults" title="Defaults">

<t>These steps will ensure that all default values have been filled in to the XML,
in case the defaults change at a later date.  Steps in this section will not
overwrite existing values in the input file.</t>

<section anchor="version-insertion" title="“version” Insertion">

<t>If the &lt;rfc&gt; element has a “version” attribute with a value other than “3”, give an error.
If the &lt;rfc&gt; element has no “version” attribute, add one with the value “3”.</t>

</section>
<section anchor="seriesinfo-insertion" title="“seriesInfo” Insertion">

<t>If the &lt;front&gt; element of the &lt;rfc&gt; element does not already have
a &lt;seriesInfo&gt; element, add a &lt;seriesInfo&gt; element with the name
attribute based on the mode in which the preptool is running (“Internet-Draft”
for Draft mode and “RFC” for RFC production mode) and a value that is the input filename
minus any extension for Internet-Drafts, and is a number specified by the RFC
Editor for RFCs.</t>

</section>
<section anchor="date-insertion" title="&lt;date&gt; Insertion">

<t>If the &lt;front&gt; element in the &lt;rfc&gt; element does not contain a
&lt;date&gt; element, add it and fill in the “day”, “month”, and “year”
attibutes from the current date. If the &lt;front&gt; element in the &lt;rfc&gt;
element has a &lt;date&gt; element with “day”, “month”, and “year” attibutes,
but the date indicated is more than three days in the past or is in the future,
give a warning. If the &lt;front&gt; element in the &lt;rfc&gt; element has a
&lt;date&gt; element with some but not all of the “day”, “month”, and “year”
attibutes, give an error.</t>

</section>
<section anchor="preptime-insertion" title="“prepTime” Insertion">

<t>If the input document includes a “prepTime” attribute of &lt;rfc&gt;, exit with
an error.</t>

<t>Fill in the “prepTime” attribute of &lt;rfc&gt; with the current datetime.</t>

</section>
<section anchor="ol-group-start-insertion" title="&lt;ol&gt; Group “start” Insertion">

<t>Add a “start” attribute to every &lt;ol&gt; element containing a group that
does not already have a start.</t>

</section>
<section anchor="attribute-default-value-insertion" title="Attribute Default Value Insertion">

<t>Fill in any default values for attributes on elements, except “keepWithNext”
and “keepWithPrevious” of &lt;t&gt;, and “toc” of &lt;section&gt;.
Some default values can be found in the Relax NG schema, while others can be
found in the prose describing the elements in <xref target="I-D.iab-xml2rfc"/>).</t>

</section>
<section anchor="section-toc" title="Section “toc” attribute">

<t>For each &lt;section&gt;, modify the “toc” attribute to be either “include” or
“exclude”:</t>

<t><list style="symbols">
  <t>for sections that have an ancestor of &lt;boilerplate&gt;, use “exclude”</t>
  <t>else for sections that have a descendant that has toc=”include”, use
“include”.  If the section has toc=”exclude” in the input, this is
an error.</t>
  <t>else for sections that are children of a section with toc=”exclude”,
use “exclude”.</t>
  <t>else for sections that are deeper than rfc/@tocDepth, use “exclude”</t>
  <t>else use “include”</t>
</list></t>

</section>
<section anchor="remove-in-rfc-warning" title="“removeInRFC” Warning Paragraph">

<t>If in I-D mode, if there is a &lt;note&gt; or &lt;section&gt; element with a “removeInRFC”
attribute that has the value “true”, add a paragraph to the top of the
element with the text “This note is to be removed before publishing
as an RFC.” or “This section…”, unless a paragraph consisting of that exact text already exists.</t>

</section>
</section>
<section anchor="normalization" title="Normalization">

<t>These steps will ensure that ideas that can be expressed in
multiple different ways in the input document are only found in one way in the
prepared document.</t>

<section anchor="normalize-month-attribute" title="“month” Attribute">

<t>Normalize the values of “month” attributes in all &lt;date&gt; elements
in &lt;front&gt; elements in &lt;rfc&gt; elements to numeric values.</t>

</section>
<section anchor="ascii-atttribute-processing" title="ASCII Attribute Processing">

<t>In every &lt;email&gt;, &lt;organization&gt;, &lt;street&gt;, &lt;city&gt;,
&lt;region&gt;, &lt;country&gt;, and &lt;code&gt; element, if there is an
“ascii” attribute and the value of that attribute is the same as the content of
the element, remove the “ascii” element and issue a warning about the removal.</t>

<t>In every &lt;author&gt; element, if there is an “asciiFullname”,
“asciiInitials”, or “asciiSurname” attribute, check the content of that element
against its matching “fullname”, “initials”, or “surname” element
(respectively). If the two are the same, remove the “ascii*” elelement and issue
a warning about the removal.</t>

</section>
<section anchor="title-conversion" title="“title” Conversion">

<t>For every &lt;section&gt;, &lt;note&gt;, &lt;figure&gt;, &lt;references&gt;, and
&lt;texttable&gt; element that has a (deprecated) “title” attribute, remove the
“title” attribute and insert a &lt;name&gt; element with the title from the
attribute.</t>

</section>
</section>
<section anchor="generation" title="Generation">

<t>These steps will generate new content, overriding existing similar
content in the input document.  Some of these steps are important enough that
they specify a warning to be generated when the content being overwritten does
not match the new content.</t>

<section anchor="expiresdate-insertion" title="“expiresDate” Insertion">

<t>If in I-D mode, fill in “expiresDate” attribute of &lt;rfc&gt; based on the
&lt;date&gt; element of the document’s &lt;front&gt; element.</t>

</section>
<section anchor="boilerplate-insertion" title="&lt;boilerplate&gt; Insertion">

<t>Create a &lt;boilerplate&gt; element if it does not exist. If there are any
children of the &lt;boilerplate&gt; element, produce a warning that says
“Existing boilerplate being removed. Other tools, specifically the draft
submission tool, will treat this condition as an error” and remove the existing
children.</t>

<section anchor="compare-submission" title="Compare &lt;rfc&gt; “submissionType” and &lt;seriesInfo&gt; “stream”">

<t>Verify that &lt;rfc&gt; “submissionType” and &lt;seriesInfo&gt; “stream” are the same
if they are both present.
If either is missing, add it.
Note that both have a default value of “IETF”.</t>

</section>
<section anchor="status-of-this-memo-insertion" title="‘Status of this Memo’ Insertion">

<t>Add the “Status of this Memo” section to the &lt;boilerplate&gt; element with
current values. The application will use the “submissionType”, and “consensus”
attributes of the &lt;rfc&gt; element, the &lt;workgroup&gt; element, and the
“status” and “stream” attributes of the &lt;seriesInfo&gt; element, to determine
which <xref target="I-D.iab-rfc5741bis"/> boilerplate to include, as described in Appendix A
of <xref target="I-D.iab-xml2rfc"/>.</t>

</section>
<section anchor="copyright-insertion" title="Copyright Insertion">

<t>Add the “Copyright Notice” section to the &lt;boilerplate&gt; element. The
application will use the “ipr” and “submissionType” attributes of the
&lt;rfc&gt; element and the &lt;date&gt; element to determine which portions and
which version of the TLP to use, as described in A.1 of <xref target="I-D.iab-xml2rfc"/>.</t>

</section>
</section>
<section anchor="reference-target-insertion" title="&lt;reference&gt; “target” Insertion">

<t>For any &lt;reference&gt; element that does not already have a “target”
attribute, fill the target attribute in if the element has one or more
&lt;seriesinfo&gt; child element(s) and the “name” attribute of the
&lt;seriesinfo&gt; element is “RFC”, “Internet-Draft”, or “DOI” or other value
for which it is clear what the “target” should be. The particular URLs for RFCs,
Internet-Drafts, and DOIs for this step will be specified later by the RFC
Editor and the IESG. These URLs might also be different before and after the v3
format is adopted.</t>

</section>
<section anchor="name-slugification" title="&lt;name&gt; Slugification">

<t>Add a “slugifiedName” attribute to each &lt;name&gt; element that does not
contain one; replace the attribute if it contains a value that begins with “n-“.</t>

</section>
<section anchor="reference-sorting" title="&lt;reference&gt; Sorting">

<t>If the “sortRefs” attribute of the &lt;rfc&gt; element is true, sort the
&lt;reference&gt;s and &lt;referencegroup&gt;s lexically by the value of the
“anchor” attribute, as modified by the “to” attribute of any
&lt;displayreference&gt; element. The RFC Editor needs to determine what the
rules for lexical sorting are. The authors of this document acknowledge that
getting consensus on this will be a difficult task.</t>

</section>
<section anchor="part-numbering" title="“pn” Numbering">

<t>Add “pn” attributes for all parts.  Parts are:</t>

<t><list style="symbols">
  <t>&lt;section&gt; in &lt;middle&gt;: pn=’s-1.4.2’</t>
  <t>&lt;references&gt;: pn=’s-12’ or pn=’s-12.1’</t>
  <t>&lt;abstract&gt;: pn=’s-abstract’</t>
  <t>&lt;note&gt;: pn=’s-note-2’</t>
  <t>&lt;section&gt; in &lt;boilerplate&gt;: pn=’s-boilerplate-1’</t>
  <t>&lt;table&gt;: pn=’t-3’</t>
  <t>&lt;figure&gt;: pn=’f-4’</t>
  <t>&lt;artwork&gt;, &lt;aside&gt;, &lt;blockquote&gt;, &lt;dt&gt;,
&lt;li&gt;, &lt;sourcecode&gt;, &lt;t&gt;: pn=’p-[section]-[counter]’</t>
</list></t>

</section>
<section anchor="iref-numbering" title="&lt;iref&gt; Numbering">

<t>In every &lt;iref&gt; element, create a document-unique “pn” attribute.
The value of the “pn” attribute will start with ‘i-‘, and use the item
attribute, the subitem attribute (if it exists), and a counter to ensure
uniqueness. For example, the first instance of “&lt;iref item=’foo’
subitem=’bar’&gt;” will get the irefid ‘i-foo-bar-1’.</t>

</section>
<section anchor="xref-processing" title="&lt;xref&gt; processing">

<section anchor="xref-derivedcontent-insertion-with-content" title="“derivedContent” Insertion (With Content)">

<t>For each &lt;xref&gt; element that has content, fill the “derivedContent” with
the element content, having first trimmed the whitespace from ends of content
text. Issue a warning if the “derivedContent” attribute already exists and has a
different value from what was being filled in.</t>

</section>
<section anchor="xref-derivedcontent-insertion-without-content" title="“derivedContent” Insertion (Without Content)">

<t>For each &lt;xref&gt; element that does not have content, fill the
“derivedContent” based on the “format” attribute.</t>

<t><list style="symbols">
  <t>For format=’counter’, the “derivedContent” is the section, figure, table, or
ordered list number of the element with anchor equal to the xref target.</t>
  <t>For format=’default’ and the “target” attribute points to a
&lt;reference&gt; or &lt;referencegroup&gt; element, the “derivedContent” is
the value of the “target” attribute (or the “to” attribute of a
&lt;displayreference&gt; element for the targeted &lt;reference&gt;).</t>
  <t>For format=’default’ and the “target” attribute points to a &lt;section&gt;,
&lt;figure&gt;, or &lt;table&gt;, the “derivedContent” is the name of the
thing pointed to, such as “Section 2.3”, “Figure 12”, or “Table 4”.</t>
  <t>For format=’title’, if the target is a &lt;reference&gt; element, the
“derivedContent” attribute is the name of the reference, extracted from the
&lt;title&gt; child of the &lt;front&gt; child of the reference.</t>
  <t>For format=’title’, if the target element has a &lt;name&gt; child element,
the “derivedContent” attribute is the text content of that &lt;name&gt;
element concatenated with the text content of each descendant node of
&lt;name&gt; (that is, stripping out all of the XML markup, leaving only the
text).</t>
  <t>For format=’title’, if the target element does not contain a &lt;name&gt;
child element, the “derivedContent” attribute is the value of the “target”
attribute with no other adornment.  Issue a warning if the “derivedContent”
attribute already exists and has a different value from what was being
filled in.</t>
</list></t>

</section>
</section>
<section anchor="relref-processing" title="&lt;relref&gt; Processing">

<t>If any &lt;relref&gt; element’s “target” attribute refers to anything but a
&lt;reference&gt; element, give an error.</t>

<t>For each &lt;relref&gt; element, fill in the “derivedLink” attribute.</t>

</section>
</section>
<section anchor="inclusion" title="Inclusion">

<t>These steps will include external files into the output document.</t>

<section anchor="artwork-processing" title="&lt;artwork&gt; Processing">

<t><list style="numbers">
  <t>If an &lt;artwork&gt; element has a “src” attribute where no scheme is
specified, copy the “src” attribute value to the “originalSrc” attribute, and
replace the “src” value with a URI that uses the “file:” scheme in a path
relative to the file being processed.
See <xref target="securitycons"/> for warnings about this step. This will likely
be one of the most common authoring approaches.</t>
  <t>If an &lt;artwork&gt; element has a “src” attribute with a “file:” scheme,
and if processing the URL would cause the processor to retrieve a file that is
not in the same directory, or a subdirectory, as the file being processed, give
an error. If the “src” has any shellmeta strings (such as “`”, “$USER”, and so
on) that would be processed, give an error. Replace the “src” attribute with a
URI that uses the “file:” scheme in a path relative to the file being processed.
This rule attempts to prevent &lt;artwork src=’file:///etc/passwd’&gt; and
similar security issues. See <xref target="securitycons"/> for warnings about this step.</t>
  <t>If an &lt;artwork&gt; element has a “src” attribute, and the element has
content, give an error.</t>
  <t>If an &lt;artwork&gt; element has type=’svg’ and there is a “src” attribute,
the data needs to be moved into the content of the &lt;artwork&gt; element.
  <list style="symbols">
      <t>If the “src” URI scheme is “data:”, fill the content of the &lt;artwork&gt;
 element with that data and remove the “src” attribute.</t>
      <t>If the “src” URI scheme is “file:”, “http:”, or “https:”, fill the content
 of the &lt;artwork&gt; element with the resolved XML from the URI in the
 “src” attribute. If there is no “originalSrc” attribute,
 add an “originalSrc” attribute with the value of the URI and
 remove the “src” attribute.</t>
      <t>If the &lt;artwork&gt; element has an “alt” attribute, and the SVG does not
 have a &lt;desc&gt; element, add the &lt;desc&gt; element with the contents
 of the “alt” attribute.</t>
    </list></t>
  <t>If an &lt;artwork&gt; element has type=’binary-art’, the data needs to be in
a “src” attribute with a URI scheme of “data:”. If the “src” URI scheme is
“file:”, “http:”, or “https:”, resolve the URL. 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 needs 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 de-prioritized.</t>
  <t>If an &lt;artwork&gt; element does not have type=’svg’ or type=’binary-art’
and there is a “src” attribute, the data needs to be moved into the content of
the &lt;artwork&gt; element. Note that this step assumes that all of the
preferred types other than “binary-art” are text, which is possibly wrong.
  <list style="symbols">
      <t>If the “src” URI scheme is “data:”, fill the content of the &lt;artwork&gt;
 element with the correctly-escaped form of that data and remove the “src”
 attribute.</t>
      <t>If the “src” URI scheme is “file:”, “http:”, or “https:”, fill the content
 of the &lt;artwork&gt; element with the correctly-escaped form of the
 resolved text from the URI in the “src” attribute.
 If there is no “originalSrc” attribute, add an “originalSrc”
 attribute with the value of the URI and remove the “src” attribute.</t>
    </list></t>
</list></t>

</section>
<section anchor="sourcecode-processing" title="&lt;sourcecode&gt; Processing">

<t><list style="numbers">
  <t>If a &lt;sourcecode&gt; element has a “src” attribute where no scheme is
specified, copy the “src” attribute value to the “originalSrc” attribute, and
replace the “src” value with a URI that uses the “file:” scheme in a path
relative to the file being processed.
See <xref target="securitycons"/> for warnings about this step. This will likely
be one of the most common authoring approaches.</t>
  <t>If a &lt;sourcecode&gt; element has a “src” attribute with a “file:” scheme,
and if processing the URL would cause the processor to retrieve a file that is
not in the same directory, or a subdirectory, as the file being processed, give
an error. If the “src” has any shellmeta strings (such as “`”, “$USER”, and so
on) that would be processed , give an error. Replace the “src” attribute with a
URI that uses the “file:” scheme in a path relative to the file being processed.
This rule attempts to prevent &lt;sourcecode src=’file:///etc/passwd’&gt; and
similar security issues. See <xref target="securitycons"/> for warnings about this step.</t>
  <t>If a &lt;sourcecode&gt; element has a “src” attribute, and the element has
content, give an error.</t>
  <t>If a &lt;sourcecode&gt; element has a “src” attribute,
the data needs to be moved into the content of the &lt;sourcecode&gt; element.  <list style="symbols">
      <t>If the “src” URI scheme is “data:”, fill the content of the &lt;sourcecode&gt;
 element with that data and remove the “src” attribute.</t>
      <t>If the “src” URI scheme is “file:”, “http:”, or “https:”, fill the content
 of the &lt;sourcecode&gt; element with the resolved XML from the URI in the
 “src” attribute. If there is no “originalSrc” attribute,
 add an “originalSrc” attribute with the value of the URI and
 remove the “src” attribute.</t>
    </list></t>
</list></t>

</section>
</section>
<section anchor="rfc-production-mode-cleanup" title="RFC Production Mode Cleanup">

<t>These steps provide extra cleanup of the output document in RFC
production mode.</t>

<section anchor="note-removal" title="&lt;note&gt; Removal">

<t>If in RFC production mode, if there is a &lt;note&gt; or &lt;section&gt; element with a
“removeInRFC” attribute that has the value “true”, remove the
element.</t>

</section>
<section anchor="cref-removal" title="&lt;cref&gt; Removal">

<t>If in RFC production mode, remove all &lt;cref&gt; elements.</t>

</section>
<section anchor="link-processing" title="&lt;link&gt; Processing">

<t><list style="numbers">
  <t>If in RFC production mode, remove all &lt;link&gt; elements whose “rel”
attribute has the value “alternate”.</t>
  <t>If in RFC production mode, check if there is a &lt;link&gt; element with the
current ISSN for the RFC series (2070-1721); if not, add
&lt;link rel=”item” href=”urn:issn:2070-1721”&gt;.</t>
  <t>If in RFC production mode, check if there is a &lt;link&gt; element with
a DOI for this RFC; if not, add one
of the form &lt;link rel=”describedBy” href=”https://dx.doi.org/10.17487/rfcdd”&gt;
where “dd” is the number of the RFC, such as “https://dx.doi.org/10.17487/rfc2109”.
The URI is described in <xref target="RFC7669" />.
If there was already a &lt;link&gt; element with a DOI for this RFC, check that
the “href” value has the right format.</t>
  <t>If in RFC production mode, check if there is a &lt;link&gt; element with
the file name of the Internet-Draft that became this RFC
the form &lt;link rel=”convertedFrom” href=”https://datatracker.ietf.org/doc/draft-tttttttttt/”&gt;.
If one does not exist, give an error.</t>
</list></t>

</section>
<section anchor="xml-comment-removal" title="XML Comment Removal">

<t>If in RFC production mode, remove XML comments.</t>

</section>
<section anchor="base-originalsrc-removal" title="“xml:base” and “originalSrc” Removal">

<t>If in RFC production mode, remove all “xml:base” or “originalSrc” attributes
from all elements.</t>

</section>
<section anchor="compliance-check" title="Compliance Check">

<t>If in RFC production mode, ensure that the result is in full compliance to v3
schema, without any deprecated elements or attributes, and give an error if any
issues are found.</t>

</section>
</section>
<section anchor="finalization" title="Finalization">

<t>These steps provide the finishing touches on the output document.</t>

<section anchor="scripts-insertion" title="“scripts” Insertion">

<t>Determine all the characters used in the document, and fill in the “scripts”
attribute for &lt;rfc&gt;.</t>

</section>
<section anchor="pretty" title="Pretty-Format">

<t>Pretty-format the XML output.  (Note: there are many tools
that do an adequate job.)</t>

</section>
</section>
</section>
<section anchor="additional-uses-for-the-prep-tool" title="Additional Uses for the Prep Tool">

<t>There will be a need for Internet-Draft authors who include files from their
local disk (such as for &lt;artwork src=”mydrawing.svg”/&gt;) to have the
contents of those files inlined to 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, having a local copy of the prep tool
that has an option to just inline all local files would be terribly useful. That
option would be a proper subset of the steps given in <xref target="steps"/>.</t>

<t>A feature that might be useful in a local prep tool would be the inverse of the
“just inline” option would be “extract all”. This would allow a user who has a
v3 RFC or Internet-Draft to dump all of the &lt;artwork&gt; and
&lt;sourcecode&gt; elements into local files instead of having to find each one
in the XML. This option might even do as much validation as possible on the
extracted &lt;sourcecode&gt; elements.  This feature might also remove some of
the features added by the prep tool (such as part numbers and slugifiedName’s
starting with “n-“) in order to make the resulting file easier to edit.</t>

</section>
<section anchor="ianacons" title="IANA Considerations">

<t>None.</t>

</section>
<section anchor="securitycons" title="Security Considerations">

<t>Steps in this document attempt to prevent the &lt;artwork&gt; and
&lt;sourcecode&gt; entities from exposing the contents of files outside the
directory in which the document being processed resides. For example, values
starting with “/”, “./”, or “../” should generate errors.</t>

<t>The security considerations in <xref target="RFC3470"/> apply here. In specific, processing
XML external references can expose a prep tool implementation to various threats
by causing the implementation to access external resources automatically. It is
important to disallow arbitrary access to such external references within XML
data from untrusted sources.</t>

</section>
<section anchor="acknowledgements" title="Acknowledgements">

<t>Many people contributed valuable ideas to this document. Special thanks go to
Robert Sparks for his in-depth review and contributions early in the development
of this document, and to Julian Reschke for his help getting the document
structured more clearly.</t>

</section>


  </middle>

  <back>


    <references title='Informative References'>





<reference  anchor='RFC3470' target='http://www.rfc-editor.org/info/rfc3470'>
<front>
<title>Guidelines for the Use of Extensible Markup Language (XML) within IETF Protocols</title>
<author initials='S.' surname='Hollenbeck' fullname='S. Hollenbeck'><organization /></author>
<author initials='M.' surname='Rose' fullname='M. Rose'><organization /></author>
<author initials='L.' surname='Masinter' fullname='L. Masinter'><organization /></author>
<date year='2003' month='January' />
<abstract><t>The Extensible Markup Language (XML) is a framework for structuring data.  While it evolved from Standard Generalized Markup Language (SGML) -- a markup language primarily focused on structuring documents -- XML has evolved to be a widely-used mechanism for representing structured data. There are a wide variety of Internet protocols being developed; many have need for a representation for structured data relevant to their application.  There has been much interest in the use of XML as a representation method.  This document describes basic XML concepts, analyzes various alternatives in the use of XML, and provides guidelines for the use of XML within IETF standards-track protocols.  This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t></abstract>
</front>
<seriesInfo name='BCP' value='70'/>
<seriesInfo name='RFC' value='3470'/>
<seriesInfo name='DOI' value='10.17487/RFC3470'/>
</reference>



<reference  anchor='RFC6949' target='http://www.rfc-editor.org/info/rfc6949'>
<front>
<title>RFC Series Format Requirements and Future Development</title>
<author initials='H.' surname='Flanagan' fullname='H. Flanagan'><organization /></author>
<author initials='N.' surname='Brownlee' fullname='N. Brownlee'><organization /></author>
<date year='2013' month='May' />
<abstract><t>This document describes the current requirements and requests for enhancements for the format of the canonical version of RFCs.  Terms are defined to help clarify exactly which stages of document production are under discussion for format changes.  The requirements described in this document will determine what changes will be made to RFC format.  This document updates RFC 2223.</t></abstract>
</front>
<seriesInfo name='RFC' value='6949'/>
<seriesInfo name='DOI' value='10.17487/RFC6949'/>
</reference>



<reference  anchor='RFC7669' target='http://www.rfc-editor.org/info/rfc7669'>
<front>
<title>Assigning Digital Object Identifiers to RFCs</title>
<author initials='J.' surname='Levine' fullname='J. Levine'><organization /></author>
<date year='2015' month='October' />
<abstract><t>This document describes the way that Digital Object Identifiers (DOIs) are assigned to past and future RFCs.  The DOI is a widely used system that assigns unique identifiers to digital documents that can be queried and managed in a consistent fashion.</t></abstract>
</front>
<seriesInfo name='RFC' value='7669'/>
<seriesInfo name='DOI' value='10.17487/RFC7669'/>
</reference>



<reference anchor='I-D.iab-rfc5741bis'>
<front>
<title>On RFC Streams, Headers, and Boilerplates</title>

<author initials='J' surname='Halpern' fullname='Joel Halpern'>
    <organization />
</author>

<author initials='L' surname='Daigle' fullname='Leslie Daigle'>
    <organization />
</author>

<author initials='O' surname='Kolkman' fullname='Olaf Kolkman'>
    <organization />
</author>

<date month='February' day='2' year='2016' />

<abstract><t>RFC documents contain a number of fixed elements such as the title page header, standard boilerplates and copyright/IPR statements. This document describes them and introduces some updates to reflect current usage and requirements of RFC publication.  In particular, this updated structure is intended to communicate clearly the source of RFC creation and review.  This document obsoletes RFC 5741, moving detailed content to an IAB web page and preparing for more flexible output formats.</t></abstract>

</front>

<seriesInfo name='Internet-Draft' value='draft-iab-rfc5741bis-02' />
<format type='TXT'
        target='http://www.ietf.org/internet-drafts/draft-iab-rfc5741bis-02.txt' />
</reference>



<reference anchor='I-D.iab-xml2rfc'>
<front>
<title>The "xml2rfc" version 3 Vocabulary</title>

<author initials='P' surname='Hoffman' fullname='Paul E. Hoffman'>
    <organization />
</author>

<date month='June' day='22' year='2016' />

<abstract><t>This document defines the "xml2rfc" version 3 vocabulary: an XML- based language used for writing RFCs and Internet-Drafts.  It is heavily derived from the version 2 vocabulary that is also under discussion.  This document obsoletes the v2 grammar described in RFC 2629 and its followup, RFC 7749.  Editorial Note (To be removed by RFC Editor)  Discussion of this draft takes place on the rfc-interest mailing list (rfc-interest@rfc-editor.org), which has its home page at &lt;https://www.rfc-editor.org/mailman/listinfo/rfc-interest>.</t></abstract>

</front>

<seriesInfo name='Internet-Draft' value='draft-iab-xml2rfc-04' />
<format type='TXT'
        target='http://www.ietf.org/internet-drafts/draft-iab-xml2rfc-04.txt' />
</reference>




    </references>



  </back>
</rfc>