Network Working Group                                         P. Hoffman
Internet-Draft                                            VPN Consortium
Intended status: Informational                                 T. Hansen
Expires: November 7, 2015                              AT&T Laboratories
                                                             May 6, 2015


         Examples of the 'XML2RFC' Version 2 and 3 Vocabularies
                    draft-hoffman-rfcexamples-03

Abstract

   This document gives examples of use of the "XML2RFC" vocabulary.  The
   examples cover both version 2 and version 3.  The purposes of this
   draft is to give developers of tools that process v2 and/or v3
   documents a corpus to test against.

Editorial Note (To be removed by RFC Editor)

   Discussion of this draft takes place on the rfc-interest mailing list
   (rfc-interest@rfc-editor.org), which has its home page at [1].

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 November 7, 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



Hoffman & Hansen        Expires November 7, 2015                [Page 1]


Internet-Draft              RFC XML Examples                    May 2015


   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.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Example of a v2 Document  . . . . . . . . . . . . . . . . . .   2
   3.  Example of a v3 Document  . . . . . . . . . . . . . . . . . .   9
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .  16
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  17
   6.  Acknowledgments . . . . . . . . . . . . . . . . . . . . . . .  17
   7.  Normative References  . . . . . . . . . . . . . . . . . . . .  17
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  17

1.  Introduction

   This document gives examples of use of the "XML2RFC" vocabulary.  The
   examples cover both version 2 [XML2RFCv2] and version 3 [XML2RFCv3].
   The purpose of this document is to help developers of tools that
   process v2 and/or v3 documents to see examples of the documents.

   Earlier versions of this document said that it was to help people
   with v2 documents transition to v3.  The authors have backed off from
   that goal.  Instead, we point out that the changes from v2 to v3 are
   listed in detail in Section 1.2 of [XML2RFCv3].  Also, we expect that
   there will be additional documents created later describing the
   v2-to-v3 conversion, as well as tools that will do as much of the
   conversion as possible.

   This is meant to be a short-lived document.  It is not expected that
   this document will be published as an RFC.

2.  Example of a v2 Document

   The following is a v2 document that has all the elements that are
   needed for typical Internet-Drafts.

   <?xml version="1.0" encoding="US-ASCII"?>
   <!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
   <!ENTITY RFC2119 SYSTEM
     "http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml">
   ]>

   <?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
   <?rfc strict="yes" ?>



Hoffman & Hansen        Expires November 7, 2015                [Page 2]


Internet-Draft              RFC XML Examples                    May 2015


   <rfc
     category="std"
     docName="draft-example-of-xml-00"
     ipr="trust200902"
     consensus="no"
     submissionType="IETF"
     updates="1234, 5678"
     xml:lang="en"
   >

   <front>
   <title abbrev="XML Example">
   An Example of Using XML for an Internet Draft
   </title>

   <author fullname="Chris Smith" initials="C." surname="Smith">
   <organization abbrev="EC">ExampleCorp</organization>
   <address>
   <postal>
   <street>123 Exemplar Way</street>
   <city>Anytown</city>
   <region>California</region>
   <code>95060</code>
   <country>US</country>
   </postal>
   <phone>+1 123-456-7890</phone>
   <facsimile>+1 123-456-7890</facsimile>
   <email>chrissmith@example.com</email>
   <uri>http://www.example.com/corporate/</uri>
   </address>
   </author>

   <!-- The following author has no organization and no postal or
        phone information. -->
   <author fullname="Kim Jones" initials="K." surname="Jones">
   <organization/>
   <address>
   <email>jk@lmn.op</email>
   </address>
   </author>

   <date year="2014" month="September"/>

   <area>General</area>
   <workgroup>Imaginary WG</workgroup>
   <keyword>XML</keyword>
   <keyword>Imagination</keyword>




Hoffman & Hansen        Expires November 7, 2015                [Page 3]


