Index of /authoring

[ICO]NameLast modifiedSizeDescription

[DIR]Parent Directory  -  
[   ]LICENSE27-Mar-2011 23:07 1.4K 
[TXT]README-dev.html27-Mar-2011 23:07 65K 
[TXT]README-dev.html.sv26-Jan-2011 16:09 64K 
[TXT]README.html10-Jul-2012 18:32 64K 
[   ]TclXML-1_1_1.tgz27-Mar-2011 23:07 33K 
[   ]TclXML-1_1_1.zip27-Mar-2011 23:07 41K 
[   ]beta27-Mar-2011 23:07 10  
[DIR]bibxml/01-Apr-2010 15:28 -  
[DIR]contrib/01-Apr-2010 15:29 -  
[TXT]draft-mrose-writing-rfcs.html27-Mar-2011 23:07 86K 
[TXT]draft-mrose-writing-rfcs.txt27-Mar-2011 23:07 62K 
[   ]rfc2629-other.ent27-Mar-2011 23:07 3.7K 
[   ]rfc2629-xhtml.ent27-Mar-2011 23:07 15K 
[   ]rfc2629.dtd27-Mar-2011 23:07 9.3K 
[TXT]rfc2629.html27-Mar-2011 23:07 57K 
[   ]rfc2629.rnc27-Mar-2011 23:07 10K 
[TXT]rfc2629.txt27-Mar-2011 23:07 48K 
[   ]rfc2629.xml27-Mar-2011 23:07 45K 
[   ]rfc2629.xsd27-Mar-2011 23:07 20K 
[   ]rfc2629.xslt27-Mar-2011 23:07 107K 
[   ]rfc2629xslt.zip27-Mar-2011 23:07 586K 
[TXT]sample.html27-Mar-2011 23:07 12K 
[TXT]sample.txt27-Mar-2011 23:07 5.4K 
[TXT]sample.xml27-Mar-2011 23:07 1.3K 
[   ]version27-Mar-2011 23:07 6  
[   ]xml2rfc-1.6.tgz27-Mar-2011 23:07 151K 
[   ]xml2rfc-1.7.tgz27-Mar-2011 23:07 154K 
[   ]xml2rfc-1.8.tgz27-Mar-2011 23:07 154K 
[DIR]xml2rfc-1.8/27-Mar-2011 23:17 -  
[   ]xml2rfc-1.9.tgz27-Mar-2011 23:07 164K 
[DIR]xml2rfc-1.9/27-Mar-2011 23:17 -  
[   ]xml2rfc-1.10.tgz27-Mar-2011 23:07 165K 
[DIR]xml2rfc-1.10/27-Mar-2011 23:16 -  
[   ]xml2rfc-1.11.tgz27-Mar-2011 23:07 156K 
[DIR]xml2rfc-1.11/27-Mar-2011 23:16 -  
[   ]xml2rfc-1.12.tgz27-Mar-2011 23:07 133K 
[DIR]xml2rfc-1.12/27-Mar-2011 23:16 -  
[   ]xml2rfc-1.13.tgz27-Mar-2011 23:07 136K 
[DIR]xml2rfc-1.13/27-Mar-2011 23:16 -  
[   ]xml2rfc-1.14.tgz27-Mar-2011 23:07 141K 
[DIR]xml2rfc-1.14/27-Mar-2011 23:16 -  
[   ]xml2rfc-1.15.tgz27-Mar-2011 23:07 158K 
[DIR]xml2rfc-1.15/27-Mar-2011 23:16 -  
[   ]xml2rfc-1.16.tgz27-Mar-2011 23:07 160K 
[DIR]xml2rfc-1.16/27-Mar-2011 23:16 -  
[   ]xml2rfc-1.17.tgz27-Mar-2011 23:07 160K 
[DIR]xml2rfc-1.17/27-Mar-2011 23:16 -  
[   ]xml2rfc-1.18.tgz27-Mar-2011 23:07 174K 
[DIR]xml2rfc-1.18/27-Mar-2011 23:16 -  
[   ]xml2rfc-1.19.tgz27-Mar-2011 23:07 174K 
[DIR]xml2rfc-1.19/27-Mar-2011 23:16 -  
[   ]xml2rfc-1.20.tgz27-Mar-2011 23:07 304K 
[DIR]xml2rfc-1.20/27-Mar-2011 23:16 -  
[   ]xml2rfc-1.21.tgz27-Mar-2011 23:07 306K 
[DIR]xml2rfc-1.21/27-Mar-2011 23:16 -  
[   ]xml2rfc-1.22.tgz27-Mar-2011 23:07 449K 
[DIR]xml2rfc-1.22/27-Mar-2011 23:16 -  
[   ]xml2rfc-1.23.tgz27-Mar-2011 23:07 454K 
[DIR]xml2rfc-1.23/27-Mar-2011 23:16 -  
[   ]xml2rfc-1.24.tgz27-Mar-2011 23:07 334K 
[DIR]xml2rfc-1.24/27-Mar-2011 23:16 -  
[   ]xml2rfc-1.25.tgz27-Mar-2011 23:07 339K 
[DIR]xml2rfc-1.25/27-Mar-2011 23:16 -  
[   ]xml2rfc-1.26.tgz27-Mar-2011 23:07 360K 
[DIR]xml2rfc-1.26/27-Mar-2011 23:16 -  
[   ]xml2rfc-1.27.tgz27-Mar-2011 23:07 365K 
[DIR]xml2rfc-1.27/27-Mar-2011 23:17 -  
[   ]xml2rfc-1.28.tgz27-Mar-2011 23:07 365K 
[DIR]xml2rfc-1.28/27-Mar-2011 23:17 -  
[   ]xml2rfc-1.29.tgz27-Mar-2011 23:07 393K 
[DIR]xml2rfc-1.29/27-Mar-2011 23:17 -  
[   ]xml2rfc-1.29rc1.tgz27-Mar-2011 23:07 369K 
[   ]xml2rfc-1.29rc1.zip27-Mar-2011 23:07 386K 
[DIR]xml2rfc-1.29rc1/27-Mar-2011 23:17 -  
[   ]xml2rfc-1.29rc2.tgz27-Mar-2011 23:07 380K 
[   ]xml2rfc-1.29rc2.zip27-Mar-2011 23:07 398K 
[DIR]xml2rfc-1.29rc2/27-Mar-2011 23:17 -  
[   ]xml2rfc-1.29rc3.tgz27-Mar-2011 23:07 388K 
[   ]xml2rfc-1.29rc3.zip27-Mar-2011 23:07 406K 
[DIR]xml2rfc-1.29rc3/27-Mar-2011 23:17 -  
[   ]xml2rfc-1.29rc4.tgz27-Mar-2011 23:07 388K 
[   ]xml2rfc-1.29rc4.zip27-Mar-2011 23:07 407K 
[DIR]xml2rfc-1.29rc4/27-Mar-2011 23:17 -  
[   ]xml2rfc-1.30.tgz27-Mar-2011 23:07 426K 
[DIR]xml2rfc-1.30/27-Mar-2011 23:17 -  
[   ]xml2rfc-1.31.tgz27-Mar-2011 23:07 553K 
[DIR]xml2rfc-1.31/27-Mar-2011 23:17 -  
[   ]xml2rfc-1.32.tgz27-Mar-2011 23:07 624K 
[DIR]xml2rfc-1.32/27-Mar-2011 23:17 -  
[   ]xml2rfc-1.33.tgz27-Mar-2011 23:07 674K 
[   ]xml2rfc-1.33.zip27-Mar-2011 23:07 693K 
[DIR]xml2rfc-1.33/27-Mar-2011 23:17 -  
[   ]xml2rfc-1.33pre2.tgz27-Mar-2011 23:07 624K 
[DIR]xml2rfc-1.33pre2/27-Mar-2011 23:17 -  
[   ]xml2rfc-1.33pre3.tgz27-Mar-2011 23:07 637K 
[DIR]xml2rfc-1.33pre3/27-Mar-2011 23:17 -  
[   ]xml2rfc-1.33pre4.tgz27-Mar-2011 23:07 640K 
[DIR]xml2rfc-1.33pre4/27-Mar-2011 23:17 -  
[   ]xml2rfc-1.34.tgz27-Mar-2011 23:07 880K 
[DIR]xml2rfc-1.34/27-Mar-2011 23:17 -  
[   ]xml2rfc-1.34pre2.tgz27-Mar-2011 23:07 675K 
[DIR]xml2rfc-1.34pre2/27-Mar-2011 23:17 -  
[   ]xml2rfc-1.34pre3.tgz27-Mar-2011 23:07 733K 
[DIR]xml2rfc-1.34pre3/27-Mar-2011 23:17 -  
[   ]xml2rfc-1.34pre4.tgz27-Mar-2011 23:07 879K 
[   ]xml2rfc-1.34pre4.zip27-Mar-2011 23:07 1.0M 
[DIR]xml2rfc-1.34pre4/27-Mar-2011 23:17 -  
[   ]xml2rfc-1.34pre5.tgz27-Mar-2011 23:07 880K 
[DIR]xml2rfc-1.34pre5/27-Mar-2011 23:17 -  
[   ]xml2rfc-1.35.tgz27-Mar-2011 23:07 1.4M 
[   ]xml2rfc-1.35.zip27-Mar-2011 23:07 4.3M 
[DIR]xml2rfc-1.35/27-Mar-2011 23:17 -  
[DIR]xml2rfc-1.35pre1/27-Mar-2011 23:17 -  
[   ]xml2rfc-1.36.tgz26-Mar-2011 10:20 1.5M 
[   ]xml2rfc-1.36.zip26-Mar-2011 10:20 1.9M 
[DIR]xml2rfc-1.36/26-Mar-2011 10:16 -  
[   ]xml2rfc-1_6.zip27-Mar-2011 23:07 169K 
[   ]xml2rfc-1_7.zip27-Mar-2011 23:07 171K 
[   ]xml2rfc-1_8.zip27-Mar-2011 23:07 171K 
[   ]xml2rfc-1_9.zip27-Mar-2011 23:07 181K 
[   ]xml2rfc-1_10.zip27-Mar-2011 23:07 181K 
[   ]xml2rfc-1_11.zip27-Mar-2011 23:07 203K 
[   ]xml2rfc-1_12.zip27-Mar-2011 23:07 142K 
[   ]xml2rfc-1_13.zip27-Mar-2011 23:07 145K 
[   ]xml2rfc-1_14.zip27-Mar-2011 23:07 148K 
[   ]xml2rfc-1_15.zip27-Mar-2011 23:07 166K 
[   ]xml2rfc-1_16.zip27-Mar-2011 23:07 167K 
[   ]xml2rfc-1_17.zip27-Mar-2011 23:07 167K 
[   ]xml2rfc-1_18.zip27-Mar-2011 23:07 181K 
[   ]xml2rfc-1_19.zip27-Mar-2011 23:07 182K 
[   ]xml2rfc-1_20.zip27-Mar-2011 23:07 313K 
[   ]xml2rfc-1_21.zip27-Mar-2011 23:07 315K 
[   ]xml2rfc-1_22.zip27-Mar-2011 23:07 454K 
[   ]xml2rfc-1_23.zip27-Mar-2011 23:07 461K 
[   ]xml2rfc-1_24.zip27-Mar-2011 23:07 344K 
[   ]xml2rfc-1_25.zip27-Mar-2011 23:07 350K 
[   ]xml2rfc-1_26.zip27-Mar-2011 23:07 372K 
[   ]xml2rfc-1_27.zip27-Mar-2011 23:07 383K 
[   ]xml2rfc-1_28.zip27-Mar-2011 23:07 383K 
[   ]xml2rfc-1_29.zip27-Mar-2011 23:07 413K 
[   ]xml2rfc-1_30.zip27-Mar-2011 23:07 447K 
[   ]xml2rfc-1_31.zip27-Mar-2011 23:07 574K 
[   ]xml2rfc-1_32.zip27-Mar-2011 23:07 639K 
[   ]xml2rfc-1_33pre2.zip27-Mar-2011 23:07 645K 
[   ]xml2rfc-1_33pre3.zip27-Mar-2011 23:07 659K 
[   ]xml2rfc-1_33pre4.zip27-Mar-2011 23:07 662K 
[   ]xml2rfc-1_34.zip27-Mar-2011 23:07 1.0M 
[   ]xml2rfc-1_34pre2.zip27-Mar-2011 23:07 694K 
[   ]xml2rfc-1_34pre3.zip27-Mar-2011 23:07 754K 
[   ]xml2rfc-1_34pre5.tgz27-Mar-2011 23:07 1.0M 
[   ]xml2rfc-dev.tgz27-Mar-2011 23:07 1.5M 
[   ]xml2rfc-dev.zip27-Mar-2011 23:07 1.9M 
[IMG]xml2rfc-win.png27-Mar-2011 23:07 3.9K 
[DIR]xml2rfc.1.6/27-Mar-2011 23:17 -  
[DIR]xml2rfc.1.7/27-Mar-2011 23:17 -  
[TXT]xml2rfc.tcl27-Mar-2011 23:07 566K 
[   ]xml2rfc.tgz27-Mar-2011 23:07 1.5M 
[   ]xml2rfc.zip27-Mar-2011 23:07 1.9M 
[   ]xml2rfc2-435.tgz26-Jul-2011 07:34 413K 
[   ]xml2rfc2-442.tgz27-Jul-2011 09:14 576K 
[   ]xml2rfc2-465.log29-Jul-2011 15:06 3.9K 
[   ]xml2rfc2-465.log.orig29-Jul-2011 15:06 3.9K 
[   ]xml2rfc2-465.tgz29-Jul-2011 15:01 755K 
[   ]xml2rfc2-481.log04-Aug-2011 11:27 3.2K 
[   ]xml2rfc2-481.log.orig04-Aug-2011 11:27 3.2K 
[   ]xml2rfc2-481.tgz04-Aug-2011 11:27 845K 
[   ]xml2rfc2-522.log25-Aug-2011 14:15 9.0K 
[   ]xml2rfc2-522.log.orig25-Aug-2011 14:15 9.0K 
[   ]xml2rfc2-522.tgz25-Aug-2011 14:15 1.1M 
[   ]xml2rfc2-524.log25-Aug-2011 14:39 9.3K 
[   ]xml2rfc2-524.log.orig25-Aug-2011 14:39 9.3K 
[   ]xml2rfc2-524.tgz25-Aug-2011 14:39 1.1M 
[   ]xml2rfc2-585.log24-Mar-2012 04:03 13K 
[   ]xml2rfc2-585.log.orig24-Mar-2012 04:03 13K 
[   ]xml2rfc2-585.tgz24-Mar-2012 04:03 9.9M 
[   ]xml2rfc2-dev.log04-Jul-2014 07:50 332K 
[   ]xml2rfc2-dev.log.orig11-Sep-2013 14:43 206K 
[   ]xml2rfc2-dev.tgz24-Mar-2012 04:03 9.9M 
[TXT]xml2sgml.tcl27-Mar-2011 23:07 105K 

