Index of /authoring/xml2rfc-1.29rc2

[ICO]NameLast modifiedSizeDescription

[DIR]Parent Directory  -  
[   ]LICENSE26-Jan-2011 11:28 1.4K 
[TXT]README.html26-Jan-2011 11:28 27K 
[TXT]README.txt26-Jan-2011 11:28 21K 
[   ]README.xml26-Jan-2011 11:28 17K 
[DIR]contrib/23-Mar-2015 11:38 -  
[TXT]draft-mrose-writing-rfcs.html26-Jan-2011 11:28 73K 
[TXT]draft-mrose-writing-rfcs.txt26-Jan-2011 11:28 60K 
[   ]rfc2629.dtd26-Jan-2011 11:28 7.4K 
[TXT]rfc2629.html26-Jan-2011 11:28 57K 
[   ]rfc2629.rnc26-Jan-2011 11:28 8.3K 
[TXT]rfc2629.txt26-Jan-2011 11:28 48K 
[   ]rfc2629.xml26-Jan-2011 11:28 45K 
[   ]rfc2629.xsd26-Jan-2011 11:28 16K 
[   ]rfc2629xslt.zip26-Jan-2011 11:28 181K 
[TXT]sample.txt26-Jan-2011 11:28 5.1K 
[   ]sample.xml26-Jan-2011 11:28 1.3K 
[IMG]xml2rfc-win.png26-Jan-2011 11:28 3.9K 
[TXT]xml2rfc.tcl26-Jan-2011 11:28 333K 
[TXT]xml2sgml.tcl26-Jan-2011 11:28 105K 

The README file: xml2rfc v1.29rc2
The README fileM. Rose
 Dover Beach Consulting, Inc.
 January 2005

xml2rfc v1.29rc2

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.  Additions to RFC 2629
6.  Limitations of xml2rfc
7.  References
§  Author's Address
A.  MacOS 9 Installation (courtesy of Ned Freed)
B.  rfc2629.xslt (courtesy of Julian Reschke)
C.  MS-Windows XP/Cygwin Installation (courtesy of Joe Touch)
D.  A Special Thanks
E.  Copyrights


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.


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


3. Testing

Now test your installation.

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

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 four lines:

    invoke as "xml2rfc   inputfile outputfile"
           or "xml2txt   inputfile"
           or "xml2html  inputfile"
           or "xml2nroff inputfile"


4. Next steps

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

4.1 Processing Instructions

A processing instruction is a directive 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 PIs in your input file!

4.1.1 Option Settings

The list of valid keywords are:

keyword default meaning
autobreaks yes automatically force page breaks to avoid widows and orphans (not perfect)
background "" when producing an 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 no when producing a txt/nroff file, try to conserve vertical whitespace
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
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
needLines n/a an integer hint indicating how many contiguous lines are needed at this point in the output
private "" produce a private memo rather than an RFC or Internet-Draft
slides no when producing an 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 no use anchors rather than numbers for references
toc no generate a table-of-contents
tocdepth 3 if toc is "yes", then this determines the depth of the table-of-contents
tocindent no if toc is "yes", then setting this to "yes" will indent subsections in the table-of-contents
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 an 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 and typeout PIs, you normally put all of these processing instructions at the beginning of the document (right after the XML declaration).

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 envariable isn't set, the directory containing the file that contains the include-file directive is used.)

You can also have xml2rfc set this envariable 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.


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

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.

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

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>
| ASCII art |
    <postamble>This is the postamble.</postamble>

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.


6. Limitations of xml2rfc


7. References

[1] Bradner, S., “The Internet Standards Process -- Revision 3,” BCP 9, RFC 2026, October 1996.


Author's Address

  Marshall T. Rose
  Dover Beach Consulting, Inc.
  POB 255268
  Sacramento, CA 95865-5268
Phone:  +1 916 483 8878


Appendix A. 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.


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

The file rfc2629.xslt can be used with an XSLT-capable formatter (i.e., MSIE6) to produce HTML. A word of warning though: the XSLT script doesn't support the processing instructions discussed earlier (Processing Instructions).


Appendix C. MS-Windows XP/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 NOTE: for xml2rfc-1.26 and earlier, see NOTE below.
  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

NOTE: for xml2rfc-1.26 and earlier ONLY, add an additional modification in Step 3:

Patch .xml2rfc.rc (xml2rfc-1.26 and earlier). The purpose of the patch is to append library names in a format compatible with the OS; on MS-Windows XP, this replaces the Cygwin's / with MS-Windows' \.

--- .xml2rfc.rc.orig    Thu Jul 24 13:58:00 2003
+++ .xml2rfc.rc    Wed Oct 20 10:59:02 2004
@@ -9,7 +9,8 @@
 if {[catch { set env(XML_LIBRARY) } library]} {
     set library ""
     foreach bibxmlD [lsort -dictionary [glob -nocomplain ~/rfcs/bibxml/*]] {
-        append library $sep$bibxmlD
+        set natbibD [file nativename $bibxmlD]
+        append library $sep$natbibD


Appendix D. A Special Thanks

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


Appendix E. Copyrights

Copyright © 2003–2005 Marshall T. Rose

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