Internet-Draft              RFC XML Examples                    May 2015


   <abstract>
   <t>This is an example of an abstract. It is a short paragraph that
   gives an overview of the document in order to help the
   reader determine whether or not they are interested in reading
   further.</t>
   </abstract>

   <note tile="Disclaimer">
   <t>This isn't a real RFC, just an example.</t>
   </note>

   </front>

   <middle>

   <section anchor="intro" title="Introduction">

   <t>This is the first paragraph of the introduction to this
   document. This introduction is probably much shorter than it would
   be for a real Internet Draft.</t>

   <t>Something to note about this paragraph is that it has a
   pointer to <xref target="protocol"/>, and one to
   <xref target="haiku"/>, both of which appear later in the
   document.</t>

   <iref item="Introduction" subitem="verbiage" primary="true"/>

   <!-- This is a comment. Comments in the XML do not appear in the
   output formats. -->

   <section title="Terminology">

   <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
   NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
   in this document are to be interpreted as described in
   <xref target="RFC2119"/>.</t>

   </section>

   </section>

   <section anchor="protocol" title="The Protocol Being Described">

   <t>This is a reference to <xref target="RFC6949"/>.
   Actually, the reference itself is not all that interesting, but the
   way that the reference is incorporated is. Note that the inclusion
   of RFC 2119 was done at the top of the XML, while the information



Hoffman & Hansen        Expires November 7, 2015                [Page 4]


Internet-Draft              RFC XML Examples                    May 2015


   for RFC 6949 is done directly in the references section.</t>

   <t>The <eref target="http://www.ietf.org">IETF web site</eref> is
   <spanx style="emph">quite</spanx>
   <spanx style="strong">nice</spanx>,
   <spanx style="verb">isn't it</spanx>?
   Unlike other web sites, it doesn't use
   <vspace blankLines="2" />gratuitous vertical space.</t>

   </section>

   <section title="Basic Lists">

   <t>Bulleted lists are good for items that
   are not ordered:

   <list style="symbols">

   <t>This is the first item.</t>

   <t>This is the second item. Here comes a sub-list:

   <list style="symbols">

   <t>This is the first sub-item.</t>

   <t>This is the second sub-item<vspace/>
   and some more detail on the second sub-item.</t>

   </list></t>

   <t>This is the item after the sub-list.</t>

   </list></t>

   <t>Numbered lists are good for items that are ordered:

   <list style="numbers">

   <t>This is the first item.</t>

   <t>This is the second item. Here comes a sub-list, but
   with letters:

   <list style="letters">

   <t>This is the first sub-item.</t>




Hoffman & Hansen        Expires November 7, 2015                [Page 5]


Internet-Draft              RFC XML Examples                    May 2015


   <t>This is the second sub-item</t>

   </list></t>

   <t>This is the item after the sub-list.</t>

   </list></t>

   <t>And an example of hanging indent.

   <list style="hanging" hangIndent="15">

   <t hangText="Trees">These are bigger plants</t>

   <t hangText="Lichen">These are smaller plants</t>

   </list></t>

   <t>And the always-interesting "format" for lists.

   <list style="format --%d--">

   <t>An element that gets a funny bullet.</t>

   </list></t>

   </section>

   <section title="Figures">

   <t>The following is a figure with a caption.
   Also, it uses the ampersand (&amp;) and less than
   (&lt;) characters in the example text.</t>

   <figure title="This could be haiku" anchor="haiku">
   <artwork type="haiku" align="left">
      The ampersand (&amp;) and
      less than (&lt;) are two characters
      that need escaping.
   </artwork>
   </figure>

   <t>Here are two short figures with no titles and with
   odd alignment.</t>

   <figure><artwork align="center">
   This might appear in the center.
   </artwork></figure>



Hoffman & Hansen        Expires November 7, 2015                [Page 6]


Internet-Draft              RFC XML Examples                    May 2015


   <figure><artwork align="right">
   This might appear right-aligned.
   </artwork></figure>

   <t>Here is a figure that is actually pulled from somewhere else.
   <cref source="cs" anchor="rememberme">
   Remember to check whether that file still exists.</cref></t>

   <figure><artwork
     src="http://www.example.com/~employees/chrissmith/artwork.txt" />
   </figure>

   </section>

   <section title="Tables">

   <t>The following is a table example.</t>

   <texttable title="The Noble Gases">
     <preamble>These are sometimes called "inert" gasses.</preamble>
     <ttcol>Name</ttcol>
     <ttcol align="center" width="50%">Symbol</ttcol>
     <ttcol align="center">Atomic Number</ttcol>

     <c>Helium</c>
     <c>He</c>
     <c>2</c>

     <c>Neon</c>
     <c>Ne</c>
     <c>10</c>

     <c>Argon</c>
     <c>Ar</c>
     <c>18</c>

     <c>Krypton</c>
     <c>Kr</c>
     <c>36</c>

     <c>Xenon</c>
     <c>Xe</c>
     <c>54</c>

     <c>Radon</c>
     <c>Rn</c>
     <c>86</c>




