= Put Your Internet Draft Title Here
Elwyn Davies <elwynd@dial.pipex.com>
:doctype: internet-draft
:name: draft-ietf-xml2rfc-template-06
:ipr: trust200902
:status: info
:abbrev: Abbreviated Title
:fullname: Elwyn Davies
:forename_initials: E.B.
:role: editor
:surname: Davies
:organization: Folly Consulting
:city: Soham
:country: UK
:phone: +44 7889 488 335
:email: elwynd@dial.pipex.com
:revdate: 2010-04-01
:area: General
:workgroup: Internet Engineering Task Force
:keyword: template
:inline-definition-lists: true
:compact: yes
:subcompact: no
:rfc2629xslt: true
[abstract]
Insert an abstract: MANDATORY. This template is for creating an
Internet Draft.
== Introduction
The original specification of xml2rfc format is in <<RFC2629,RFC 2629>>.
=== Requirements Language
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 <<RFC2119,RFC 2119>>.
[[simple_list]]
== Simple List
List styles: 'empty', 'symbols', 'letters', 'numbers', 'hanging',
'format'.
* First bullet
* Second bullet
You can write text here as well.
//[Note: Asciidoc will force new paragraph]
== Figures
Figures should not exceed 69 characters wide to allow for the indent
of sections.
[[xml_happy]]
[align=center]
====
Preamble text - can be omitted or empty.
[align=left]
....
+-----------------------+
| Use XML, be Happy :-) |
|_______________________|
....
Cross-references allowed in pre- and postamble. <<min_ref>>.
====
The CDATA means you don't need to escape meta-characters (especially
< (\<) and & (\&)) but is not essential.
Figures may also have a title attribute but it won't be displayed unless
there is also an anchor. White space, both horizontal and vertical, is
significant in figures even if you don't use CDATA.
== Subsections and Tables
=== A Subsection
By default 3 levels of nesting show in table of contents but that
can be adjusted with the value of the "tocdepth" processing
instruction.
=== Tables
pass:[..] are very similar to figures:
//[Note: Asciidoc does not support preambles and postambles within tables.]
Tables use ttcol to define column headers and widths. Every cell then has a "c" element for its content.
[[table_example]]
.A Very Simple Table
[cols="2*^", frame="sides", grid="cols"]
|===
|ttcol #1 |ttcol #2
|c #1 |c #2
|c #3 |c #4
|c #5 |c #6
|===
which is a very simple example.
[[nested_lists]]
== More about Lists
Lists with 'hanging labels': the list item is indented the amount of
the hangIndent:
[hang-indent=8]
short:: With a label shorter than the hangIndent.
fantastically long label:: With a label longer than the hangIndent.
vspace_trick:: {blank} +
Forces the new item to start on a new line.
Simulating more than one paragraph in a list item using
<vspace>:
[loweralpha]
. First, a short item.
. Second, a longer list item.
+
{blank}
+
And something that looks like a separate pararaph..
NOTE: In Asciidoc, it *is* a separate paragraph.
Simple indented paragraph using the "empty" style:
[empty,hang-indent=8]
* The quick, brown fox jumped over the lazy dog and lived to fool
many another hunter in the great wood in the west.
=== Numbering Lists across Lists and Sections
Numbering items continuously although they are in separate
<list> elements, maybe in separate sections using the "format"
style and a "counter" variable.
First list:
[hang-indent=4,counter=reqs,format=R%d]
. #1
. #2
. #3
Specify the indent explicitly so that all the items line up
nicely.
Second list:
[hang-indent=4,counter=reqs,format=R%d]
. #4
. #5
. #6
=== Where the List Numbering Continues
List continues here.
Third list:
[hang-indent=4,counter=reqs,format=R%d]
. #7
. #8
. #9
. #10
The end of the list.
[[codeExample]]
== Example of Code or MIB Module To Be Extracted
// NOTE: in asciidoctor-rfc output we're missing an empty line before
// the code block and after it. Can't figure out a way to create that...
====
The <artwork> element has a number of extra attributes
that can be used to substitute a more aesthetically pleasing rendition
into HTML output while continuing to use the ASCII art version in the
text and nroff outputs (see the xml2rfc README for details). It also
has a "type" attribute. This is currently ignored except in the case
'type="abnf"'. In this case the "artwork" is expected to contain a
piece of valid Augmented Backus-Naur Format (ABNF) grammar. This will
be syntax checked by xml2rfc and any errors will cause a fatal error
if the "strict" processing instruction is set to "yes". The ABNF will
also be colorized in HTML output to highlight the syntactic
components. Checking of additional "types" may be provided in future
versions of xml2rfc.
----
/**** an example C program */
#include <stdio.h>
void
main(int argc, char *argv[])
{
int i;
printf("program arguments are:\n");
for (i = 0; i < argc; i++) {
printf("%d: \"%s\"\n", i, argv[i]);
}
exit(0);
} /* main */
/* end of file */
----
====
[[Acknowledgements]]
== Acknowledgements
This template was derived from an initial version written by Pekka Savola and contributed by him to the xml2rfc project.
This document is part of a plan to make xml2rfc indispensable <<DOMINATION>>.
[[IANA]]
== IANA Considerations
This memo includes no request to IANA.
All drafts are required to have an IANA considerations section (see
<<RFC5226,Guidelines for Writing an IANA Considerations Section in RFCs>> for a guide). If the draft does not require IANA to do
anything, the section contains an explicit statement that this is the
case (as above). If there are no requirements for IANA, the section will
be removed during conversion into an RFC by the RFC Editor.
[[Security]]
== Security Considerations
All drafts are required to have a security considerations section.
See <<RFC3552,RFC 3552>> for a guide.
[bibliography]
== Normative References
++++
<reference anchor='RFC2119' target='https://www.rfc-editor.org/info/rfc2119'>
<front>
<title>Key words for use in RFCs to Indicate Requirement Levels</title>
<author initials='S.' surname='Bradner' fullname='S. Bradner'><organization /></author>
<date year='1997' month='March' />
<abstract><t>In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t></abstract>
</front>
<seriesInfo name='BCP' value='14'/>
<seriesInfo name='RFC' value='2119'/>
<seriesInfo name='DOI' value='10.17487/RFC2119'/>
</reference>
<reference anchor="min_ref">
<!-- the following is the minimum to make xml2rfc happy -->
<front>
<title>Minimal Reference</title>
<author initials="authInitials" surname="authSurName">
<organization></organization>
</author>
<date year="2006" />
</front>
</reference>
++++
[bibliography]
== Informative References
++++
<!-- Here we use entities that we defined at the beginning. -->
<reference anchor='RFC2629' target='https://www.rfc-editor.org/info/rfc2629'>
<front>
<title>Writing I-Ds and RFCs using XML</title>
<author initials='M.' surname='Rose' fullname='M. Rose'><organization /></author>
<date year='1999' month='June' />
<abstract><t>This memo presents a technique for using XML (Extensible Markup Language) as a source format for documents in the Internet-Drafts (I-Ds) and Request for Comments (RFC) series. This memo provides information for the Internet community.</t></abstract>
</front>
<seriesInfo name='RFC' value='2629'/>
<seriesInfo name='DOI' value='10.17487/RFC2629'/>
</reference>
<reference anchor='RFC3552' target='https://www.rfc-editor.org/info/rfc3552'>
<front>
<title>Guidelines for Writing RFC Text on Security Considerations</title>
<author initials='E.' surname='Rescorla' fullname='E. Rescorla'><organization /></author>
<author initials='B.' surname='Korver' fullname='B. Korver'><organization /></author>
<date year='2003' month='July' />
<abstract><t>All RFCs are required to have a Security Considerations section. Historically, such sections have been relatively weak. This document provides guidelines to RFC authors on how to write a good Security Considerations section. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t></abstract>
</front>
<seriesInfo name='BCP' value='72'/>
<seriesInfo name='RFC' value='3552'/>
<seriesInfo name='DOI' value='10.17487/RFC3552'/>
</reference>
<reference anchor='RFC5226' target='https://www.rfc-editor.org/info/rfc5226'>
<front>
<title>Guidelines for Writing an IANA Considerations Section in RFCs</title>
<author initials='T.' surname='Narten' fullname='T. Narten'><organization /></author>
<author initials='H.' surname='Alvestrand' fullname='H. Alvestrand'><organization /></author>
<date year='2008' month='May' />
<abstract><t>Many protocols make use of identifiers consisting of constants and other well-known values. Even after a protocol has been defined and deployment has begun, new values may need to be assigned (e.g., for a new option type in DHCP, or a new encryption or authentication transform for IPsec). To ensure that such quantities have consistent values and interpretations across all implementations, their assignment must be administered by a central authority. For IETF protocols, that role is provided by the Internet Assigned Numbers Authority (IANA).</t><t>In order for IANA to manage a given namespace prudently, it needs guidelines describing the conditions under which new values can be assigned or when modifications to existing values can be made. If IANA is expected to play a role in the management of a namespace, IANA must be given clear and concise instructions describing that role. This document discusses issues that should be considered in formulating a policy for assigning values to a namespace and provides guidelines for authors on the specific text that must be included in documents that place demands on IANA.</t><t>This document obsoletes RFC 2434. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t></abstract>
</front>
<seriesInfo name='RFC' value='5226'/>
<seriesInfo name='DOI' value='10.17487/RFC5226'/>
</reference>
<!-- A reference written by by an organization not a person. -->
<reference anchor="DOMINATION"
target="http://www.example.com/dominator.html">
<front>
<title>Ultimate Plan for Taking Over the World</title>
<author>
<organization>Mad Dominators, Inc.</organization>
</author>
<date year="1984" />
</front>
</reference>
++++
[[app-additional]]
[appendix]
== Additional Stuff
This becomes an Appendix.
////
<!-- Change Log
v00 2006-03-15 EBD Initial version
v01 2006-04-03 EBD Moved PI location back to position 1 -
v3.1 of XMLmind is better with them at this location.
v02 2007-03-07 AH removed extraneous nested_list attribute,
other minor corrections
v03 2007-03-09 EBD Added comments on null IANA sections and fixed heading capitalization.
Modified comments around figure to reflect non-implementation of
figure indent control. Put in reference using anchor="DOMINATION".
Fixed up the date specification comments to reflect current truth.
v04 2007-03-09 AH Major changes: shortened discussion of PIs,
added discussion of rfc include.
v05 2007-03-10 EBD Added preamble to C program example to tell about ABNF and alternative
images. Removed meta-characters from comments (causes problems).
v06 2010-04-01 TT Changed ipr attribute values to latest ones. Changed date to
year only, to be consistent with the comments. Updated the
IANA guidelines reference from the I-D to the finished RFC. -->
////