<?xml version="1.0"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">

<?rfc compact="yes"?>
<?rfc private="The README file"?>
<?rfc header="README"?>

<rfc>
<front>
<title>xml2rfc</title>

<author initials="M.T." surname="Rose" fullname="Marshall T. Rose">
<organization>Invisible Worlds, Inc.</organization>

<address>
<postal>
<street>660 York Street</street>
<city>San Francisco</city> <region>CA</region> <code>94110</code>
<country>US</country>
</postal>

<phone>+1 415 695 3975</phone>
<email>mrose@not.invisible.net</email>
<uri>http://invisible.net/</uri>
</address>
</author>

<date month="June" year="1999"/>
</front>

<middle>

<section title="Introduction">
<t>This is a package to convert memos written in XML to the RFC format.</t>

<t>If you don't want to install any software,
you can use the
<eref target="http://memory.palace.org/author.html">web-based service</eref>.</t>
</section>

<section title="Requirements">

<section title="Tcl/Tk version 8.0">
<t>You need to have Tcl/Tk version 8.0 running on your system.
Tcl is a scripting language,
Tk is Tcl with support for your windowing system.</t>
    
<t>To get a source or binary distribution for your system,
go to the
<eref target="http://www.scriptics.com/software/8.0.html">Scriptics
website</eref>
and install it.
If you get the binary distribution,
this is pretty simple.</t>
    
<figure>
<preamble>Of course,
you may already have Tcl version 8.0.
To find out,
try typing this command from the shell
(including the "MS-DOS Prompt"):</preamble>
<artwork>
    % tclsh80
</artwork>
<postamble>If the program launches,
you're good to go with Tcl version 8.0.</postamble>
</figure>

<figure>
<preamble>If you are running under a windowing system (e.g., X or Windows),
you can also try:</preamble>
<artwork>
    % wish80
</artwork>
<postamble>If a new window comes up along with a "Console" window,
then you're good to go with Tk version 8.0.</postamble>
</figure>
</section>

<section title="TclXML version 1.1.1">
<t>You need to also have TclXML version 1.1.1 running on your system.
TclXML is a Tcl package that parses XML.</t>
    
<t>We've included a copy of TclXML in this release,
you can also look in
<eref target="http://www.zveno.com/zm.cgi/in-tclxml/">the TclXML
site</eref>.</t>
    
<figure>
<preamble>For example,
on Unix,
you'd probably put the files somewhere under</preamble>
<artwork>
    /usr/local/lib/tcl/

or 

    C:\Program Files\Tcl\lib\tcl8.0\TclXML-1.0\
</artwork>
<postamble>depending on whether you're on UNIX or Windows.</postamble>
</figure>
</section>
</section>

<section title="Testing">
<t>Now test your installation.</t>
    
<section title="Testing under a windowing system">
<figure>
<preamble>Type this command from the shell:</preamble>
<artwork>
    % xml2rfc.tcl
</artwork>
</figure>

<figure>
<preamble>A new window should come up that looks like this:</preamble>
<artwork>
    +------------------------------------------------------------+
    |                     Convert XML to RFC                     |
    |                                                            |
    |  Select input file: ____________________________  [Browse] |
    |                                                            |
    | Select output file: ____________________________  [Browse] |
    |                                                            |    
    |               [Convert]               [Quit]               |
    |                                                            |
    +------------------------------------------------------------+
</artwork>
<postamble>Fill-in the blanks and click on [Convert].</postamble>
</figure>
</section>
    
<section title="Testing without a windowing system">
<figure>
<preamble>Type this command from the shell:</preamble>
<artwork>
    % tclsh80
</artwork>
</figure>

<figure>
<preamble>If the program launches, type this command to it:</preamble>
<artwork>
    % source xml2rfc.tcl
</artwork>
</figure>

<figure>
<preamble>and you should see these three lines:</preamble>
<artwork>
    invoke as "xml2rfc inputfile outputfile"
           or "xml2txt inputfile"
           or "xml2html inputfile"
</artwork>
</figure>
</section>
</section>

<section title="Next steps">
<t>Read either <xref target="RFC2629">rfc2629.txt</xref> or 
<eref target="rfc2629.html">rfc2629.html</eref>.
In particular,
Section 3 has some good information.</t>

<section title="xml2rfc-specific Processing Instructions">

<figure>
<preamble>A "processing instruction" is a directive to an XML
application.
If you want to give directives to xml2rfc,
the PIs look like this:</preamble>
<artwork>
    &lt;?rfc keyword="value"?>
</artwork>
</figure>

<figure>
<preamble>The list of valid keywords are:</preamble>
<artwork>
    keyword     default     meaning
    =======     =======     =======
    compact     no          when producing a .txt file, try to
                            conserve vertical whitespace
    
    toc         no          generate a table-of-contents

    private     ""          produce a private memo rather than
                            an RFC or Internet-Draft.

    header      ""          override the leftmost header string

    footer      ""          override the center footer string

    sortrefs    no          sort references

    symrefs     no          use anchors rather than numbers for
                            references

    background  ""          when producing an .html file, use this
                            image
</artwork>
<postamble>Remember,
that as with everything else in XML,
keywords and values are case-sensitive.</postamble>
</figure>

</section>

<section title="xml2rfc-specific Limitations">
<t>
<list style="bullets">
<t>The "figure" element's "title" attribute is ignored.</t>
    
<t>The "xref" element's "pageno" attribute is ignored.</t>
</list>
</t>
</section>
</section>

</middle>

<back>
<references>

<reference anchor="RFC2629">
<front>
<title>Writing I-Ds and RFCs using XML</title>

<author initials="M.T." surname="Rose" fullname="Marshall T. Rose">
<organization>Invisible Worlds, Inc.</organization>

<address>
<postal>
<street>660 York Street</street>
<city>San Francisco</city> <region>CA</region> <code>94110</code>
<country>US</country>
</postal>

<phone>+1 415 695 3975</phone>
<email>mrose@not.invisible.net</email>
<uri>http://invisible.net/</uri>
</address>
</author>
    
<date month="June" year="1999"/>
</front>

<seriesInfo name="RFC" value="2629" />
</reference>

</references>

</back>
</rfc>