Hoffman & Hansen        Expires November 7, 2015                [Page 7]


Internet-Draft              RFC XML Examples                    May 2015


     <postamble>Source: Chemistry 101</postamble>
   </texttable>

   <t>The following is a right-aligned table with "full" (but not "all")
   lines between cells.</t>

   <texttable align="right" style="full">
     <ttcol>Time</ttcol>
     <ttcol align="right">Mood</ttcol>

     <c>Morning</c>
     <c>Happy!</c>

     <c>Afternoon</c>
     <c>Happy!</c>

     <c>Evening</c>
     <c>Somber</c>

   </texttable>

   </section>

   <section anchor="IANA" title="IANA Considerations">

   <t>None.</t>

   </section>

   <section anchor="Security" title="Security Considerations">

   <t>There are no security considerations for an imaginary
   Internet Draft.</t>

   </section>

   <section anchor="Acknowledgements" title="Acknowledgements">

   <t>Some of the things included in this draft came from
   Elwyn Davies' templates.</t>

   </section>

   </middle>

   <back>

   <references title="Normative References">



Hoffman & Hansen        Expires November 7, 2015                [Page 8]


Internet-Draft              RFC XML Examples                    May 2015


   &RFC2119;

   </references>

   <references title="Informative References">

   <reference anchor="RFC6949">
   <front>
   <title>RFC Series Format Requirements and Future Development</title>
   <author initials="H." surname="Flanagan" fullname="H. Flanagan">
   <organization/></author>
   <author initials="N." surname="Brownlee" fullname="N. Brownlee">
   <organization/></author>
   <date year="2013" month="May"/>
   </front>
   <seriesInfo name="RFC" value="6949"/>
   <annotation>This is a primary reference work.</annotation>
   </reference>

   <reference anchor="RED"
   target="http://www.aciri.org/floyd/papers/early.pdf">
   <front>
   <title>Random Early Detection (RED) gateways for Congestion
   Avoidance</title>
   <author fullname="Sally Floyd" initials="S" surname="Floyd">
   <organization>LBL</organization>
   </author>
   <author fullname="Van Jacobson" initials="V" surname="Jacobson">
   <organization>LBL</organization>
   </author>
   <date month="August" year="1993"/>
   </front>
   <seriesInfo name="IEEE/ACM Transactions on Networking"
   value="1(4) 397--413"/>
   <format target="http://www.aciri.org/floyd/papers/early.pdf"
   octets="318703" type="PDF"/>
   </reference>

   </references>

   </back>
   </rfc>

3.  Example of a v3 Document

   The following is a v3 document that has all the elements that are
   needed for typical Internet-Drafts.  It was converted from the
   example in Section 2.



Hoffman & Hansen        Expires November 7, 2015                [Page 9]


Internet-Draft              RFC XML Examples                    May 2015


<?xml version='1.0' encoding='US-ASCII'?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd'>

<rfc ipr='trust200902' consensus='false' submissionType='IETF'
  updates='1234, 5678' xml:lang='en'
  xmlns:xi="http://www.w3.org/2001/XInclude">

<front><seriesInfo name='Internet-Draft'
  value='draft-example-of-xml-00'/><seriesInfo name='std'
  value=''/>
<title abbrev='XML Example'>
An Example of Using XML for an Internet Draft
</title>

<author fullname='Chris Smith' initials='C.' surname='Smith'>
<organization abbrev='EC'>ExampleCorp</organization>
<address>
<postal>
<street>123 Exemplar Way</street>
<city>Anytown</city>
<region>California</region>
<code>95060</code>
<country>US</country>
</postal>
<phone>+1 123-456-7890</phone>
+1 123-456-7890
<email>chrissmith@example.com</email>
<uri>http://www.example.com/corporate/</uri>
</address>
</author>

<!-- The following author has no organization and no postal or
     phone information. -->
<author fullname='Kim Jones' initials='K.' surname='Jones'>
<organization/>
<address>
<email>jk@lmn.op</email>
</address>
</author>

<date year='2014' month='September'/>

<area>General</area>
<workgroup>Imaginary WG</workgroup>
<keyword>XML</keyword>
<keyword>Imagination</keyword>

<abstract>



