]> Full Organization name

Espoo FI psavola@funet.fi

Folly Consulting

Soham UK +44 7889 488 335 elwynd@dial.pipex.com

Operations & Management Internet Engineering Task Force This is an abstract abstract. I-Ds and RFCs MUST have an abstract but other uses might not want an abstract so it is optional unless strict="yes". Remember, don't add references here. So we would just say the 'language' used to write this document is defined in RFC 2629. This "foreword" section is an unnumbered section that is not included in the table of contents. It is primarily used for the IESG to make comments about the document. It can also be used for comments about the status of the document and sometimes is used for the RFC2119 requirements language statement. In this example, it is used as a handy place to specify URLs to documents and tools to author RFC-style documents using XML. RFC2629 is the original published document on authoring RFC-style documents in XML (). It is being updated (and called RFC2629(bis) and is . The tool to convert XML documents to RFC-style text (and HTML) files is described in document . Please also remember to check out for issues to note when writing drafts and the automated tools documented at . Remember, you don't need to have any other tools than a 'notepad' or your favorite editor to write xml2rfc drafts. You can use the web interface at 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. This template is not meant to be a conclusive list of everything, but will summarize the often-needed basic features to get one started. This example makes extensive use of "(")and '(') entities: this is not strictly necessary but may avoid problems if pieces of text are moved into attribute values, where it would be necessary. It also avoids problems if the text is edited with Microsoft Word with the 'smart quotes' option turned on (see Word menu Tools->Auto Correct Options, 'AutoFormat As You Type' tab) which might result in the left and right quotes characters replacing the ASCII character. 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 RFC 2119.

Now you can have a bit lengthier text here. The definition of the XML Data Type Description used to 'describe' an RFC or Internet Draft can be found in a document which we can refer to as RFC 2629. Let's refer to a couple more documents, just for practice: "Ultimate Plan for Taking Over The World" and L2TP. For text generation, these look equivalent, but the latter looks a bit neater in the HTML representation. You might also add a note about the usage of RFC2119 keywords here using the same text as in the note above. You can cross-reference the sections of the document in a stable manner either by section number - the usual way - or by section title (""): if the organization of the document changes the reference will still be to the correct section. However "sect2" is not a very good 'anchor' name because there is no guarantee that this section will remain as Section 2 for ever. It is best to use some sort of mnemonic for the contents of the section, which also makes it easier to remember the anchor when creating a cross-reference many pages later. A final note about anchors: anchors are XML 'tokens' and must therefore consist only of letters, numbers, underscores, hyphens and periods, starting with either a letter or underscore. Anchors with spaces or other punctuation characters are not allowed.

Technical documents often use lists. There are multiple list styles: 'empty', 'symbols', 'letters', 'numbers', 'hanging', 'format', etc. A more complicated list structure can be found in . First bullet Second bullet You can write text here as well - the difference, as compared with putting it in the next <t> element, is that there will not be a blank line between the last list item and this text if the processing instructions compact and subcompact are both set to "yes". Otherwise list items and the text before and after will be separated by blank lines. One can draw fancy diagrams as well; remember to ensure that they don't exceed 69 chars/line until v1.31 comes along. v1.31 should give you the ability to start figures at the left margin getting figures up to 72 characters wide. Setting the alignment for the whole figure to "center" instead of the default "left" causes all the components to be centred unless it is overridden just for the "artwork", as it is here.

Figures can have some text before the artwork should it be needed. Note that figures should NOT be inside <t> elements. Originally they were allowed to be but you will now get a warning that this is deprecated, and the figure should be a 'child' of the section element. Figures can also have text after the artwork and before the caption (if any). This figure has an anchor. This means that the figure will get a caption...

Note that including a CDATA means you don't need to escape most special characters you might otherwise have to. Figures may also have a title attribute but it won't be displayed unless there is also an anchor, and it will be somewhat disconcerting for readers if some figures have numbers and others don't..

There can be a lot of subsections (and sub-subsections). By default 3 levels of nesting show in the Table of Contents but that can be adjusted with the value of the "tocdepth" processing instruction. There are also attributes that can be used to force individual titles in and out of the Table of Contents.