The README file: xml2rfc v1.36pre1
 TOC 
The README fileM. Rose
 Dover Beach Consulting, Inc.
 B. Fenner
 Arista Networks, Inc.
 C. Levert
  
 T. Hansen
 AT&T Labs
 J. Reschke
 greenbytes
 July 10, 2012


xml2rfc v1.36pre1



Table of Contents

1.  Introduction
2.  Requirements
3.  Testing
3.1.  Testing under a windowing system
3.2.  Testing without a windowing system
4.  Next steps
4.1.  Processing Instructions
4.1.1.  Option Settings
4.1.2.  Include Files
5.  The Page Model
6.  Additions to RFC 2629
6.1.  Extra Attributes
6.2.  Typed-Artwork Interpretation
7.  Limitations of xml2rfc
8.  References
A.  Producing the IETF 'Boilerplate'
A.1.  The /rfc/@ipr Attribute
A.1.1.  Current Values: '*trust200902'
A.1.2.  Historic Values
A.2.  The /rfc/@category Attribute
A.3.  The /rfc/@submissionType Attribute
A.4.  The /rfc/@consensus Attribute
A.5.  The /rfc/@number Attribute
A.6.  The /rfc/@docName Attribute
A.7.  The /rfc/@obsoletes Attribute
A.8.  The /rfc/@updates Attribute
B.  MacOS 9 Installation (courtesy of Ned Freed)
C.  rfc2629.xslt (courtesy of Julian Reschke)
D.  MS-Windows/Cygwin Installation (courtesy of Joe Touch)
E.  A Special Thanks
F.  Copyrights
§  Index
§  Authors' Addresses




 TOC 

