[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
XML template [RE: New ID-Checklist to replace ID-nits (fwd)
On Thu, 27 May 2004, Wijnen, Bert (Bert) wrote:
> > An actual ASCII boiler-plate might save people some time by gathering
> > all the required statements in one place.
>
> I think Pekka was providing that in an XML2RFC example file.
> I believe Henrik (but I may have the source wrong) also posted
> an ASCII file recently.
>
> Hope this helps, Bert
For what it's worth, here's an XML draft template people can use to
get started on writing documents. You can push it through the
interface at xml.resource.org to get the text version for boilerplates
etc. as well.
--
Pekka Savola "You each name yourselves king, yet the
Netcore Oy kingdom bleeds."
Systems. Networks. Security. -- George R.R. Martin: A Clash of Kings
la <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<!-- may be omitted for very short documents -->
<?rfc toc="yes"?>
<?rfc sortrefs="yes"?>
<!-- these two save paper: start new sections from the same page etc. -->
<?rfc compact="yes"?> <?rfc subcompact="no"?>
<!-- other categories: bcp, exp, historic, std -->
<rfc ipr="full3667" category="info" docName="draft-savola-xml2rfc-template-00.txt" updates="1,2" obsoletes="3">
<front>
<title abbrev="Template Shortname for Headers">An XML2RFC Template</title>
<!-- add 'role="editor"' below for the editors if requiring designation -->
<author fullname="Pekka Savola" initials="P." surname="Savola">
<!-- abbrev not needed but can be used for the header if full company name is too long -->
<organization abbrev="CSC/FUNET">CSC - Scientific Computing Ltd.</organization>
<address>
<!--
if you want to omit the postal information, just use a <postal/>
.. / at the end also acts as a closing tag
-->
<postal>
<street/>
<city>Espoo</city>
<!--
<region>MN</region>
<code>11111</code>
-->
<country>Finland</country>
</postal>
<email> psavola at funet.fi </email>
<!--
<tel>+1-555-911-9112</tel>
<facsimile>+1-555-911-9111</facsimile>
<uri>http://127.0.0.1/</uri>
-->
</address>
</author>
<date year="2004"/> <!-- month="May" is no longer necessary -->
<!-- not used for anything ? -->
<area>Operations & Management</area>
<!-- WG name at the upperleft corner of the doc, IETF fine for individual submissions -->
<workgroup>Internet Engineering Task Force</workgroup>
<abstract>
<t>This is an abstract abstract. Remember, don't add references here.</t>
</abstract>
</front>
<middle>
<note title="Foreword">
<t>SEE RFC2629(bis) FOR MORE INFORMATION:
http://xml.resource.org/public/rfc/html/rfc2629.html and "bis":
http://xml.resource.org/authoring/draft-mrose-writing-rfcs.html. Also see
http://xml.resource.org/authoring/README.html for for 'rfc' option
strings.</t>
<t>Please also remember to check out
http://www.ietf.org/ID-Checklist.html for issues to note when writing
drafts.</t>
<t>Remember, you don't need to have any other tools than a 'notepad'
or your favourite editor to write xml2rfc drafts. You can use the web
interface at http://xml.resource.org for processing. The benefit of using
xml editors is mostly catching those missing tags which the processor will
warn you about, but you don't need to worry about the editors when getting
started.</t>
<t>This template is not meant to be a conclusive list of everything,
but summarize the often-needed basic features to get one started.</t>
</note>
<section title="Introduction">
<t>Now you can have a bit more lengthier text here.</t>
<t>Let's refer to a couple of documents: <xref
target="I-D.ietf-v6ops-3gpp-analysis"/> and <xref
target="RFC2661">L2TP</xref>. For text generation, these look equivalent,
but the latter looks a bit neater in the HTML representation.</t>
<t>You might also add a note about the usage of RFC2119 keywords here..</t>
<t>You can cross-reference the sections in a stable manner; <xref
target="sect2"/></t>.
</section>
<section anchor="sect2" title="Sections go under here..">
<t>There are multiple list styles: 'symbols', 'letters', 'numbers',
'hanging', 'format', etc.</t>
<list style="symbols">
<t>First bullet</t>
<t>Second bullet</t>
</list>
<t>One can draw fancy diagrams as well; remember to ensure that they
don't exceed 72 chars/line.</t>
<!-- you can specify how many contiguous lines you need (w/o linebreak you need -->
<?rfc needLines="5" ?>
<figure anchor="xml_happy">
<artwork>
<![CDATA[
+-----------------------+
| Use XML, be Happy :-) |
|_______________________|
]]>
</artwork>
</figure>
<t>Note that including a CDATA you don't need to escape most special characters
you might otherwise have to.</t>
<section title="A Subsection">
<t>There can be a lot of subsections. By default 3 levels of
nesting show in ToC but that can be adjusted.</t>
</section>
</section>
<section title="Decrypting XML2RFC Parsing errors">
<t>The most common form of xml2rfc parsing erros are those where a
closing tag has been expected to be present before a new kind of tag is
specified. In the example below, Introduction section's last paragraph was
missing the closing t-element. The rest of the error messages can be rather
easily understood as well by reading it carefully and examining the context.
The reason is typically a missing tag somewhere.</t>
<figure>
<artwork>
<![CDATA[
======8<=========
end tag "section" does not match open element "t" around line 65
Context:
<rfc ipr="full3667" category="info" docName="draft-savola-xml2rfc-template-00.txt" updates="1,2" obsoletes="3">
<middle>
<section title="Introduction">
<t>
=======8<========
]]>
</artwork>
</figure>
</section>
<section title="Acknowledgements">
<t>Remember, it's important to acknowledge people who have
contributed to the work.</t>
</section>
<!-- possibly a 'Contributors' section ... -->
<section title="IANA Considerations">
<t>This memo includes no request to IANA.</t>
<t>(It's good to have an explicit note because otherwise IANA wastes
cycles trying to figure out if something is needed..)</t>
</section>
<section title="Security Considerations">
<t>Remember to consider security from the start..</t>
</section>
</middle>
<back>
<!-- references split to informative and normative -->
<references title="Normative References">
<?rfc include="reference.RFC.2661" ?>
</references>
<references title="Informative References">
<?rfc include="reference.I-D.ietf-v6ops-3gpp-analysis" ?>
</references>
<section anchor="appendix" title="Redundant stuff">
<t>You can add appendices just as regular sections, the only
difference is that they go under "back" element..</t>
</section>
</back>
</rfc>