Hoffman & Hansen        Expires November 7, 2015               [Page 10]


Internet-Draft              RFC XML Examples                    May 2015


<t>This is an example of an abstract. It is a short paragraph that
gives an overview of the document in order to help the
reader determine whether or not they are interested in reading
further.</t>
</abstract>

<note tile='Disclaimer'>
<t>This isn't a real RFC, just an example.</t>
</note>

</front>

<middle>

<section anchor='intro'><name>Introduction</name>

<t>This is the first paragraph of the introduction to this
document. This introduction is probably much shorter than it would
be for a real Internet Draft.</t>

<t>Something to note about this paragraph is that it has a
pointer to <xref target='protocol'/>, and one to
<xref target='haiku'/>, both of which appear later in the
document.</t>

<iref item='Introduction' subitem='verbiage' primary='true'/>

<!-- This is a comment. Comments in the XML do not appear in the
output formats. -->

<section><name>Terminology</name>

<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
in this document are to be interpreted as described in
<xref target='RFC2119'/>.</t>

</section>

</section>

<section anchor='protocol'><name>The Protocol Being Described</name>

<t>This is a reference to <xref target='RFC6949'/>.
Actually, the reference itself is not all that interesting, but the
way that the reference is incorporated is. Note that the inclusion
of RFC 2119 was done at the top of the XML, while the information
for RFC 6949 is done directly in the references section.</t>



Hoffman & Hansen        Expires November 7, 2015               [Page 11]


Internet-Draft              RFC XML Examples                    May 2015


<t>The <eref target='http://www.ietf.org'>IETF web site</eref> is
<em>quite</em>
<strong>nice</strong>,
<tt>isn't it</tt>?
Unlike other web sites, it doesn't use
gratuitous vertical space.</t>

</section>

<section><name>Basic Lists</name>

<t>Bulleted lists are good for items that
are not ordered:

</t><ul>

<li>This is the first item.</li>

<li>This is the second item. Here comes a sub-list:

</t><ul>

<li>This is the first sub-item.</li>

<li><t>This is the second sub-item</t><t>
and some more detail on the second sub-item.</t></li>

</ul><t></li>

<li>This is the item after the sub-list.</li>

</ul><t></t>

<t>Numbered lists are good for items that are ordered:

</t><ol style='1'>

<li>This is the first item.</li>

<li>This is the second item. Here comes a sub-list, but
with letters:

</t><ol style='a'>

<li>This is the first sub-item.</li>

<li>This is the second sub-item</li>




Hoffman & Hansen        Expires November 7, 2015               [Page 12]


Internet-Draft              RFC XML Examples                    May 2015


</ol><t></li>

<li>This is the item after the sub-list.</li>

</ol><t></t>

<t>And an example of hanging indent.

</t><dl hanging='true'>

<dt>Trees</dt><dd>These are bigger plants</dd>

<dt>Lichen</dt><dd>These are smaller plants</dd>

</dl><t></t>

<t>And the always-interesting "format" for lists.

</t><ol style='--%d--'>

<li>An element that gets a funny bullet.</li>

</ol><t></t>

</section>

<section><name>Figures</name>

<t>The following is a figure with a caption.
Also, it uses the ampersand (&amp;) and less than
(&lt;) characters in the example text.</t>

<figure anchor='haiku'><name>This could be haiku</name>
<artwork type='haiku' align='left'>
   The ampersand (&amp;) and
   less than (&lt;) are two characters
   that need escaping.
</artwork>
</figure>

<t>Here are two short figures with no titles and with
odd alignment.</t>

<figure><artwork align='center'>
This might appear in the center.
</artwork></figure>

<figure><artwork align='right'>



Hoffman & Hansen        Expires November 7, 2015               [Page 13]


Internet-Draft              RFC XML Examples                    May 2015


This might appear right-aligned.
</artwork></figure>

<t>Here is a figure that is actually pulled from somewhere else.
<cref source='cs' anchor='rememberme'>
Remember to check whether that file still exists.</cref></t>

<figure><artwork
  src='http://www.example.com/~employees/chrissmith/artwork.txt'>
</artwork></figure>

</section>

<section><name>Tables</name>

<t>The following is a table example.</t>