1.  Introduction

This is a package to convert memos written in XML to the RFC format.

If you don't want to install any software, you can use the web-based service.



 TOC 

2.  Requirements

You need to have Tcl/Tk version 8 running on your system. Tcl is a scripting language, Tk is Tcl with support for your windowing system.

To get a source or binary distribution for your system, go to the Tcl Developer Xchange website and install it. If you get the binary distribution, this is pretty simple.

Of course, you may already have Tcl version 8. To find out, try typing this command from the shell (or the “MS-DOS Prompt”):

    % tclsh

If the program launches, you're good to go with Tcl version 8.

If you are running under a windowing system (e.g., X or MS-Windows), you can also try:

    % wish

If a new window comes up along with a “Console” window, then you're good to go with Tk version 8.

Finally, you may notice a file called xml2sgml.tcl in the distribution. It contains some extra functionality for a few special users — so, if you don't know what it is, don't worry about it...



 TOC 

3.  Testing

Now test your installation.



 TOC 

3.1.  Testing under a windowing system

Type this command from the shell:

    % xml2rfc.tcl

A new window should come up that looks like this:

[“Convert XML to RFC” window]

Fill-in the blanks and click on [Convert].



 TOC 

3.2.  Testing without a windowing system

Type this command from the shell:

    % tclsh

