RFC v3 Prep Tool Description
draft-hoffman-rfcv3-preptool-00

Network Working Group                                         P. Hoffman
Internet-Draft                                            VPN Consortium
Intended status: Informational                             J. Hildebrand
Expires: November 23, 2015                                         Cisco
                                                            May 22, 2015

                      RFC v3 Prep Tool Description
                      draft-hoffman-rfcv3-preptool-00

Abstract

   This short document describes some aspects of the "prep tool" that is
   expected to be created when the new RFC v3 specification is deployed.
   This draft is just a way to keep track of the ideas; it is not
   (currently) expected to be published as an RFC.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on November 23, 2015.

Copyright Notice

   Copyright (c) 2015 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
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Hoffman & Hildebrand    Expires November 23, 2015               [Page 1]
Internet-Draft        RFC v3 Prep Tool Description              May 2015

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  v3 Prep Tool Usage Scenarios  . . . . . . . . . . . . . . . .   2
   3.  Internet-Draft Submission . . . . . . . . . . . . . . . . . .   2
   4.  Canonical RFC Preparation . . . . . . . . . . . . . . . . . .   3
   5.  What the v3 Prep Tool Does  . . . . . . . . . . . . . . . . .   3
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   5
   7.  Security Considerations . . . . . . . . . . . . . . . . . . .   5
   8.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .   5
   9.  Informative References  . . . . . . . . . . . . . . . . . . .   5
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   5

1.  Introduction

   This document describes some aspects of the "prep tool" that is
   expected to be created when the new RFC v3 specification is deployed.

   See [I-D.hoffman-xml2rfc] and [RFC6949] for more context for this
   draft.

2.  v3 Prep Tool Usage Scenarios

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

   o  Internet-Draft preparation

   o  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 work-alike prep tools for their own
   formatting needs.  However, an output format 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.

   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.

3.  Internet-Draft Submission

   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

Hoffman & Hildebrand    Expires November 23, 2015               [Page 2]
Internet-Draft        RFC v3 Prep Tool Description              May 2015

   submitted file and the prepped file.  This prepped file represents a
   self-contained record of what any external references resolved to at
   the time of submission.  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.

   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 we create a .mobi output renderer later,
   we can run that renderer on all of the prepped XML that we have
   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.

4.  Canonical RFC Preparation

   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.

   Similarly to I-D's, the prepped XML can be used later to re-render
   the output formats, or to generate new formats.

5.  What the v3 Prep Tool Does

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

   1.   Process all <x:include> elements.  Note: <x:include>d XML may
        include more <x:include>s (with relative URLs rooted at the
        xml:base), so set a limit on the depth of recursion.

   2.   If in RFC production mode, remove comments.

   3.   If boilerplate exists in the input, produce a scary warning.
        Otherwise, fill in boilerplate text with current values.

   4.   Fill in the "prepTime" attribute of <rfc> with the current
        datetime.

Hoffman & Hildebrand    Expires November 23, 2015               [Page 3]
Internet-Draft        RFC v3 Prep Tool Description              May 2015

   5.   If in I-D mode, fill in "expiresDate" attribute of <rfc>.

   6.   Fill in any default values for attributes on elements, except
        "keepWithNext" and "keepWithPrevious" of <t>, and "toc" of
        <section>.

   7.   If the <workgroup> content doesn't end with "Group", issue a
        warning.

   8.   Add a "slugifiedName" attribute to each <name> element that does
        not contain a valid one (all values must be valid HTML id's, and
        all start with with "n-").

   9.   Remove any existing "pn" attributes.

   10.  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]'

   11.  Add a "start" attribute to every <ol> element containing a group
        that doesn't already have a start.

   12.  Sort the references, if "sortRefs" of <rfc> is true.

   13.  Resolve all <xref> elements.  Ensure that each target is valid.
        Invent text for each element that doesn't have it.

   14.  Process <artwork> elements.  If an element has type='svg', and
        if there is a "src" attribute, inline and remove the "src"
        attribute, and insert "xml:base" attribute; also check SVG
        schema against our TinySVG profile.  Otherwise, if the "src"
        attribute is not a "data:" URI, turn it into a "data:" URI and
        insert "xml:base" attribute.

   15.  Add a <link> child element to <rfc> for the DOI, if in RFC
        production mode.

Hoffman & Hildebrand    Expires November 23, 2015               [Page 4]
Internet-Draft        RFC v3 Prep Tool Description              May 2015

   16.  Determine all the characters used in the document, and fill in
        "scripts" attribute for <rfc>.

   17.  Ensure that the output has the "version" attribute of <rfc>, and
        that it is set to "3".

   18.  Pretty-format the XML output.  (Note: tools like
        https://github.com/hildjj/dentin do an adequate job.)

   19.  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.

6.  IANA Considerations

   None.

7.  Security Considerations

   None.

8.  Acknowledgements

   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.

9.  Informative References

   [I-D.hoffman-xml2rfc]
              Hoffman, P., "The 'XML2RFC' version 3 Vocabulary", draft-
              hoffman-xml2rfc-17 (work in progress), April 2015.

   [RFC6949]  Flanagan, H. and N. Brownlee, "RFC Series Format
              Requirements and Future Development", RFC 6949, May 2013.

Authors' Addresses

   Paul Hoffman
   VPN Consortium

   Email: paul.hoffman@vpnc.org

   Joe Hildebrand
   Cisco

   Email: jhildebr@cisco.com

Hoffman & Hildebrand    Expires November 23, 2015               [Page 5]