<t keepWithNext='true'>These are sometimes called "inert" gasses.</t>
<table title='The Noble Gases'>

  <tr><th>Name</th>
  <th align='center'>Symbol</th>
  <th align='center'>Atomic Number</th></tr>

  <tr><td>Helium</td>
  <td align='center'>He</td>
  <td align='center'>2</td></tr>

  <tr><td>Neon</td>
  <td align='center'>Ne</td>
  <td align='center'>10</td></tr>

  <tr><td>Argon</td>
  <td align='center'>Ar</td>
  <td align='center'>18</td></tr>

  <tr><td>Krypton</td>
  <td align='center'>Kr</td>
  <td align='center'>36</td></tr>

  <tr><td>Xenon</td>
  <td align='center'>Xe</td>
  <td align='center'>54</td></tr>

  <tr><td>Radon</td>
  <td align='center'>Rn</td>
  <td align='center'>86</td></tr>




Hoffman & Hansen        Expires November 7, 2015               [Page 14]


Internet-Draft              RFC XML Examples                    May 2015


  </table><t keepWithPrevious='true'>Source: Chemistry 101</t>


<t>The following is a right-aligned table with "full"
(but not "all") lines between cells.</t>

<table align='right' style='full'>
  <tr><th>Time</th>
  <th align='right'>Mood</th></tr>

  <tr><td>Morning</td>
  <td align='right'>Happy!</td></tr>

  <tr><td>Afternoon</td>
  <td align='right'>Happy!</td></tr>

  <tr><td>Evening</td>
  <td align='right'>Somber</td></tr>

</table>

</section>

<section anchor='IANA'><name>IANA Considerations</name>

<t>None.</t>

</section>

<section anchor='Security'><name>Security Considerations</name>

<t>There are no security considerations for an imaginary
Internet Draft.</t>

</section>

<section anchor='Acknowledgements'><name>Acknowledgements</name>

<t>Some of the things included in this draft came from
Elwyn Davies' templates.</t>

</section>

</middle>

<back>

<references><name>Normative References</name>



Hoffman & Hansen        Expires November 7, 2015               [Page 15]


Internet-Draft              RFC XML Examples                    May 2015


<xi:include
href='http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml'/>

</references>

<references><name>Informative References</name>

<reference anchor='RFC6949'>
<front>
<title>RFC Series Format Requirements and Future Development</title>
<author initials='H.' surname='Flanagan' fullname='H. Flanagan'>
<organization/></author>
<author initials='N.' surname='Brownlee' fullname='N. Brownlee'>
<organization/></author>
<date year='2013' month='May'/>
</front>
<seriesInfo name='RFC' value='6949'/>
<annotation>This is a primary reference work.</annotation>
</reference>

<reference anchor='RED'
  target='http://www.aciri.org/floyd/papers/early.pdf'>
<front>
<title>Random Early Detection (RED) gateways for Congestion
Avoidance</title>
<author fullname='Sally Floyd' initials='S' surname='Floyd'>
<organization>LBL</organization>
</author>
<author fullname='Van Jacobson' initials='V' surname='Jacobson'>
<organization>LBL</organization>
</author>
<date month='August' year='1993'/>
</front>
<seriesInfo
  name='IEEE/ACM Transactions on Networking' value='1(4) 397--413'/>

</reference>

</references>

</back>
</rfc>

4.  Security Considerations

   The examples in this document do not introduce any new security
   considerations.




Hoffman & Hansen        Expires November 7, 2015               [Page 16]


Internet-Draft              RFC XML Examples                    May 2015


5.  IANA Considerations

   There are no IANA considerations for this document.

6.  Acknowledgments

   The ideas for the examples in this document come from many people
   over a long period of time.  Special thanks go to the Alice Russo and
   other members of the RFC Design Team for suggestions and debugging
   help.

7.  Normative References

   [XML2RFCv2]
              Reschke, J., "The 'XML2RFC' version 2 Vocabulary", draft-
              reschke-xml2rfc (work in progress), 2014.

   [XML2RFCv3]
              Hoffman, P., "The 'XML2RFC' version 3 Vocabulary", draft-
              hoffman-xml2rfc (work in progress), 2014.

Authors' Addresses

   Paul Hoffman
   VPN Consortium

   EMail: paul.hoffman@vpnc.org


   Tony Hansen
   AT&T Laboratories
   200 Laurel Ave. South
   Middletown, NJ  07748
   USA

   EMail: tony+rfcv3@maillennium.att.com















Hoffman & Hansen        Expires November 7, 2015               [Page 17]