If the program launches, type this command to it:

    % source xml2rfc.tcl

and you should see these five lines:

    invoke as "xml2rfc   input-file output-file"
           or "xml2txt   input-file"
           or "xml2html  input-file"
           or "xml2nroff input-file"
           or "xml2unpg  input-file"


 TOC 

4.  Next steps

Read the 2629bis document. In particular, Section 3 has some good information.



 TOC 

4.1.  Processing Instructions

A processing instruction contains directives to an XML application. If you want to give directives to xml2rfc, the processing instructions (PIs) look like this:

    <?rfc keyword='value'?>

Of course, if you like the default behavior, you don't need any behavior-modifying directives in your input file! Although xml2rfc supports putting several attribute-like directives in one PI, be warned that there are issues in doing this for a non-include-file directive following an include-file directive (Include Files). It is good practice to always surround the value with either single or double quotes.



 TOC 

4.1.1.  Option Settings

The list of valid keywords are:

keyworddefaultmeaning
artworkdelimiter "" when producing txt or nroff files, use this string to delimit artwork
artworklines 0 when producing txt or nroff files, add this many blank lines around artwork
authorship yes render author information
autobreaks yes automatically force page breaks to avoid widows and orphans (not perfect)
background "" when producing a html file, use this image
colonspace no put two spaces instead of one after each colon (“:”) in txt or nroff files
comments no render <cref> information
compact (rfcedstyle) when producing a txt/nroff file, try to conserve vertical whitespace (the default value is the current value of the rfcedstyle PI)
docmapping no use hierarchical tags (e.g., <h1>, <h2>, etc.) for (sub)section titles
editing no insert editing marks for ease of discussing draft versions
emoticonic no automatically replaces input sequences such as |*text| by, e.g., <strong>text</strong> in html output
footer "" override the center footer string
header "" override the leftmost header string
include n/a see Section 4.1.2 (Include Files)
inline no if comments is "yes", then render comments inline; otherwise render them in an “Editorial Comments” section
iprnotified no include boilerplate from Section 10.4(d) of [1] (Bradner, S., “The Internet Standards Process -- Revision 3,” October 1996.)
linkmailto yes generate mailto: URL, as appropriate
linefile n/a a string like "35:file.xml" or just "35" (file name then defaults to the containing file's real name or to the latest linefile specification that changed it) that will be used to override xml2rfc's reckoning of the current input position (right after this PI) for warning and error reporting purposes (line numbers are 1-based)
needLines n/a an integer hint indicating how many contiguous lines are needed at this point in the output
notedraftinprogress yes generates "(work in progress)", as appropriate
private "" produce a private memo rather than an RFC or Internet-Draft
refparent "References" title of the top-level section containing all references
rfcedstyle no attempt to closely follow finer details from the latest observable RFC-Editor style so as to minimize the probability of being sent back corrections after submission; this directive is a kludge whose exact behavior is likely to change on a regular basis to match the current flavor of the month; presently, it will capitalize the adjective “This” in automatically generated headings, use the variant “acknowledgement” spelling instead of Merriam Webster's main “acknowledgment” dictionary entry, use the “eMail” spelling instead of Knuth's more modern “email” spelling, only put one blank line instead of two before top sections, omit “Intellectual Property and Copyright Statements” and “Author's Address” from the table of content, and not limit the indentation to a maximum tag length in <references> sections.
rfcprocack no if there already is an automatically generated Acknowledg(e)ment section, pluralize its title and add a short sentence acknowledging that xml2rfc was used in the document's production to process an input XML source file in RFC-2629 format
slides no when producing a html file, produce multiple files for a slide show
sortrefs no sort references
strict no try to enforce the ID-nits conventions and DTD validity
subcompact (compact) if compact is "yes", then you can make things a little less compact by setting this to "no" (the default value is the current value of the compact PI)
symrefs yes use anchors rather than numbers for references
text-list-symbols o*+- modify the list of symbols used (when generated text) for list type="symbols". For example, specifying "abcde" will cause "a" to be used for 1st level, "b" for the 2nd level, etc, cycling back to the first character "a" at the 6th level. Specifying "o*" will cause the characters "o" and "*" to be alternated for each successive level.
toc no generate a table-of-contents
tocappendix yes control whether the word “Appendix” appears in the table-of-content
tocdepth 3 if toc is "yes", then this determines the depth of the table-of-contents
tocindent yes if toc is "yes", then setting this to "yes" will indent subsections in the table-of-contents
tocnarrow yes affects horizontal spacing in the table-of-content
tocompact yes if toc is "yes", then setting this to "no" will make it a little less compact
topblock yes put the famous header block on the first page
typeout n/a during processing pass 2, print the value to standard output at that point in processing
useobject no when producing a html file, use the <object> html element with inner replacement content instead of the <img> html element, when a source xml element includes an src attribute

Remember that, as with everything else in XML, keywords and values are case-sensitive.

With the exception of the needLines, typeout, and include directives, you normally put all of these processing instructions at the beginning of the document (right after the XML declaration).



 TOC 

4.1.2.  Include Files

xml2rfc has an include-file facility, e.g.,

    <?rfc include='file'?>

xml2rfc will consult the XML_LIBRARY environment variable for a search path of where to look for files. (If this environment variable isn't set, the directory containing the file that contains the include-file directive is used.) The file's contents are inserted right after the PI. Putting non-include-file directives (especially needLines ones) after an include-file one in the same PI may not work as expected because of this. Remember that file names are generally case-sensitive and that an input file that is distributed to the outside world may be processed on a different operating system than that used by its author.

You can also have xml2rfc set the XML_LIBRARY environment variable directly, by creating a file called .xml2rfc.rc in the directory where your main file is, e.g.,

global env tcl_platform

if {![string compare $tcl_platform(platform) windows]} {
    set sep ";"
} else {
    set sep ":"
}

if {[catch { set env(XML_LIBRARY) } library]} {
    set library ""
    foreach bibxmlD [lsort -dictionary \
                           [glob -nocomplain $HOME/rfcs/bibxml/*]] {
        append library $sep$bibxmlD
    }
}

set nativeD [file nativename $inputD]
if {[lsearch [split $library $sep] $nativeD] < 0} {
    set library "$nativeD$sep$library"
}

set env(XML_LIBRARY) $library

There are links to various bibliographic databases (RFCs, I-Ds, and so on) on the xml2rfc homepage.



 TOC 

5.  The Page Model

The html rendering engine does not need to have a tightly defined page model.

The txt and nr rendering engines assume the following page model.

Each line has at most 72 columns from the left edge, including any left margin, but excluding the line terminator. Every output character is from the ASCII repertoire and the only control character used is the line-feed (LF); the character-tabulation (HT) character is never used.

Each page has the following lines (in 1-based numbering, as reported to the user, but contrary to xml2rfc's internal 0-based numbering):

 1: header line (blank line on first page)

 2: blank line

 3: blank line

 4: 1st line of content

...

51: 48th line of content

52: blank line

53: blank line

54: blank line

55: footer line

56: form-feed character (followed by line terminator)

Once processed through nroff and the fix.sh script (from 2-nroff.template), the nr output differs from this in two ways. It has three extra blank lines (that could be numbered -2, -1, and 0, for a total of six) at the very beginning of the document (so the first page is that much longer). It also has no line terminator following the very last form-feed character of the file. These differences originate in the design of the fix.sh script.

Header and footer lines each have three parts: left, center, and right.



 TOC 

6.  Additions to RFC 2629

A few additions have been made to the format originally defined in RFC 2629. In particular, Appendix C of the 2629bis document enumerates the additions.



 TOC 

6.1.  Extra Attributes

In addition, xml2rfc recognizes the undocumented src, alt, width, and height attributes in the figure and artwork elements, but only if HTML is being generated. Here are two examples, one for each case.

Here, the attributes are added to the artwork element.

<figure>
    <preamble>This is the preamble.</preamble>
    <artwork src='layers.png'
             alt='[picture of layers only]'>
.-----------.
| ASCII art |
`-----------'
</artwork>
    <postamble>This is the postamble.</postamble>
</figure>

In this case, the preamble and postamble elements are kept and an img tag is placed in the HTML output to replace the whole artwork element and its textual drawing, which are ignored.

Here, the attributes are added to the figure element.

<figure src='layers.png'
        alt='[picture of layers and explanation]'>
    <preamble>This is the preamble.</preamble>
    <artwork>
.-----------.
| ASCII art |
`-----------'
</artwork>
    <postamble>This is the postamble.</postamble>
</figure>

In this case, an img tag is placed in the HTML output to replace the whole contents of the figure element (the preamble, artwork, and postamble inner elements and the textual drawing itself) which are ignored.

xml2rfc also recognizes an undocumented align attribute (with possible values left, center, or right) in the figure and artwork elements. It affects the whole content of the targeted element for all types of generated output. Its default is inherited from the parent of its element.



 TOC 

6.2.  Typed-Artwork Interpretation

The artwork element from RFC 2629 supports an optional type attribute. While most possible values are just ignored, including the special case where the attribute is unspecified or just empty, some values are recognized. In particular, type='abnf' can be used if the artwork contains an Augmented Backus-Naur Form (ABNF) syntax specification [3] (Crocker, D. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” October 2005.). As a special extension in its behavior, xml2rfc will attempt to validate the syntax and colorize the HTML output of ABNF, since it is so widely used in RFCs. It does this colorizing by relying on the full parsing it does right before, not on a quick and partial (e.g., line-by-line) pattern-based hack. ABNF is the only artwork type to benefit from this kind of internal support at this time. If the strict rfc-PI directive is activated, invalid ABNF content will cause xml2rfc to abort with an error message. Omitting the type attribute altogether is the obvious way to avoid having this validation and colorizing performed.

For example (to be viewed in HTML):

char-val       =  DQUOTE *(%x20-21 / %x23-7E) DQUOTE
                       ; quoted string of SP and VCHAR
                          without DQUOTE

num-val        =  "%" (bin-val / dec-val / hex-val)

bin-val        =  "b" 1*BIT
                  [ 1*("." 1*BIT) / ("-" 1*BIT) ]
                       ; series of concatenated bit values
                       ; or single ONEOF range

dec-val        =  "d" 1*DIGIT
                  [ 1*("." 1*DIGIT) / ("-" 1*DIGIT) ]

hex-val        =  "x" 1*HEXDIG
                  [ 1*("." 1*HEXDIG) / ("-" 1*HEXDIG) ]

prose-val      =  "<" *(%x20-3D / %x3F-7E) ">"
                       ; bracketed string of SP and VCHAR
                          without angles
                       ; prose description, to be used as
                          last resort

This is from the original RFC on ABNF [2] (Crocker, D., Ed. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” November 1997.), with its minor mistakes in manually folded comment lines purposely left intact, for illustration. Since the result is still valid ABNF (but incorrect with respect to what was intended), this showcases how colorizing might give a human author (or editor or reader) a better chance to spot the three mistakes (and correct them, e.g., with extra semicolons, as has been done in a more recent version [3] (Crocker, D. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” October 2005.) of the ABNF specification). Note that it is the white space characters at the beginning of the subsequent lines (including the commented ones) that conspire to extend the reach of those rules across several lines.



 TOC 

7.  Limitations of xml2rfc



 TOC 

8. References

[1] Bradner, S., “The Internet Standards Process -- Revision 3,” BCP 9, RFC 2026, October 1996 (TXT).
[2] Crocker, D., Ed. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” RFC 2234, November 1997 (TXT, HTML, XML).
[3] Crocker, D. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” RFC 4234, October 2005 (TXT).
[4] Daigle, L. and O. Kolkman, “RFC Streams, Headers, and Boilerplates,” RFC 5741, December 2009.


 TOC 

Appendix A.  Producing the IETF 'Boilerplate'

This section was borrowed from http://greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html#boilerplate.

Various attributes of the <rfc> element plus some child elements of <front> affect the automatically generated parts of the front page, such as the tabular information at the beginning, the "Status Of This Memo", and the "Copyright Notice".

When submitting an Internet Draft, this "boilerplate" is checked by "Idnits" (http://tools.ietf.org/tools/idnits/) for compliance with the current Intellectual Property rules, and thus it is important to set the correct values.

Furthermore, the RFC Production Center uses RFC2629-based tools to generate the final RFC text, so the more accurate the supplied information is, the less additional work is left, and the risk for errors in producing the final (and immutable!) document is reduced.

Note: this only applies to the case when IETF documents are produced. The "private" processing instruction allows to switch off most of the autogeneration logic.



 TOC 

A.1.  The /rfc/@ipr Attribute

As of the time of this writing, this attribute value can take a long list of values. As frequently, this is not the result of a grand plan, but simply for historic reasons. Of these values, only a few are currently in use; all others are supported by the various tools for backwards compatibility with old source files.

Note: some variations of the boilerplate are selected based on the document's date; therefore it is important to specify the "year", "month" and "day" attributes of the <date> element when archiving the XML source of an Internet Draft on the day of submission.

Disclaimer: THIS ONLY PROVIDES IMPLEMENTATION INFORMATION. IF YOU NEED LEGAL ADVICE, PLEASE CONTACT A LAWYER. For further information, refer to http://trustee.ietf.org/docs/IETF-Copyright-FAQ.pdf.

Finally, for the current "Status Of This Memo" text, the submissionType attribute determines whether a statement about "Code Components" is inserted (this is the case for the value "IETF", which also happens to be the default). Other values, such as "independent", suppress this part of the text.



 TOC 

A.1.1.  Current Values: '*trust200902'

The name for these values refers to the "TLP" ("IETF TRUST Legal Provisions Relating to IETF Documents"), on effect February 15, 2009 (see http://trustee.ietf.org/license-info/archive/IETF-Trust-License-Policy-20090215.pdf). Updates to this document were published on September 12, 2009 (TLP 3.0, http://trustee.ietf.org/license-info/archive/IETF-Trust-License-Policy-20090912.pdf) and on December 28, 2009 (TLP 4.0, http://trustee.ietf.org/license-info/archive/IETF-Trust-License-Policy-20091228.pdf), modifying the license for code components. The actual text is located in Section 6 ("Text To Be Included in IETF Documents") of these documents.

The tools will automatically produce the "right" text depending on the document's date information (see above):

TLPURIstarting with publication date
3.0 http://trustee.ietf.org/license-info/archive/IETF-Trust-License-Policy-20090912.pdf 2009-11-01
4.0 http://trustee.ietf.org/license-info/archive/IETF-Trust-License-Policy-20091228.pdf 2010-04-01



 TOC 

A.1.1.1.  trust200902

This should be the default, unless one of the more specific '*trust200902' values is a better fit. It produces the text in Sections 6.a and 6.b of the TLP.



 TOC 

A.1.1.2.  noModificationTrust200902

This produces the additional text from Section 6.c.i of the TLP:

This document may not be modified, and derivative works of it may not be created, except to format it for publication as an RFC or to translate it into languages other than English.



 TOC 

A.1.1.3.  noDerivativesTrust200902

This produces the additional text from Section 6.c.ii of the TLP:

This document may not be modified, and derivative works of it may not be created, and it may not be published except as an Internet-Draft.



 TOC 

A.1.1.4.  pre5378Trust200902

This produces the additional text from Section 6.c.iii of the TLP, frequently called the "pre-5378 escape clause":

This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of this material may not have granted the IETF Trust the right to allow modifications of such material outside the IETF Standards Process. Without obtaining an adequate license from the person(s) controlling the copyright in such materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English.

See Section 4 of http://trustee.ietf.org/docs/IETF-Copyright-FAQ.pdf for further information about when to use this value.

Note: this text appears under "Copyright Notice", unless the document was published before November 2009, in which case it appears under "Status Of This Memo".



 TOC 

A.1.2.  Historic Values



 TOC 

A.1.2.1.  Historic Values: '*trust200811'

The attribute values "trust200811", "noModificationTrust200811" and "noDerivativesTrust200811" are similar to their "trust200902" counterparts, except that they use text specified in http://trustee.ietf.org/license-info/archive/IETF-Trust-License-Policy_11-10-08.pdf.



 TOC 

A.1.2.2.  Historic Values: '*3978'

The attribute values "full3978", "noModification3978" and "noDerivatives3978" are similar to their counterparts above, except that they use text specified in RFC 3978 (March 2005).



 TOC 

A.1.2.3.  Historic Values: '*3667'

The attribute values "full3667", "noModification3667" and "noDerivatives3667" are similar to their counterparts above, except that they use text specified in RFC 3667 (February 2004).



 TOC 

A.1.2.4.  Historic Values: '*2026'

The attribute values "full2026" and "noDerivativeWorks2026" are similar to their counterparts above, except that they use text specified in RFC 2026 (October 1996).

The special value "none" was also used back then, and denied the IETF any rights beyond publication as Internet Draft.



 TOC 

A.2.  The /rfc/@category Attribute

For RFCs, the category determines the "maturity level" (see Section 4 of [1] (Bradner, S., “The Internet Standards Process -- Revision 3,” October 1996.)). The allowed values are "std" for "Standards Track", "bcp" for "BCP", "info" for "Informational", "exp" for "Experimental", and "historic" for - surprise - "Historic".

For Internet Drafts, the category attribute is not needed, but will appear on the front page ("Intended Status"). Supplying this information can be useful, because reviewers may want to know.

Note: the Standards Track consists of "Proposed Standard", "Draft Standards", and "Internet Standard". These do not appear in the boilerplate, thus the category attribute doesn't handle them. However, this information can be useful for validity checkers, and thus rfc2629.xslt supports an extension attribute for that purpose (see http://greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html#ext-rfc2629.rfc for details).



 TOC 

A.3.  The /rfc/@submissionType Attribute

The RFC Editor publishes documents from different "document streams", of which the "IETF stream" of course is the most prominent one. Other streams are the "independent stream" (used for things like administrative information or April 1st RFCs), the "IAB stream" (Internet Architecture Board) and the "IRTF stream" (Internet Research Task Force).

Not surprisingly, the values for the attribute are "IETF" (the default value), "independent", "IAB", and "IRTF".

Historically, this did not affect the final appearance of RFCs, except for subtle differences in Copyright notices. Nowadays (as of [4] (Daigle, L. and O. Kolkman, “RFC Streams, Headers, and Boilerplates,” December 2009.)), the stream name appears in the first line of the front page, and it also affects the text in the "Status Of This Memo" section.

For current documents, setting submissionType attribute will have the following effect:



 TOC 

A.4.  The /rfc/@consensus Attribute

For some of the publication streams (see Appendix A.3 (The /rfc/@submissionType Attribute)), the "Status Of This Memo" section depends on whether there was a consensus to publish (again, see Section 3.2.2 of [4] (Daigle, L. and O. Kolkman, “RFC Streams, Headers, and Boilerplates,” December 2009.)).

The consensus attribute ("yes"/"no", defaulting to "yes") can be used to supply this information. The effect for the various streams is:



 TOC 

A.5.  The /rfc/@number Attribute

For RFCs, this attribute supplies the RFC number.



 TOC 

A.6.  The /rfc/@docName Attribute

For Internet Drafts, this specifies the draft name (which appears below the title). The file extension is not part of the draft, so in general it should end with the current draft number ("-", plus two digits).

Note: "Idnits" (http://tools.ietf.org/tools/idnits/) checks the in-document draft name for consistency with the filename of the submitted document.



 TOC 

A.7.  The /rfc/@obsoletes Attribute

The RFC Editor maintains a database (http://www.rfc-editor.org/rfc.html) of all RFCs, including information about which one obsoletes which. Upon publication of an RFC, this database is updated from the data on the front page.

This attribute takes a list of comma-separated RFC numbers. Do not put the string "RFC" here.



 TOC 

A.8.  The /rfc/@updates Attribute

This is like obsoletes, but for the "updates" relation.



 TOC 

Appendix B.  MacOS 9 Installation (courtesy of Ned Freed)

  1. Install Tcl/Tk 8.3.4
  2. When you performed Step 1, a folder in your Extensions folder called Tool Command Language was created. Create a new folder under Extensions, with any name you like.
  3. Drag the file xml2rfc.tcl onto the Drag & Drop Tclets application that was installed in Step 1.
  4. When asked for an appropriate wish stub, select Wish 8.3.4.
  5. The Drag & Drop Tclets application will write out an executable version of xml2rfc.


 TOC 

Appendix C.  rfc2629.xslt (courtesy of Julian Reschke)

The file rfc2629.xslt can be used with an XSLT-capable formatter (e.g., Saxon, Xalan, xsltproc, and most browsers) to produce HTML. A word of warning though: the XSLT script only supports a limited subset of the processing instruction directives discussed earlier (Processing Instructions). The latest version (and full distribution ZIP file) can be downloaded from the original site which also hosts its documentation.



 TOC 

Appendix D.  MS-Windows/Cygwin Installation (courtesy of Joe Touch)

  1. install Cygwin: follow instructions at the Cygwin website (also visit the Cygwin pages on the Tcl Wiki), make sure to select tcltk in Libs
  2. place a copy of xml2rfc files on a local drive, e.g., in C:\xml2rfc
  3. place a copy of bibxml* files on a local drive, e.g., in C:\xmlbib\
  4. edit .xml2rfc.rc to indicate the bibxml* library path, e.g., as per Step 3, change ~/rfca/bibxml/* to /cygdrive/c/xmlbib/*
  5. run xml2rfc as follows: tclsh /cygdrive/c/xml2rfc/xml2rfc.tcl



 TOC 

Appendix E.  A Special Thanks

A special thanks to Charles Levert for the v1.29 release, which includes many internal improvements made to the rendering engines.



 TOC 

Appendix F.  Copyrights

Copyright © 2003–2011 Marshall T. Rose

Hold harmless the author, and any lawful use is allowed.



 TOC 

Index

P 
 private PI pseudo-attribute
 Processing Instruction pseudo attributes
   private


 TOC 

Authors' Addresses

  Marshall T. Rose
  Dover Beach Consulting, Inc.
  POB 255268
  Sacramento, CA 95865-5268
  US
Phone:  +1 916 483 8878
Email:  mrose@dbc.mtview.ca.us
  
  Bill Fenner
  Arista Networks, Inc.
  275 Middlefield Rd, Suite 50
  Menlo Park, CA 94025
  US
Phone:  +1 650 924-2455
Email:  fenner@gmail.com
  
  Charles Levert
  Montréal, QC
  Canada
Email:  charles.levert@gmail.com
  
  Tony Hansen
  AT&T Labs
  Middletown, NJ
  USA
Email:  tony+xml2rfc@maillennium.att.com
  
  Julian F. Reschke
  greenbytes GmbH
  Hafenweg 16
  Muenster, NW 48155
  Germany
Email:  julian.reschke@greenbytes.de
URI:  http://greenbytes.de/tech/webdav/