One document matched: draft-hoffman-rfcv3-preptool-01.txt
Differences from draft-hoffman-rfcv3-preptool-00.txt
Network Working Group P. Hoffman
Internet-Draft VPN Consortium
Intended status: Informational J. Hildebrand
Expires: December 3, 2015 Cisco
June 01, 2015
RFC v3 Prep Tool Description
draft-hoffman-rfcv3-preptool-01
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 December 3, 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 December 3, 2015 [Page 1]
Internet-Draft RFC v3 Prep Tool Description June 2015
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. v3 Prep Tool Usage Scenarios . . . . . . . . . . . . . . . . 2
3. Internet-Draft Submission . . . . . . . . . . . . . . . . . . 3
4. Canonical RFC Preparation . . . . . . . . . . . . . . . . . . 3
5. What the v3 Prep Tool Does . . . . . . . . . . . . . . . . . 4
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5
7. Security Considerations . . . . . . . . . . . . . . . . . . . 5
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 6
9. Informative References . . . . . . . . . . . . . . . . . . . 6
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 6
1. Introduction
As a part of the new HTML format work, the RFC Editor has decided
that the XML2RFCv3 vocabulary [I-D.hoffman-xml2rfc] will be
canonical, in the sense that it is the data that is blessed by the
process as the actual RFC. See [RFC6949] for more detail on this.
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 format is as similar as possible to one another as well as the
canonical XML, there is a desire for 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 notthere today. That data will be added by a program
called the "prep tool", which will often run as a part of the xml2rfc
process.
This draft specifies the steps that the prep tool will have to take.
As changes to [I-D.hoffman-xml2rfc] are made, this document will be
updated.
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
Hoffman & Hildebrand Expires December 3, 2015 [Page 2]
Internet-Draft RFC v3 Prep Tool Description June 2015
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
submitted file and the prepped file.
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.
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 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.
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.
Hoffman & Hildebrand Expires December 3, 2015 [Page 3]
Internet-Draft RFC v3 Prep Tool Description June 2015
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
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 is correct. 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.
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. Add the boilerplate text with current values. However, if
different boilerplate text already exists in the input, produce
a scary warning that says that other tools, specifically the
draft submission tool, will treat that condition as an error.
4. Fill in the "prepTime" attribute of <rfc> with the current
datetime.
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. 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'
Hoffman & Hildebrand Expires December 3, 2015 [Page 4]
Internet-Draft RFC v3 Prep Tool Description June 2015
* <figure>: pn='f-4'
* (<abstract>, <note>, <t>, <aside>, <blockquote>, <li>, <dt>,
<artwork>, <sourcecode>, <references>):
pn='p-[section]-[counter]'
10. Add a "start" attribute to every <ol> element containing a group
that doesn't already have a start.
11. Sort the references, if "sortRefs" of <rfc> is true.
12. Resolve all <xref> elements. Ensure that each target is valid.
Invent text for each element that doesn't have it. (More steps
will be added here when the community has agreement on *ref.)
1. 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.
2. Add a <link> child element to <rfc> for the DOI, if in RFC
production mode.
3. Determine all the characters used in the document, and fill in
"scripts" attribute for <rfc>.
4. Ensure that the output has the "version" attribute of <rfc>, and
that it is set to "3".
5. Pretty-format the XML output. (Note: tools like
https://github.com/hildjj/dentin do an adequate job.)
6. 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.
Hoffman & Hildebrand Expires December 3, 2015 [Page 5]
Internet-Draft RFC v3 Prep Tool Description June 2015
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-18 (work in progress), May 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 December 3, 2015 [Page 6]
| PAFTECH AB 2003-2026 | 2026-04-24 07:13:34 |