RSE Wiki Archive

The prep tool will have (at least) two settings:

• Internet-Draft preparation
• Canonical RFC preparation

There are only a few difference between these two settings. For example, the boilerplate output will be different, as will the date output on the front page.

Note that this only describes what the IETF-sponsored prep tool does. Others might create their own prep tools for their own formatting needs. However, a developer does not not need to change the prep tool in order to create their own formatter: they only need to be able to consume prepared text.

Also note that this prep tool could be expanded to be a “v2 to v3 converter” or a “v3 to v3 prettifier”; however, those settings would have only a subset of the steps below. For example, a converter would not remove comments.

When the IETF draft submission tool accepts v3 XML as an input format, the submission tool runs the submitted file through the prep tool. If the tool finds no errors, it keeps two XML files: the submitted file and the prepped file. The prepped file is used by the IETF formatters to create outputs such as HTML, PDF, and text. 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.

During AUTH48, the RPC will run the prep tool in canonical RFC preparation mode and make the results available to the authors so they can see what the final output might look like. When the document is done with AUTH48 review, the RPC runs the prep tool in canonical RFC preparation mode one last time, locks down the canonicalized XML, runs the formatters for the non-canonical output, and publishes all of those. It is probably a good idea for the RPC to keep a copy of the input XML file from the various steps of the RFC production process.

This is a mostly-complete list of what the v3 prep tool does. The steps are in order of processing.

• Process all <x:include> elements. Note: <x:include>d XML may include more <x:include>s (with relative URLs rooted at the xml:base), set a limit on the depth of recursion.
• Remove comments
• Replace or remove all deprecated features to the greatest extent possible. Generate warnings or errors as needed.
  • Replace yes/no values in some attributes with true/false
  • All other v2→v3 conversions
• Fill in document date and expires date, if applicable
• Remove current boilerplate text
  • After removing, fill in boilerplate text with current values
• Fill in any default values for attributes on elements, except t/@keepWith* and section/@toc
• If the <workgroup> item doesn't end with Group, add (Working|Research) Group to the end
• Add slugifiedName to each <name> that does not contain a valid one (generating only valid HTML id's starting with n-)
• Remove any existing pn attributes
• Add pn attributes for all parts. Parts are:
  • section: pn='s-1.4.2'
    • except <abstract>, which gets pn='s-abstract'
    • except <note>, which gets pn='s-note-[counter]'
  • table: pn='t-3'
  • figure: pn='f-4'
  • (abstract, note, t, aside, blockquote, li, dt, artwork, sourcecode, references): pn='p-[section]-[counter]'
• Resolve all <xref> elements
  • Ensure the target is valid
  • Invent text for each element that doesn't have it
• Process <artwork>
  • if type='svg'
    • If src attribute, inline and remove src, insert xml:base
    • Check SVG schema against our TinySVG profile
  • else if src != data:, turn into data:, insert xml:base
• Add rfc/@finalizedTime attribute
• Pretty-format the XML output. Note: Dentin now does an adequate job.
  • This step might be controversial
• Do a final sanity check to ensure full compliance to v3 schema, without any deprecated elements or attributes; this is to be sure that none of the added or changed text breaks compliance.