Another item that you might need is a table. The XML for tables is very similar to that for figures: Tables use ttcol to define column headers and widths. Every cell then has a "c" element for its content. ttcol #1 ttcol #2 c #1 c #2 c #3 c #4 c #5 c #6 which is a very simple example.

One useful style of lists uses 'hanging labels' where the list item is indented by the amount of the hangIndent with the hanging label displayed to the left of the first line of the item. This example shows how <vspace> can be used to deal with the odd label longer than the indent you really want to use (This is only really relevant to text mode output because the labels are always on separate lines in HTML output): With a label shorter than the hangIndent there is white space after the label and before the item text starts although it starts on the same line - clearly separating the label from the column of items. With a label longer than the hangIndent the label runs on into the text item and the separation is lost. Inserting a <vspace /> at the start of the item forces the new item to start on a new line emphasizing the separation again. List items in xml2rfc are made up of one <t> element. In some cases it would be nice to have more than one paragraph in a list item. This can be achieved with <vspace> also: First, a short item that needs only one paragraph. Second, a longer list item. We have more to say, and we want a separate paragraph. And here we can have it, and go on to our heart's content. If you just want an indented paragraph (say for a quotation) use the "empty" style: The quick, brown fox jumped over the lazy dog and lived to fool many another hunter in the great wood in the west.

Sometimes it is useful to be able to number items continuously although they are in separate <list> elements, maybe in separate sections. This can be achieved using the "format" style and a "counter" variable. First list with (say) requirements items: Requirement #1 Requirement #2 Requirement #3 It is wise to specify the indent explicitly so that all the items line up nicely. Otherwise the indent in each list is determined by the maximum length of the labels in that list, even if later lists have longer labels. A little later there is a second list with requirements items: Requirement #4 Requirement #5 Requirement #6 before this section finishes.

But in the next section the list of requirements continues: Third list with requirements items: Requirement #7 Requirement #8 Requirement #9 Requirement #10 And finally that is all about the requirements.

The artwork element from RFC 2629 supports an optional type attribute. While most possible values are just ignored, including the special case where the attribute is unspecified or just empty, some values are recognized. In particular, type='abnf' can be used if the artwork contains an Augmented Backus-Naur Form (ABNF) syntax specification . As a special extension in its behavior, xml2rfc will attempt to validate the syntax and colorize the HTML output of ABNF, since it is so widely used in RFCs. It does this colorizing by relying on the full parsing it does right before, not on a quick and partial (e.g., line-by-line) pattern-based hack. ABNF is the only artwork type to benefit from this kind of internal support at this time. If the strict rfc-PI directive is activated, invalid ABNF content will cause xml2rfc to abort with an error message. Omitting the type attribute altogether is the obvious way to avoid having this validation and colorizing performed.

For example (to be viewed in HTML): " ; bracketed string of SP and VCHAR without angles ; prose description, to be used as last resort ]]> This is from the original RFC on ABNF , with its minor mistakes in manually folded comment lines purposely left intact, for illustration. Since the result is still valid ABNF (but incorrect with respect to what was intended), this showcases how colorizing might give a human author (or editor or reader) a better chance to spot the three mistakes (and correct them, e.g., with extra semicolons, as has been done in a more recent version  of the ABNF specification). Note that it is the white space characters at the beginning of the subsequent lines (including the commented ones) that conspire to extend the reach of those rules across several lines.

The most common form of xml2rfc parsing errors 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.

=======8<======== ]]>

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 */ ]]>

Remember, it's important to acknowledge people who have contributed to the work. This template was extended from an initial version written by Pekka Savola and contributed by him to the xml2rfc project.

This memo includes no request to IANA. (It's good - indeed pretty much mandatory now - to have an explicit note because otherwise IANA wastes cycles trying to figure out if something is needed..)

Remember to consider security from the start.. and all drafts are required to have a security considerations section before they will pass the IESG.

Harvard University

1350 Mass. Ave. Cambridge MA 02138 - +1 617 495 3864 sob@harvard.edu

General keyword 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. Authors who follow these guidelines should incorporate this phrase near the beginning of their document: 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 RFC 2119. Note that the force of these words is modified by the requirement level of the document in which they are used. &RFC2629; Mad Dominators, Inc. &RFC4234; &RFC2234;

You can add appendices just as regular sections, the only difference is that they go within the "back" element, and not within the "middle" element. And they follow the "reference" elements.