idnits 2.17.1 

draft-mrose-writing-rfcs-02.txt:

  Checking boilerplate required by RFC 5378 and the IETF Trust (see
  https://trustee.ietf.org/license-info):
  ----------------------------------------------------------------------------

  ** Looks like you're using RFC 2026 boilerplate.  This must be updated to
     follow RFC 3978/3979, as updated by RFC 4748.


  Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
  ----------------------------------------------------------------------------

  ** Missing expiration date.  The document expiration date should appear on
     the first and last page.

  == No 'Intended status' indicated for this document; assuming Proposed
     Standard


  Checking nits according to https://www.ietf.org/id-info/checklist :
  ----------------------------------------------------------------------------

  ** The document seems to lack an IANA Considerations section.  (See Section
     2.2 of https://www.ietf.org/id-info/checklist for how to handle the case
     when there are no actions for IANA.)

  ** The document seems to lack separate sections for Informative/Normative
     References.  All references will be assumed normative when checking for
     downward references.

  == There are 2 instances of lines with non-RFC6890-compliant IPv4 addresses
     in the document.  If these are example addresses, they should be changed.


  Miscellaneous warnings:
  ----------------------------------------------------------------------------

  == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not
     match the current year

  -- The document seems to lack a disclaimer for pre-RFC5378 work, but may
     have content which was first submitted before 10 November 2008.  If you
     have contacted all the original authors and they are all willing to grant
     the BCP78 rights to the IETF Trust, then this is fine, and you can ignore
     this comment.  If not, you may need to add the pre-RFC5378 disclaimer. 
     (See the Legal Provisions document at
     https://trustee.ietf.org/license-info for more information.)

  -- The document date (April 1999) is 9143 days in the past.  Is this
     intentional?

  -- Found something which looks like a code comment -- if you have code
     sections in the document, please surround them with '<CODE BEGINS>' and
     '<CODE ENDS>' lines.


  Checking references for intended status: Proposed Standard
  ----------------------------------------------------------------------------

     (See RFCs 3967 and 4897 for information about using normative references
     to lower-maturity documents in RFCs)

  -- Possible downref: Non-RFC (?) normative reference: ref. '1'

  ** Obsolete normative reference: RFC 2223 (ref. '2') (Obsoleted by RFC 7322)

  ** Obsolete normative reference: RFC 2396 (ref. '4') (Obsoleted by RFC 3986)

  -- Possible downref: Non-RFC (?) normative reference: ref. '5'

  -- Possible downref: Non-RFC (?) normative reference: ref. '6'

  -- Possible downref: Non-RFC (?) normative reference: ref. '7'

  -- Possible downref: Non-RFC (?) normative reference: ref. '8'

  -- Possible downref: Non-RFC (?) normative reference: ref. '9'

  -- Possible downref: Non-RFC (?) normative reference: ref. '10'

  -- Possible downref: Non-RFC (?) normative reference: ref. '11'


     Summary: 6 errors (**), 0 flaws (~~), 3 warnings (==), 11 comments (--).

     Run idnits with the --verbose option for more detailed information about
     the items above.

--------------------------------------------------------------------------------

1	Network Working Group                                          M.T. Rose
2	Internet-Draft                                    Invisible Worlds, Inc.
3	Expires: September 30, 1999                                   April 1999

5	                    Writing I-Ds and RFCs using XML
6	                      draft-mrose-writing-rfcs-02.txt

8	Status of this Memo

10	   This document is an Internet-Draft and is in full conformance with
11	   all provisions of Section 10 of RFC2026.

13	   Internet-Drafts are working documents of the Internet Engineering
14	   Task Force (IETF), its areas, and its working groups. Note that
15	   other groups may also distribute working documents as
16	   Internet-Drafts.

18	   Internet-Drafts are draft documents valid for a maximum of six
19	   months and may be updated, replaced, or obsoleted by other documents
20	   at any time. It is inappropriate to use Internet-Drafts as reference
21	   material or to cite them other than as "work in progress."

23	   The list of current Internet-Drafts can be accessed at
24	   http://www.ietf.org/ietf/1id-abstracts.txt

26	   The list of Internet-Draft Shadow Directories can be accessed at
27	   http://www.ietf.org/shadow.html.

29	   This Internet-Draft will expire on September 30, 1999.

31	Abstract

33	   This memo presents a technique for using XML as a source format for
34	   documents in the Internet-Drafts and RFC series.

36	Copyright Notice

38	   Copyright (C) The Internet Society (1999). All Rights Reserved.

40	Table of Contents

42	   1.      Introduction . . . . . . . . . . . . . . . . . . . . . . .  3
43	   2.      Using the DTD to Write I-Ds and RFCs . . . . . . . . . . .  4
44	   2.1     XML basics . . . . . . . . . . . . . . . . . . . . . . . .  4
45	   2.2     Front matter . . . . . . . . . . . . . . . . . . . . . . .  6
46	   2.2.1   The title Element  . . . . . . . . . . . . . . . . . . . .  6
47	   2.2.2   The author Element . . . . . . . . . . . . . . . . . . . .  7
48	   2.2.3   The date Element . . . . . . . . . . . . . . . . . . . . .  8
49	   2.2.4   Meta Data Elements . . . . . . . . . . . . . . . . . . . .  8
50	   2.2.5   The abstract Element . . . . . . . . . . . . . . . . . . .  9
51	   2.2.6   The note Element . . . . . . . . . . . . . . . . . . . . .  9
52	   2.2.7   Status, Copyright Notice, Table of Contents  . . . . . . .  9
53	   2.2.7.1 Conformance with RFC 2026  . . . . . . . . . . . . . . . .  9
54	   2.2.8   Everything in the Front  . . . . . . . . . . . . . . . . . 10
55	   2.3     The Middle . . . . . . . . . . . . . . . . . . . . . . . . 11
56	   2.3.1   The section Element  . . . . . . . . . . . . . . . . . . . 11
57	   2.3.1.1 The t Element  . . . . . . . . . . . . . . . . . . . . . . 12
58	   2.3.1.2 The list Element . . . . . . . . . . . . . . . . . . . . . 12
59	   2.3.1.3 The figure Element . . . . . . . . . . . . . . . . . . . . 13
60	   2.3.1.4 The xref Element . . . . . . . . . . . . . . . . . . . . . 15
61	   2.3.1.5 The eref Element . . . . . . . . . . . . . . . . . . . . . 15
62	   2.3.1.6 The iref Element . . . . . . . . . . . . . . . . . . . . . 16
63	   2.3.1.7 The vspace Element . . . . . . . . . . . . . . . . . . . . 16
64	   2.4     Back matter  . . . . . . . . . . . . . . . . . . . . . . . 17
65	   2.4.1   The references Element . . . . . . . . . . . . . . . . . . 17
66	   2.4.2   Appendices . . . . . . . . . . . . . . . . . . . . . . . . 18
67	   2.4.3   Copyright Status . . . . . . . . . . . . . . . . . . . . . 18
68	   3.      Processing the XML Source File . . . . . . . . . . . . . . 19
69	   3.1     Editing  . . . . . . . . . . . . . . . . . . . . . . . . . 19
70	   3.1.1   Checking . . . . . . . . . . . . . . . . . . . . . . . . . 19
71	   3.2     Converting to Text Format  . . . . . . . . . . . . . . . . 20
72	   3.3     Converting to HTML Format  . . . . . . . . . . . . . . . . 20
73	   3.4     Viewing  . . . . . . . . . . . . . . . . . . . . . . . . . 20
74	   3.5     Searching  . . . . . . . . . . . . . . . . . . . . . . . . 20
75	   4.      Security Considerations  . . . . . . . . . . . . . . . . . 21
76	           References . . . . . . . . . . . . . . . . . . . . . . . . 22
77	           Author's Address . . . . . . . . . . . . . . . . . . . . . 22
78	   A.      The rfc Element  . . . . . . . . . . . . . . . . . . . . . 23
79	   B.      The RFC DTD  . . . . . . . . . . . . . . . . . . . . . . . 24
80	   C.      Acknowledgements . . . . . . . . . . . . . . . . . . . . . 29
81	   D.      Revision History . . . . . . . . . . . . . . . . . . . . . 30
82	   D.1     Changes since 01 . . . . . . . . . . . . . . . . . . . . . 30
83	   D.2     Changes since 00 . . . . . . . . . . . . . . . . . . . . . 30

85	1. Introduction

87	   This memo describes how to write a document for the I-D and RFC
88	   series using the Extensible Markup Language[1] (XML). This memo has
89	   three goals:

91	   1.  To describe a simple XML Document Type Definition (DTD) that is
92	       powerful enough to handle the simple formatting requirements of
93	       RFC-like documents whilst allowing for meaningful markup of
94	       descriptive qualities.

96	   2.  To describe software that processes XML source files, including
97	       a tool that produces documents conforming to RFC 2223[2], HTML
98	       format, and so on.

100	   3.  To provide the proof-of-concept for the first two goals (this
101	       memo was written using this DTD and produced using that
102	       software).

104	   It is beyond the scope of this memo to discuss the political
105	   ramifications of using XML as a source format for RFC-like
106	   documents. Rather, it is simply noted that adding minimal markup to
107	   plain text:

109	   o  allows the traditional production of textual RFC-like documents
110	      using familiar editors;

112	   o  requires some, albeit minimal, additions to existing software
113	      environments; and,

115	   o  permits information to be organized, searched, and retrieved
116	      using both unstructured and structured mechanisms.

118	2. Using the DTD to Write I-Ds and RFCs

120	   We do not provide a formal or comprehensive description of XML.
121	   Rather, this section discusses just enough XML to use a Document
122	   Type Declaration (DTD) to write RFC-like documents.

124	   If you're already familiar with XML, skip to Appendix B to look at
125	   the DTD.

127	2.1 XML basics

129	   There are very few rules when writing in XML, as the syntax is
130	   simple. There are five terms you'll need to know:

132	   1.  An "element" usually refers to a start tag, an end tag, and all
133	       the characters in between, e.g., "<example>text and/or nested
134	       elements</example>"

136	   2.  An "empty element" combines the start tag and the end tag, e.g.,
137	       "<empty/>". You don't find these in HTML.

139	   3.  An "attribute" is part of an element. If present, they occur in
140	       the start tag, e.g., "<example name='value'>". Of course, they
141	       can also appear in empty elements, e.g., "<empty name='value'/>".

143	   4.  An "entity" is a textual macro that starts with "&". Don't worry
144	       about these, you'll only use them whenever you want to put a "&"
145	       or a "<" in your text.

147	   5.  A "token" is a string of characters. The first character is
148	       either a letter or an underscore ("_"). Any characters that
149	       follow are either letters, numbers, an underscore, or a period
150	       (".").

152	   First, start your source file with an XML declaration, a reference
153	   to the DTD, and the "rfc" element:

155	       <?xml version="1.0"?>
156	       <!DOCTYPE rfc SYSTEM "rfcXXXX.dtd">
157	       <rfc>
158	           ...
159	       </rfc>

161	   Ignore the first two lines -- the declaration and the reference --
162	   and simply treat them as opaque strings. Nothing else should be
163	   present after the "</rfc>" tag.

165	   (NOTE TO READER: when this memo is published as an RFC, the "XXXX"
166	   above will be replaced with the actual string to use in your source
167	   file.)

169	   Second, make sure that all elements are properly matched and nested.
170	   A properly matched element that starts with "<example>" is
171	   eventually followed with "</example>". (Empty elements are always
172	   matched.) Elements are properly nested when they don't overlap.

174	   For example,

176	       <outer>
177	           ...
178	           <inner>
179	               ...
180	           </inner>
181	           ...
182	       </outer>

184	   is properly nested.

186	   However,

188	       <outer>
189	           ...
190	           <inner>
191	               ...
192	           </outer>
193	           ...
194	       </inner>

196	   overlaps, so the elements aren't properly nested.

198	   Third, never use "<" or "&" in your text. Instead, use either "&lt;"
199	   or "&amp;", respectively.

201	   Fourth, there are two quoting characters in XML, 'apostrophe' and
202	   "quotation". Make sure that all attributes values are quoted, e.g.,
203	   "<example name='value'>", If the value contains one of the quoting
204	   characters, then use the other to quote the value, e.g., "<example
205	   name='"'>", If the value contains both quoting characters, then use
206	   one of them to quote the value, and replace occurrances of that
207	   character in the attribute value with either '&apos;' (apostrophe)
208	   or "&quot;" (quotation), e.g., "<example name='"&apos;"'>".

210	   If you want to put a comment in your source file, here's the syntax:

212	           <!-- comments can be multiline,
213	            if you wish -->

215	   Finally, XML is case sensitive.

217	2.2 Front matter

219	   Immediately following the "<rfc>" tag is the "front" element:

221	       <?xml version="1.0"?>
222	       <!DOCTYPE rfc SYSTEM "rfcXXXX.dtd">
223	       <rfc>
224	           <front>
225	               <title ...>
226	               <author ...>
227	               <author ...>
228	               <date ...>
229	               <area ...>
230	               <workgroup ...>
231	               <keyword ...>
232	               <keyword ...>
233	               <abstract ...>
234	               <note ...>
235	           </front>
236	           ...
237	       </rfc>

239	   (Note that in all examples, indentation is used only for expository
240	   purposes.)

242	   The "front" element consists of a "title" element, one or more
243	   "author" elements, a "date" element, one or more optional "area"
244	   elements, one or more optional "workgroup" elements, one or more
245	   optional "keyword" elements, an optional "abstract" element. and,
246	   one or more optional "note" elements.

248	2.2.1 The title Element

250	   The "title" element identifies the title of the document. Because
251	   the title will be used in the headers of the document when formatted
252	   according to [2], if the title is more than 42 characters, then an
253	   abbreviation should also be provided, e.g.,

255	       <title abbrev="Much Ado about Nothing">
256	       The IETF's Discussion on "Source Format of RFC Documents"
257	       </title>

259	2.2.2 The author Element

261	   Each "author" element identifies a document author. Since a document
262	   may have more than one author, more than one "author" element may be
263	   present. If the author is a person, then three attributes must be
264	   present in the "<author>" tag, "initials", "surname", and
265	   "fullname", e.g.,

267	       <author initials="M.T." surname="Rose"
268	               fullname="Marshall T. Rose">

270	   The "author" element itself consists of an "organization" element,
271	   and, an optional "address" element.

273	   The "organization" element is similar to the "title" element, in
274	   that an abbreviation may be paired with a long organization name
275	   using the "abbrev" attribute, e.g.,

277	       <organization abbrev="ISI">
278	           USC/Information Sciences Institute
279	       </organization>

281	   The "address" element consists of an optional "postal" element, an
282	   optional "phone" element, an optional "facsimile" element, an
283	   optional "email" element, and, an optional "uri" element.

285	   The "postal" element contains one or more "street" elements,
286	   followed by any combination of "city", "region" (state or province),
287	   "code" (zipcode or postal code), and "country" elements, e.g.,

289	       <postal>
290	           <street>660 York Street</street>
291	           <street>M/S 40</street>
292	           <city>San Francisco</city> <region>CA</region>
293	           <code>94110</code>
294	           <country>US</country>
295	       </postal>

297	   This flexibility is provided to allow for different national formats
298	   for postal addresses. Note however, that although the order of the
299	   "city", "region", "code", and "country" elements isn't specified, at
300	   most one of each may be present. Regardless, these elements must not
301	   be re-ordered during processing by an XML application (e.g., display
302	   applications must preserve the ordering of the information contained
303	   in these elements). Finally, the value of the "country" element
304	   should be a two-letter code from ISO 3166.

306	   The "phone", "facsimile", "email", and "uri" elements are simple,
307	   e.g.,

309	       <phone>+1 415 695 3975</phone>
310	       <email>mrose@not.invisible.net</email>
311	       <uri>http://invisible.net/</uri>

313	2.2.3 The date Element

315	   The "date" element identifies the publication date of the document.
316	   It consists of a month and a year, e.g.,

318	       <date month="February" year="1999" />

320	   The "date" element also has an optional day attribute.

322	2.2.4 Meta Data Elements

324	   The "front" element may contain meta data -- the content of these
325	   elements does not appear in printed versions of the document.

327	   A document has one or more optional "area", "workgroup" and
328	   "keyword" elements, e.g.,

330	       <area>General</area>
331	       <workgroup>RFC Beautification Working Group</workgroup>
332	       <keyword>RFC</keyword>
333	       <keyword>Request for Comments</keyword>
334	       <keyword>I-D</keyword>
335	       <keyword>Internet-Draft</keyword>
336	       <keyword>XML</keyword>
337	       <keyword>Extensible Markup Language</keyword>

339	   The "area" elements identify a general category for the document
340	   (e.g., one of "Applications", "General", "Internet", "Management",
341	   "Operations", "Routing", "Security", "Transport", or "User"), while
342	   the "workgroup" elements identify the IETF working groups that
343	   produced the document, and the "keyword" elements identify useful
344	   search terms.

346	2.2.5 The abstract Element

348	   A document may have an "abstract" element, which contains one or
349	   more "t" elements (Section 2.3.1.1). In general, only a single "t"
350	   element is present, e.g.,

352	       <abstract>
353	           <t>This memo presents a technique for using XML as a
354	           source format for documents in the Internet-Drafts and
355	           RFC series.</t>
356	       </abstract>

358	2.2.6 The note Element

360	   A document may have one or more "note" elements, each of which
361	   contains one or more "t" elements (Section 2.3.1.1). There is a
362	   mandatory "title" attribute. In general, the "note" element contains
363	   text from the IESG, e.g.,

365	       <note title="IESG Note">
366	           <t>The IESG has something to say.</t>
367	       </note>

369	2.2.7 Status, Copyright Notice, Table of Contents

371	   Note that text relating to the memo's status, copyright notice, or
372	   table of contents is not included in the document's markup -- this
373	   is automatically inserted by an XML application when it produces
374	   either a text or HTML version of the document.

376	2.2.7.1 Conformance with RFC 2026

378	   If an Internet-Draft is being produced, then the "ipr" attribute
379	   should be present in the "<rfc>" tag at the beginning of the file.
380	   The value of the attribute should be one of:

382	   full2026: indicating that the document is in full conformance with
383	      all the provisions of Section 10 of RFC 2026;

385	   noDerivativeWorks2026: indicating that the document is in full
386	      conformance with all the provisions of Section 10 of RFC 2026
387	      except that the right to produce derivative works is not granted;
388	      or,

390	   none: indicating that the document is NOT offered in accordance with
391	      Section 10 of RFC 2026, and the author does not provide the IETF
392	      with any rights other than to publish as an Internet-Draft.

394	   In the latter case, a copyright notice will not be automatically
395	   inserted during processing by an XML application.

397	   Consult [3] for further details.

399	   Finally, if the Internet-Draft is being submitted to an automated
400	   process, then the "docName" attribute should be present in the
401	   "<rfc>" tag at the beginning of the file. The value of this
402	   attribute contains the document (not file) name associated with this
403	   Internet-Draft, e.g.,

405	       <rfc ipr="full" docName="draft-mrose-writing-rfcs-01">
406	           ...
407	       </rfc>

409	2.2.8 Everything in the Front

411	   So, putting it all together, we have, e.g.,

413	       <front>
414	           <title>Writing I-Ds and RFCs using XML</title>

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

420	               <address>
421	                   <postal>
422	                       <street>660 York Street</street>
423	                       <street>M/S 40</street>
424	                       <city>San Francisco</city> <region>CA</region>
425	                       <code>94110</code>
426	                       <country>US</country>
427	                   </postal>

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

435	           <date month="February" year="1999" />

437	           <area>General</area>
438	           <workgroup>RFC Beautification Working Group</workgroup>
439	           <keyword>RFC</keyword>
440	           <keyword>Request for Comments</keyword>
441	           <keyword>I-D</keyword>
442	           <keyword>Internet-Draft</keyword>
443	           <keyword>XML</keyword>
444	           <keyword>Extensible Markup Language</keyword>
445	           <abstract>
446	               <t>This memo presents a technique for using XML as a
447	               source format for documents in the Internet-Drafts and
448	               RFC series.</t>
449	           </abstract>
450	       </front>

452	2.3 The Middle

454	   The "middle" element contains all the sections of the document
455	   except for the bibliography and appendices:

457	       ...
458	       </front>
459	       <middle>
460	           <section ...>
461	           <section ...>
462	           <section ...>
463	       </middle>
464	       <back>
465	       ...

467	   The "middle" element consists of one or more "section" elements.

469	2.3.1 The section Element

471	   Each "section" element contains a section of the document. There is
472	   a mandatory attribute, "title", that identifies the title of the
473	   section. There is also an optional attribute, "anchor", that is used
474	   for cross-referencing with the "xref" element (Section 2.3.1.4),
475	   e.g.,

477	       <section anchor="intro" title="Introduction">
478	           ...
479	       </section>

481	   The "section" element is recursive -- each contains any number and
482	   combination of "t", "figure", and "section" elements, e.g.,

484	       <section title="The Middle">
485	           ...
486	           <section title="The section Element">
487	               ...
488	               <section title="The t Element">...</section>
489	               <section title="The list Element">...</section>
490	               <section title="The figure Element">...</section>
491	               <section title="The xref Element">...</section>
492	               <section title="The eref Element">...</section>
493	               <section title="The iref Element">...</section>
494	           </section>
495	       </section>

497	2.3.1.1 The t Element

499	   The "t" element contains any number and combination of paragraphs,
500	   lists, and figures. If a cross-reference is needed to a section,
501	   figure, or reference, the "xref" element (Section 2.3.1.4) is used;
502	   similarly, if an external-reference is needed, the "eref" element
503	   (Section 2.3.1.5) is used. Indexing of text is provided by the the
504	   "iref" element (Section 2.3.1.6).

506	2.3.1.2 The list Element

508	   The "list" element contains one or more items. Each item is a "t"
509	   element, allowing for recursion, e.g.,

511	       <list style="numbers">
512	           <t>The first item.</t>
513	           <t>The second item, which contains two bulleted sub-items:
514	               <list style="symbols">
515	                   <t>The first sub-item.</t>
516	                   <t>The second sub-item.</t>
517	               </list>
518	           </t>
519	       </list>

521	   The "list" element has an optional attribute, "style", having the
522	   value "numbers" (for numeric lists), "symbols" (for bulleted lists),
523	   "hanging" (for hanging lists), or, "empty" (for indented text). If a
524	   "list" element is nested, the default value is taken from its
525	   closest parent; otherwise, the default value is "empty".

527	   When nested within a "hanging list" element, the "t" element has an
528	   optional attribute, "hangText" that specifies the text to be
529	   inserted, e.g.,

531	       <list style="hanging">
532	           <t hangText="full2026:">indicating that the document is in
533	           full conformance with all the provisions of Section 10 of
534	           RFC 2026;</t>

536	           <t hangText="noDerivativeWorks2026:">indicating that the
537	           document is in full conformance with all the provisions of
538	           Section 10 of RFC 2026 except that the right to produce
539	           derivative works is not granted; or,</t>

541	           <t hangText="none:">indicating that the document is NOT
542	           offered in accordance with Section 10 of RFC 2026, and
543	           the author does not provide the IETF with any rights other
544	           than to publish as an Internet-Draft.</t>
545	       </list>

547	2.3.1.3 The figure Element

549	   The "figure" element groups an optional "preamble" element, an
550	   "artwork" element, and an optional "postamble" element together. The
551	   "figure" element also has an optional "anchor" attribute that is
552	   used for cross-referencing with the "xref" element (Section
553	   2.3.1.4). There is also an optional "title" attribute that
554	   identifies the title of the figure.

556	   The "preamble" and "postamble" elements, if present, are simply
557	   text. If a cross-reference is needed to a section, figure, or
558	   reference, the "xref" element (Section 2.3.1.4) is used; similarly,
559	   if an external-reference is needed, the "eref" element (Section
560	   2.3.1.5) is used. Indexing of text is provided by the the "iref"
561	   element (Section 2.3.1.6).

563	   The "artwork" element, which must be present, contains "ASCII
564	   artwork". Unlike text contained in the "t", "preamble", or
565	   "postamble" elements, both horizontal and vertical whitespace is
566	   significant in the "artwork" element.

568	   So, putting it all together, we have, e.g.,

570	       <figure anchor="figure_example">
571	           <preamble>So,
572	           putting it all together, we have, e.g.,</preamble>
573	           <artwork>
574	               ascii artwork goes here...

576	               be sure to use "&lt;" or "&amp;" instead of "<" and "&",
577	               respectively!
578	           </artwork>
579	           <postamble>which is a very simple example.</postamble>
580	       </figure>

582	   which is a very simple example.

584	   If you have artwork with a lot of "<" characters, then there's an
585	   XML trick you can use:

587	       <figure>
588	           <preamble>If you have artwork with a lot of "&lt;"
589	           characters, then there's an XML trick you can
590	           use:</preamble>
591	           <artwork><![CDATA[
592	               ascii artwork goes here...

594	               just don't use "]]" in your artwork!
595	           ]]></artwork>
596	           <postamble>The "&lt;![CDATA[ ... ]]>" construct is called
597	           a CDATA block -- everything between the innermost brackets
598	           is left alone by the XML application.</postamble>
599	       </figure>

601	   The "<![CDATA[ ... ]]>" construct is called a CDATA block --
602	   everything between the innermost brackets is left alone by the XML
603	   application.

605	   Because the "figure" element represents a logical grouping of text
606	   and artwork, an XML application producing a text version of the
607	   document should attempt to keep these elements on the same page.
608	   Because RFC 2223[2] allows no more than 69 characters by 49 lines of
609	   content on each page, XML applications should be prepared to
610	   prematurely introduce page breaks to allow for better visual
611	   grouping.

613	   Finally, the "artwork" element has two optional attributes: "name"
614	   and "type". The former is used to suggest a filename to use when
615	   storing the content of the "artwork" element, whilst the latter
616	   contains a suggestive data-typing for the content.

618	2.3.1.4 The xref Element

620	   The "xref" element is used to cross-reference sections, figures, and
621	   references. The mandatory "target" attribute is used to link back to
622	   the "anchor" attribute of the "section", "figure", and "reference"
623	   elements. The value of the "anchor" and "target" attributes should
624	   be formatted according to the token syntax in Section 2.1.

626	   If used as an empty element, e.g.,

628	       according to the token syntax in <xref target="xml_basics" />.

630	   then the XML application inserts an appropriate phrase during
631	   processing, such as "Section 2.1" or "<a href="#xml_basics">XML
632	   Basics</a>".

634	   If used with content, e.g.,

636	       conforming to <xref target="refs.RFC2223">RFC 2223</xref>.

638	   then the XML application inserts an appropriate designation during
639	   processing, such as "RFC 2223[2]" or "<a href="#refs.RFC2223">RFC
640	   2223</a>". Although the XML application decides what "an appropriate
641	   designation" might be, its choice is consistent throughout the
642	   processing of the document.

644	2.3.1.5 The eref Element

646	   The "eref" element is used to reference external documents. The
647	   mandatory "target" attribute is a URI[4], e.g.,

649	       <eref target="http://metalab.unc.edu/xml/">Cafe con Leche</eref>

651	   Note that while the "target" attribute is always present, the "eref"
652	   element may be empty, e.g.,

654	       <eref target="http://invisible.net/" />

656	   and the XML application inserts an appropriate designation during
657	   processing such as "[9]" or "<a
658	   href="http://invisible.net/">http://invisible.net/</a>".

660	2.3.1.6 The iref Element

662	   The "iref" element is used to add information to an index. The
663	   mandatory "item" attribute is the primary key the information is
664	   stored under, whilst the optional "subitem" attribute is the
665	   secondary key, e.g.,

667	       <iref item="indexing" subitem="how to" />

669	   Finally, note that the "iref" element is always empty -- it never
670	   contains any text.

672	2.3.1.7 The vspace Element

674	   The "vspace" element, which may occur only inside the "t" element,
675	   is used by the author to provide formatting guidance to the XML
676	   application. There is an attribute, "blankLines", that indicates the
677	   number of blank lines that should be inserted. A physical linebreak
678	   is specified by using the default value, "0".

680	   In addition, the "vspace" element can be used to force a new
681	   physical paragraph within a list item, e.g.,

683	       <list style="numbers">
684	           <t>This is list item.
685	              <vspace blankLines="1" />
686	              This is part of the same list item,
687	              although when displayed, it appears
688	              as a separate physical paragraph.</t>
689	       </list>

691	   An XML application producing a text version of the document should
692	   exercise care when encountering a value for "blankLines" that causes
693	   a pagebreak -- in particular, if a "vspace" element causes a
694	   pagebreak, then no further blank lines should be inserted. This
695	   allows authors to "force" a pagebreak by using an arbitrarily large
696	   value, e.g., "blankLines='100'".

698	   Finally, note that the "vspace" element is always empty -- it never
699	   contains any text.

701	2.4 Back matter

703	   Finally, the "back" element is used for references and appendices:

705	           ...
706	           </middle>
707	           <back>
708	               <references>
709	                   <reference ...>
710	                   <reference ...>
711	               </references>
712	               <section ...>
713	               <section ...>
714	           </back>
715	       </rfc>

717	   The "back" element consists of an optional "references" element,
718	   and, one or more optional "section" elements. The "back" element
719	   itself is optional, if your document doesn't have any references or
720	   appendices, you don't have to include it.

722	2.4.1 The references Element

724	   The "references" element contains the document's bibliography. It
725	   contains one or more "reference" elements.

727	   Each "reference" element contains a "front" element and one or more
728	   optional "seriesInfo" elements.

730	   We've already discussed the "front" element back in Section 2.2.

732	   The "seriesInfo" element has two attributes, "name" and "value" that
733	   identify the document series and series entry, respectively.

735	   The "reference" element has an optional "anchor" attribute that is
736	   used for cross-referencing with the "xref" element (Section
737	   2.3.1.4), e.g.,

739	       <reference anchor="refs.RFC2200">
740	           <front>
741	               <title>Internet Official Protocol Standards</title>
742	               <author initials="J." surname="Postel"
743	                       fullname="Jon Postel">
744	                   <organization abbrev="ISI">
745	                   USC/Information Sciences Institute
746	                   </organization>
747	               </author>

749	               <date month="June" year="1997" />
750	           </front>
751	           <seriesInfo name="RFC" value="2200" />
752	           <seriesInfo name="STD" value="1" />
753	       </reference>

755	   The "reference" element also has an optional "target" attribute that
756	   is used for external references (c.f., Section 2.3.1.5). The XML
757	   application, if producing an HTML version of the document will use
758	   the "target" attribute accordingly; however, if the "name" attribute
759	   of the "seriesInfo" element has the value "RFC", then the XML
760	   application should automatically provide an appropriate default for
761	   the "target" attribute (e.g., "http://example.com/rfcs/rfc2200.txt").

763	2.4.2 Appendices

765	   To include appendices after the bibliography, simply add more
766	   "section" elements. (For an example, look at the example at the
767	   beginning of Section 2.4.)

769	2.4.3 Copyright Status

771	   The copyright status for the document is not included in the
772	   document's markup -- this is automatically inserted by an XML
773	   application that produces either a text or HTML version of the
774	   document.

776	3. Processing the XML Source File

778	   This section concerns itself with applications that operate on an
779	   XML source file. A lot of XML tools are available, as are many lists
780	   of XML resources, e.g., Cafe con Leche[5].

782	   There are two kinds of XML tools: validating and non-validating.
783	   Both check that the source file conforms to the rules given in
784	   Section 2.1. However, in addition to making sure that the source
785	   file is well-formed, a validating tool also reads the DTD referenced
786	   by the source file to make sure that they match. There are a number
787	   of both validating and non-validating tools available.

789	3.1 Editing

791	   There are several XML editors available. Ideally, you want an editor
792	   that validates. This has two advantages:

794	   o  the editor provides guidance in fleshing-out the document
795	      structure; and,

797	   o  the editor validates that the source file matches the rules in
798	      the DTD.

800	   There are two major modes in Emacs that support XML: tdtd[6] and
801	   psgml[7]. The latter mode allows you to validate the source file (by
802	   calling an external program). If you visit the source file in Emacs
803	   and the major mode isn't "SGML" or "XML", then usually all it takes
804	   is adding these lines to your ".emacs" file:

806	       (setq auto-mode-alist
807	             (cons (cons "\\.xml$" 'sgml-mode) auto-mode-alist))

809	   and then restarting Emacs. If this doesn't work, try one of the
810	   sources above.

812	   The author uses both sgml-mode in Emacs, and a commercial validating
813	   editor, Clip! version 1.5[8], when editing source files.

815	3.1.1 Checking

817	   If your editor doesn't validate, then you should run a program to
818	   validate the source file.

820	   The author uses the AlphaWorks XML parser[9] for this purpose. It
821	   requires that your system have a Java virtual machine. In addition
822	   to Java, there are validating parsers written in C, Perl, Python,
823	   and Tcl.

825	3.2 Converting to Text Format

827	   The author has written the xml2rfc tool[10], which reads the source
828	   file and produces both a text and HTML version of the document.
829	   (This memo was produced using the xml2rfc tool.) Note that xml2rfc
830	   isn't a validating tool, so it's a good idea to use either a
831	   validating editor or run a stand-alone validating parser prior to
832	   using the tool.

834	3.3 Converting to HTML Format

836	   The XML Style Language (XSL) is used to describe transformations
837	   from the source file into some other structured file. So, ideally
838	   you should use an XSL-capable formatter to convert an XML source
839	   file to HTML.

841	   However, as of this writing XSL is still in considerable flux.
842	   (Hence, no reference was included in this memo, as by the time you
843	   read this section, the reference would be outdated.) So, in the
844	   interim, the author uses the xml2rfc tool for this purpose, even
845	   though this tool doesn't provide much flexibility in its HTML layout.

847	3.4 Viewing

849	   Browsers that support either XSL or Cascading Style Sheets (CSS) are
850	   able to view the source file directly.

852	   At present, the author doesn't use any of these browsers, instead
853	   converting source files to either text or HTML.

855	3.5 Searching

857	   As with text editors, any text-oriented search tool (e.g., grep) can
858	   be used on the source file. However, there are search tools
859	   available that understand structured source.

861	   The author uses sgrep version 1.9[11] for this purpose, e.g.

863	       sgrep -g xml 'ELEMENTS("title") not in ELEMENTS("back")' \
864	           writing-rfcs.xml

866	   which extracts the title element from the source file.

868	4. Security Considerations

870	   This memo raises no security issues; however, according to [2], your
871	   document should contain a section near the end that discusses the
872	   security considerations of the protocol or procedures that are the
873	   main topic of your document, e.g.,

875	       <middle>
876	           ...
877	           <section title="Security Considerations">
878	               <t>This memo raises no security issues;
879	               however,
880	               according to <xref target="refs.RFC2223" />,
881	               your document should contain a section near the end
882	               that discusses the security considerations of the
883	               protocol or procedures that are the main topic of your
884	               document.</t>
885	           </section>
886	       </middle>

888	References

890	   [1]  World Wide Web Consortium, "Extensible Markup Language (XML)
891	        1.0", W3C XML, February 1998.

893	   [2]  Postel, J., Reynolds, J., "Instructions to RFC Authors", RFC
894	        2223, October 1997.

896	   [3]  Bradner, S.O., "The Internet Standards Process -- Revision 3",
897	        RFC 2026, BCP 9, October 1996.

899	   [4]  Berners-Lee, T., Fielding, R.T., Masinter, L., "Uniform
900	        Resource Identifiers (URI): Generic Syntax", RFC 2396, August
901	        1998.

903	   [5]  http://metalab.unc.edu/xml/

905	   [6]  http://www.mulberrytech.com/tdtd/

907	   [7]  http://www.inria.fr/koala/plh/sxml.html

909	   [8]  http://www.t2000-usa.com/

911	   [9]  http://www.alphaworks.ibm.com/formula/xml/

913	   [10]  http://memory.palace.org/authoring/

915	   [11]  http://www.cs.helsinki.fi/~jjaakkol/sgrep.html

917	Author's Address

919	   Marshall T. Rose
920	   Invisible Worlds, Inc.
921	   660 York Street
922	   San Francisco, CA  94110
923	   US

925	   Phone: +1 415 695 3975
926	   EMail: mrose@not.invisible.net
927	   URI:   http://invisible.net/

929	Appendix A. The rfc Element

931	   The "<rfc>" tag at the beginning of the file, with only an "ipr"
932	   attribute (Section 2.2.7.1), produces an Internet-Draft. However,
933	   when other attributes are added to this tag by the RFC editor, an
934	   RFC is produced, e.g.,

936	       <rfc number="2200"
937	            obsoletes="2000, 1920, 1880, 1800, ..."
938	            category="std"
939	            seriesNo="1">

941	   At a minimum, the "number" attribute should be present.

943	   The other attributes are:

945	   o  "obsoletes", having a comma-separated list of RFC numbers, that
946	      the document obsoletes;

948	   o  "updates", having a comma-separated list of RFC numbers, that the
949	      document updates;

951	   o  "category", having one of these values:

953	      1.  "std", for a Standards-Track document;

955	      2.  "bcp", "for a Best Current Practices document;

957	      3.  "exp", for an Experimental Protocol document;

959	      4.  "historic", for a historic document; or,

961	      5.  "info", the default, for an Informational document.

963	   o  "seriesNo", having the corresponding number in the STD (std), BCP
964	      (bcp), or FYI (info) series.

966	   Finally, a special entity, "&rfc.number;", is available. Authors
967	   preparing an RFC should use this entity whenever they want to
968	   reference the number of the RFC within the document itself. In
969	   printed versions of the document, the appropriate substitution (or
970	   "XXXX") will occur.

972	Appendix B. The RFC DTD

974	   <!--
975	     DTD for the RFC document series, draft of 99-01-30
976	     -->

978	   <!--
979	     Contents

981	       DTD data types

983	       The top-level

985	       Front matter

987	       The Body

989	       Back matter
990	     -->

992	   <!--
993	     DTD data types:

995	           entity        description
996	           ======        ===============================================
997	           NUMBER        [0-9]+
998	           NUMBERS       a comma-separated list of NUMBER

1000	           DAY           the day of the month, e.g., "1"
1001	           MONTH         the month of the year, e.g., "January"
1002	           YEAR          a four-digit year, e.g., "1999"

1004	           URI           e.g., "http://invisible.net/"

1006	           ATEXT/CTEXT   printable ASCII text (no line-terminators)

1008	           TEXT          character data
1009	     -->

1011	   <!ENTITY % NUMBER     "CDATA">
1012	   <!ENTITY % NUMBERS    "CDATA">

1014	   <!ENTITY % DAY        "CDATA">
1015	   <!ENTITY % MONTH      "CDATA">
1016	   <!ENTITY % YEAR       "CDATA">
1017	   <!ENTITY % URI        "CDATA">

1019	   <!ENTITY % ATEXT      "CDATA">
1020	   <!ENTITY % CTEXT      "#PCDATA">

1022	   <!ENTITY % TEXT       "#PCDATA">

1024	   <!ENTITY   rfc.number "XXXX">

1026	   <!--
1027	     The top-level
1028	     -->

1030	   <!--
1031	     attributes for the "rfc" element are supplied by the RFC
1032	     editor. when preparing drafts, authors should leave them blank.

1034	     the "seriesNo" attribute is used if the category is, e.g., BCP.
1035	     -->
1036	   <!ELEMENT rfc         (front,middle,back?)>
1037	   <!ATTLIST rfc
1038	             number      %NUMBER;           #IMPLIED
1039	             obsoletes   %NUMBERS;          ""
1040	             updates     %NUMBERS;          ""
1041	             category    (std|bcp|info|exp|historic)
1042	                                            "info"
1043	             seriesNo    %NUMBER;           #IMPLIED
1044	             ipr         (full2026|noDerivativeWorks2026|none)
1045	                                            #IMPLIED
1046	             docName     %ATEXT;            #IMPLIED>

1048	   <!--
1049	     Front matter
1050	     -->

1052	   <!ELEMENT front       (title,author+,date,area*,workgroup*,keyword*,
1053	                          abstract?,note*)>

1055	   <!-- the "abbrev" attribute is used for headers, etc. -->
1056	   <!ELEMENT title       (%CTEXT;)>
1057	   <!ATTLIST title
1058	             abbrev      %ATEXT;            #IMPLIED>

1060	   <!ELEMENT author      (organization,address?)>
1061	   <!ATTLIST author
1062	             initials    %ATEXT;            #IMPLIED
1063	             surname     %ATEXT;            #IMPLIED
1064	             fullname    %ATEXT;            #IMPLIED>

1066	   <!ELEMENT organization
1067	                         (%CTEXT;)>
1068	   <!ATTLIST organization
1069	             abbrev      %ATEXT;            #IMPLIED>

1071	   <!ELEMENT address     (postal?,phone?,facsimile?,email?,uri?)>

1073	   <!-- at most one of each the city, region, code, and country
1074	        elements may be present -->
1075	   <!ELEMENT postal      (street+,(city|region|code|country)*)>
1076	   <!ELEMENT street      (%CTEXT;)>
1077	   <!ELEMENT city        (%CTEXT;)>
1078	   <!ELEMENT region      (%CTEXT;)>
1079	   <!ELEMENT code        (%CTEXT;)>
1080	   <!ELEMENT country     (%CTEXT;)>
1081	   <!ELEMENT phone       (%CTEXT;)>
1082	   <!ELEMENT facsimile   (%CTEXT;)>
1083	   <!ELEMENT email       (%CTEXT;)>
1084	   <!ELEMENT uri         (%CTEXT;)>

1086	   <!ELEMENT date        EMPTY>
1087	   <!ATTLIST date
1088	             day         %DAY;              #IMPLIED
1089	             month       %MONTH;            #REQUIRED
1090	             year        %YEAR;             #REQUIRED>

1092	   <!-- meta-data... -->
1093	   <!ELEMENT area        (%CTEXT;)>
1094	   <!ELEMENT workgroup   (%CTEXT;)>
1095	   <!ELEMENT keyword     (%CTEXT;)>

1097	   <!ELEMENT abstract    (t)+>
1098	   <!ELEMENT note        (t)+>
1099	   <!ATTLIST note
1100	             title       %ATEXT;            #REQUIRED>

1102	   <!--
1103	     The body
1104	     -->

1106	   <!ELEMENT middle      (section)+>

1108	   <!ELEMENT section     (t|figure|section)*>
1109	   <!ATTLIST section
1110	             anchor      ID                 #IMPLIED
1111	             title       %ATEXT;            #REQUIRED>

1113	   <!ELEMENT t           (%TEXT;|list|figure|xref|eref|iref|vspace)*>
1114	   <!ATTLIST t
1115	             hangText    %ATEXT;            #IMPLIED>

1117	   <!-- the value of the style attribute is inherited from the closest
1118	        parent -->
1119	   <!ELEMENT list        (t+)>
1120	   <!ATTLIST list
1121	             style       (numbers|symbols|hanging|empty)
1122	                                            "empty">

1124	   <!ELEMENT xref        (%CTEXT;)>
1125	   <!ATTLIST xref
1126	             target      IDREF              #REQUIRED
1127	             pageno      (true|false)       "false">

1129	   <!ELEMENT eref        (%CTEXT;)>
1130	   <!ATTLIST eref
1131	             target      %URI;              #REQUIRED>

1133	   <!ELEMENT iref        EMPTY>
1134	   <!ATTLIST iref
1135	             item        %ATEXT;            #REQUIRED
1136	             subitem     %ATEXT;            "">

1138	   <!ELEMENT vspace      EMPTY>
1139	   <!ATTLIST vspace
1140	             blankLines  %NUMBER;           "0">

1142	   <!ELEMENT figure      (preamble?,artwork,postamble?)>
1143	   <!ATTLIST figure
1144	             anchor      ID                 #IMPLIED
1145	             title       %ATEXT;            "">

1147	   <!ELEMENT preamble    (%TEXT;|xref|eref|iref)*>
1148	   <!ELEMENT artwork     (%TEXT;)*>
1149	   <!ATTLIST artwork
1150	             xml:space   (default|preserve) "preserve">
1151	   <!ELEMENT postamble   (%TEXT;|xref|eref|iref)*>

1153	   <!--
1154	     Back matter
1155	     -->

1157	   <!-- sections, if present, are appendices -->
1158	   <!ELEMENT back        (references?,section*)>

1160	   <!ELEMENT references  (reference+)>
1161	   <!ELEMENT reference   (front,seriesInfo*)>
1162	   <!ATTLIST reference
1163	             anchor      ID                 #IMPLIED
1164	             target      %URI;              #IMPLIED>
1165	   <!ELEMENT seriesInfo  EMPTY>
1166	   <!ATTLIST seriesInfo
1167	             name        %ATEXT;            #REQUIRED
1168	             value       %ATEXT;            #REQUIRED>

1170	Appendix C. Acknowledgements

1172	   The author gratefully acknowledges the contributions of: Alan
1173	   Barrett, Brad Burdick, Brian Carpenter, Steve Deering, Patrik
1174	   Faltstrom, Jim Gettys, Carl Malamud, Chris Newman, Kurt Starsinic,
1175	   and, Frank Strauss.

1177	Appendix D. Revision History

1179	   RFC Editor: please remove this section prior to publication.

1181	D.1 Changes since 01

1183	   addition: The "day" attribute (Section 2.2.3).

1185	   change: The ipr2026 (Section 2.2.7.1) attribute is now called "ipr",
1186	      and the values have changed.

1188	   addition: The artwork (Section 2.3.1.3) element has two optional
1189	      attributes: "name" and "type".

1191	   change: The seriesInfo (Section 2.4.1) attribute is now an empty
1192	      element and has two mandatory attributes: "name" and "value".

1194	D.2 Changes since 00

1196	   clarification: Elements within the the "address" element (Section
1197	      2.2.2) should not be re-ordered.

1199	   addition: The "docName" attribute (Section 2.2.7.1).

1201	   change: The the "figure" element (Section 2.3.1.3) may now nest
1202	      within the "t" element.

1204	   addition: The "iref" element (Section 2.3.1.6).

1206	Index

1208	I
1209	   indexing
1210	      how to  16

1212	Full Copyright Statement

1214	   Copyright (C) The Internet Society (1999).  All Rights Reserved.

1216	   This document and translations of it may be copied and furnished to
1217	   others, and derivative works that comment on or otherwise explain it
1218	   or assist in its implmentation may be prepared, copied, published
1219	   and distributed, in whole or in part, without restriction of any
1220	   kind, provided that the above copyright notice and this paragraph
1221	   are included on all such copies and derivative works.  However, this
1222	   document itself may not be modified in any way, such as by removing
1223	   the copyright notice or references to the Internet Society or other
1224	   Internet organizations, except as needed for the purpose of
1225	   developing Internet standards in which case the procedures for
1226	   copyrights defined in the Internet Standards process must be
1227	   followed, or as required to translate it into languages other than
1228	   English.

1230	   The limited permissions granted above are perpetual and will not be
1231	   revoked by the Internet Society or its successors or assigns.

1233	   This document and the information contained herein is provided on an
1234	   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
1235	   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
1236	   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
1237	   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
1238	   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.