rfc2629.txt

来自「RFC 的详细文档！」· 文本 代码 · 共 1,740 行 · 第 1/4 页

Network Working Group                                            M. Rose
Request for Comments: 2629                        Invisible Worlds, Inc.
Category: Informational                                        June 1999


                    Writing I-Ds and RFCs using XML

Status of this Memo

   This memo provides information for the Internet community.  It does
   not specify an Internet standard of any kind.  Distribution of this
   memo is unlimited.

Copyright Notice

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

Abstract

   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.





























Rose                         Informational                      [Page 1]

RFC 2629            Writing I-Ds and RFCs using XML            June 1999


Table of Contents

   1.      Introduction . . . . . . . . . . . . . . . . . . . . . . .  3
   2.      Using the DTD to Write I-Ds and RFCs . . . . . . . . . . .  4
   2.1     XML basics . . . . . . . . . . . . . . . . . . . . . . . .  4
   2.2     Front matter . . . . . . . . . . . . . . . . . . . . . . .  6
   2.2.1   The title Element  . . . . . . . . . . . . . . . . . . . .  6
   2.2.2   The author Element . . . . . . . . . . . . . . . . . . . .  7
   2.2.3   The date Element . . . . . . . . . . . . . . . . . . . . .  8
   2.2.4   Meta Data Elements . . . . . . . . . . . . . . . . . . . .  8
   2.2.5   The abstract Element . . . . . . . . . . . . . . . . . . .  9
   2.2.6   The note Element . . . . . . . . . . . . . . . . . . . . .  9
   2.2.7   Status, Copyright Notice, Table of Contents  . . . . . . .  9
   2.2.7.1 Conformance with RFC 2026  . . . . . . . . . . . . . . . .  9
   2.2.8   Everything in the Front  . . . . . . . . . . . . . . . . . 10
   2.3     The Middle . . . . . . . . . . . . . . . . . . . . . . . . 11
   2.3.1   The section Element  . . . . . . . . . . . . . . . . . . . 11
   2.3.1.1 The t Element  . . . . . . . . . . . . . . . . . . . . . . 12
   2.3.1.2 The list Element . . . . . . . . . . . . . . . . . . . . . 12
   2.3.1.3 The figure Element . . . . . . . . . . . . . . . . . . . . 13
   2.3.1.4 The xref Element . . . . . . . . . . . . . . . . . . . . . 15
   2.3.1.5 The eref Element . . . . . . . . . . . . . . . . . . . . . 15
   2.3.1.6 The iref Element . . . . . . . . . . . . . . . . . . . . . 16
   2.3.1.7 The vspace Element . . . . . . . . . . . . . . . . . . . . 16
   2.4     Back matter  . . . . . . . . . . . . . . . . . . . . . . . 17
   2.4.1   The references Element . . . . . . . . . . . . . . . . . . 17
   2.4.2   Appendices . . . . . . . . . . . . . . . . . . . . . . . . 18
   2.4.3   Copyright Status . . . . . . . . . . . . . . . . . . . . . 18
   3.      Processing the XML Source File . . . . . . . . . . . . . . 19
   3.1     Editing  . . . . . . . . . . . . . . . . . . . . . . . . . 19
   3.1.1   Checking . . . . . . . . . . . . . . . . . . . . . . . . . 19
   3.2     Converting to Text Format  . . . . . . . . . . . . . . . . 20
   3.3     Converting to HTML Format  . . . . . . . . . . . . . . . . 20
   3.4     Viewing  . . . . . . . . . . . . . . . . . . . . . . . . . 20
   3.5     Searching  . . . . . . . . . . . . . . . . . . . . . . . . 20
   4.      Security Considerations  . . . . . . . . . . . . . . . . . 21
           References . . . . . . . . . . . . . . . . . . . . . . . . 22
           Author's Address . . . . . . . . . . . . . . . . . . . . . 22
   A.      The rfc Element  . . . . . . . . . . . . . . . . . . . . . 23
   B.      The RFC DTD  . . . . . . . . . . . . . . . . . . . . . . . 24
   C.      Acknowledgements . . . . . . . . . . . . . . . . . . . . . 29
   Index  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
   Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 31








Rose                         Informational                      [Page 2]

RFC 2629            Writing I-Ds and RFCs using XML            June 1999


1. Introduction

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

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

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

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

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

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

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

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




















Rose                         Informational                      [Page 3]

RFC 2629            Writing I-Ds and RFCs using XML            June 1999


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

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

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

2.1 XML basics

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

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

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

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

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

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

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

       <?xml version="1.0"?>
       <!DOCTYPE rfc SYSTEM "rfc2629.dtd">
       <rfc>
           ...
       </rfc>

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

   Second, make sure that all elements are properly matched and nested.



Rose                         Informational                      [Page 4]

RFC 2629            Writing I-Ds and RFCs using XML            June 1999


   A properly matched element that starts with "<example>" is eventually
   followed with "</example>". (Empty elements are always matched.)
   Elements are properly nested when they don't overlap.

   For example,

       <outer>
           ...
           <inner>
               ...
           </inner>
           ...
       </outer>

   is properly nested.

   However,

       <outer>
           ...
           <inner>
               ...
           </outer>
           ...
       </inner>

   overlaps, so the elements aren't properly nested.

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

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

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

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

   Finally, XML is case sensitive.





Rose                         Informational                      [Page 5]

RFC 2629            Writing I-Ds and RFCs using XML            June 1999


2.2 Front matter

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

       <?xml version="1.0"?>
       <!DOCTYPE rfc SYSTEM "rfc2629.dtd">
       <rfc>
           <front>
               <title ...>
               <author ...>
               <author ...>
               <date ...>
               <area ...>
               <workgroup ...>
               <keyword ...>
               <keyword ...>
               <abstract ...>
               <note ...>
           </front>
           ...
       </rfc>

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

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

2.2.1 The title Element

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

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










Rose                         Informational                      [Page 6]

RFC 2629            Writing I-Ds and RFCs using XML            June 1999


2.2.2 The author Element

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

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

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

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

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

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

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

       <postal>
           <street>660 York Street</street>
           <street>M/S 40</street>
           <city>San Francisco</city> <region>CA</region>
           <code>94110</code>
           <country>US</country>
       </postal>

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





Rose                         Informational                      [Page 7]

RFC 2629            Writing I-Ds and RFCs using XML            June 1999


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

       <phone>[phone]</phone>
       <email>[e-mail]</email>
       <uri>http://invisible.net/</uri>

2.2.3 The date Element

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

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

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

2.2.4 Meta Data Elements

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

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

       <area>General</area>
       <workgroup>RFC Beautification Working Group</workgroup>
       <keyword>RFC</keyword>
       <keyword>Request for Comments</keyword>
       <keyword>I-D</keyword>
       <keyword>Internet-Draft</keyword>
       <keyword>XML</keyword>
       <keyword>Extensible Markup Language</keyword>

   The "area" elements identify a general category for the document
   (e.g., one of "Applications", "General", "Internet", "Management",
   "Operations", "Routing", "Security", "Transport", or "User"), while
   the "workgroup" elements identify the IETF working groups that