rfc2629.txt

283个中文RFC文档

           <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>
           <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.</t>
           </abstract>
       </front>

2.3 Middle

   "middle" 元素包含文档的除参考书目和附录之外的所有章节:

       ...
       </front>
       <middle>
           <section ...>
           <section ...>
           <section ...>
       </middle>
       <back>
       ...

   "middle" 元素包含一个或多个"section" 元素s.

2.3.1 section 元素

每一个"section" 元素包含了文档的一个章节. 有一个必须的属性,就是 "title",标识了该章节的
标题.还有一个可选的属性"anchor", 它和 "xref" 元素一起使用,以能进行联结. (见 2.3.1.4),
   例:

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

   "section" 元素是可以递归的 – 每一个元素可以包含以下 "t", "figure", 和 "section" 元素的
任意组合,如,

       <section title="The Middle">
           ...
           <section title="section 元素">
               ...
               <section title="t 元素">...</section>
               <section title=" list 元素">...</section>
               <section title=" figure 元素">...</section>
               <section title="xref 元素">...</section>
               <section title=" eref 元素">...</section>
               <section title=" iref 元素">...</section>
           </section>
       </section>

2.3.1.1 t 元素

"t" 元素可包含任意段落,列表和图片的组合. 如果在章节,图片或者参考中需要有交叉联结
(cross-reference),则可以使用 "xref" 元素 (见2.3.1.4) ;同样,如果有外部联结,则使用"eref" 元
素(见 2.3.1.5). "iref" 元素可以提供文本的索引 (见 2.3.1.6).

2.3.1.2 list 元素

   "list" 元素包含一个或多个条目.每一个条目是一个 "t" 元素, 允许递归, 如,

       <list style="numbers">
           <t>The pfirst item.</t>
           <t>The second item, which contains two bulleted sub-items:
               <list style="symbols">
                   <t>The first sub-item.</t>
                   <t>The second sub-item.</t>
               </list>
           </t>
       </list>

    "list" 元素有一个可选的属性"style",其值可以为"numbers" (数值型列表), "symbols" ( 子弹
型列表),   "hanging" (悬挂型列表), 或, "empty" (锯齿型列表). 如果 "list" 元素是嵌套的,它的
缺省值来自于它最近的父元素,否则它的缺省值是 "empty".

    嵌套了"hanging list" 元素时, "t" 元素有一个可选属性 "hangText",它标识了被插入的文本, 
如:

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

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

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

2.3.1.3  figure 元素

    "figure" 元素组合了一个可选的"preamble" 元素, 一个"artwork" 元素, 及一个可选的
"postamble" 元素."figure" 元素还有一个可选的属性 "anchor" ,它和 "xref" 元素一起使用用来进
行交叉联结 (见 2.3.1.4).它还有一个可选属性,用来标识图片的标题.

   "preamble和 "postamble" 元素如果出现,只是简单的文本. 如果在章节,图片或者参考中需要有交
叉联结(cross-reference),则可以使用 "xref" 元素 (见2.3.1.4) ;同样,如果有外部联结,则使用
"eref" 元素(见 2.3.1.5). "iref" 元素可以提供文本的索引 (见 2.3.1.6).

   "artwork" 元素是必需的,它包含 "ASCII artwork". 它不象在"t", "preamble",或 "postamble" 元
素中包含文本, "artwork" 元素中水平和垂直的whitespace 都是有意义的.

   现在, 把它们连在一起,我们有下例,
       <figure anchor="figure_example">
           <preamble>So,
           putting it all together, we have, e.g.,</preamble>
           <artwork>
               ascii artwork goes here...

               be sure to use "&lt;" or "&amp;" instead of "<" and "&",
               respectively!
           </artwork>
           <postamble>which is a very simple example.</postamble>
       </figure>
这只是一个很简单的例子.

    如果你的作品中有很多 "<"符号,有一种XML技巧可以使用:
       <figure>
           <preamble>If you have artwork with a lot of "&lt;"
           characters, then there's an XML trick you can
           use:</preamble>
           <artwork><![CDATA[
               ascii artwork goes here...

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

    这里 "<![CDATA[ ... ]]>" 构造了一种 CDATA 节 –最里面的括号之间的所有内容,XML应用程序
都将进行单独处理.
    因为"figure" 元素描述了文本或者作品的逻辑组合, XML应用程序生成的文本中在同一页必须保
持这些相同的元素.
    因为 RFC 2223 [2] 只允许一页不超过49行,一行不超过69字符. 为了页面的美观,XML应用程序
应该应能适当做好断页工作.
    最后,"artwork" 元素有两个可选属性: "name"和 "type". 前者用来表示"artwork" 元素间内容的
名称,而后者用来表示其内容的数据类型.

2.3.1.4 xref 元素

     "xref" 元素用来在章节,图片和参考间进行交叉联结.其必须属性 "target"用来联结到
"section", "figure", 或"reference"元素中的"anchor"属性. "anchor"的值和"target"属性必须符合 
2.1节的语法规定.

    如果作为一个空元素使用,如:

根据标志语法 <xref target="xml_basics" />.

    则XML应用程序在处理中插入适当短语,比如"Section 2.1" 或 "<a href="#xml_basics">XML
   Basics</a>".

    如果有内容,如,

       顺应 <xref target="refs.RFC2223">RFC 2223</xref>.

   则XML应用程序在处理中插入适当名称, 比如 "RFC 2223 [2]" 或 "<a href="#refs.RFC2223">RFC
   2223</a>". 虽然这里的" 适当名称"是由XML应用程序决定的,它的选择在文档处理过程中是保持
一致的.

2.3.1.5 eref 元素

   "eref" 元素用来说明外部文档.有一个必须属性 "target",它是一个URI [4], 例,

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

注意"target"属性是必须有的,但"eref"元素却可以是空元素,例:

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

    在处理中XML应用程序会插入适当指示,如"[9]" 或是 "<a
   href="http://invisible.net/">http://invisible.net/</a>".

2.3.1.6 iref 元素

iref" 元素用来给索引增添信息,其必须属性"item"是所存放信息的主键, 而可选属性 "subitem"
是第二键.例:
       <iref item="indexing" subitem="how to" />

    最后,注意 "iref" 元素总是空的 – 它从不会包含任何文本内容.

2.3.1.7 vspace 元素

"vspace" 元素可能只会在出现在 "t" 元素内,作者用来给出XML应用程序的格式设定.有一个属性, 
"blankLines",表示应插入的空行数.如果用缺省值 "0"表示物理空行.

    另外,"vspace" 元素可用来在列表项目中强制产生一物理段落, 如:

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

    XML应用程序生成文本文档时需进行仔细实践,当遇到 "blankLines"值时可能会引起分页. – 在
极端情况下, 如果 "vspace" 元素产生分页,则不能再插入空行. 这就允许作者通过使用一些大的属性
值来"强制"产生分页.例: "blankLines='100'".

    最后,注意 "vspace" 元素总是空的 – 它从不包含任何文本内容.

2.4 Back matter

    最后, back" 元素用来显示参考附录:

           ...
           </middle>
           <back>
               <references>
                   <reference ...>
                   <reference ...>
               </references>
               <section ...>
               <section ...>
           </back>
       </rfc>

    back" 元素包含可选的"references" 元素, 已及一个或多个可选的 "section" 元素. "back" 元
素本身也是可选的,如果你的文档中没有什么参考或者附录的话,就不需要包括它.

2.4.1 references 元素

"references" 元素包含了文档的参考书目.它包含一个或多个"reference" 元素.每一个
"reference" 元素包含一个"front" 元素及一个或多个可选的"seriesInfo" 元素.   我们已经在2.2
章中讨论了 "front" 元素."seriesInfo" 元素有两个属性, "name" 和"value" 分别标识了文档的序列
条目.

    "reference" 元素有一个可选的"anchor"属性,和 "xref" 元素 (Section 2.3.1.4)一起用于联结,
   如:

       <reference anchor="refs.RFC2200">
           <front>
               <title>Internet Official Protocol Standards</title>
               <author initials="J." surname="Postel"
                       fullname="Jon Postel">
                   <organization abbrev="ISI">
                   USC/Information Sciences Institute
                   </organization>
               </author>

               <date month="June" year="1997" />
           </front>
           <seriesInfo name="RFC" value="2200" />
           <seriesInfo name="STD" value="1" />
       </reference>

    "reference" 元素还有一个可选的"target"属性用于内部参照 (见 2.3.1.5). XML应用程序如果
产生HTML文档则会相应用到"target"属性; 当然,如果"seriesInfo" 元素的"name" 属性有 "RFC"值的
话,那 XML应用程序应自动为"target"属性提供一最佳值
(如,"http://example.com/rfcs/rfc2200.txt").

2.4.2 附录

要在参考书目之后加入附录,只需简单的增加多个"section" 元素. (举个例子,请看2.4.章开头的
例子)

2.4.3 版权申明

文档的版权申明包括在文档的结构中 -- XML应用程序在产生文本文件或HTML文件时会自动插入.

3. 处理XML源文件

    本章重点是关于XML源文件操作的应用程序. 有大量XML工具可以获得,参见Cafe con Leche [5].

    有两类 XML 工具: 可检查类与非检查类.两类都对源文件进行语法检查(2.1所述语法). 然而,为
了保证源文件是结构良好的,一些补充的类工具可以检查 DTD 参照是否与文件匹配.可以获得很多检查
和非检查类的工具.

3.1 编辑

    有一些 XML编辑器可以获取.一个理想的编辑器应该可以进行检查.有两类标签:

   o  编辑器可以列出整个文档的结构; 并且:

   o  编辑器可以确认源文件DTD 是否符合语法规则.

    Emacs 对XML的支持主要有两种模式: tdtd [6] 和 psgml [7]. 后一种模式允许你对源文件进行
确认. (通过调用一内部程序).如果你访问Emacs中的源文件而且其主模式不是"SGML" 或 "XML", 那么
通常它是把这些行加到".emacs" 文件中:

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

    然后重启动Emacs. 如果不行,试一下上面的源程序.

    作者在编辑源程序时在Emacs中使用了所有两种sgml模式,编辑器是一种商业化编辑器 Clip!,版
本是1.5[8].

3.1.1 检查

    如果编辑器不能进行检查,那就要运行程序来检查源文件.

    作者为此使用了 AlphaWorks XML parser [9].它需要你的系统里有Java虚拟机.除了Java,他还
能检查 C, Perl, Python, 和 Tcl.

3.2 转换为文本模式

作者曾写过一个工具:xml2rfc [10],它可以读源文件并产生文本格式和HTML格式的版本.
    (本章程就是用 xml2rfc 处理的.)注意到xml2rfc不是一个检查工具, 所以最好使用一个可检查的
编辑器或者是运行一个解析工具.

3.3 转换为HTML格式

    XML 类型语言(XSL)用来描述如何将源文件转换为其他格式的文件. 所以最好使用支持 XSL的格式
化器以便将XML源文件转换为HTML格式.

    然而, XSL 技术还没有完全成型.(所以本文档资料内没有包含这方面的参考资料,因为也许在你看
到时就已经过时了.) 所以作为临时过渡,作者使用了 xml2rfc 工具,虽然它在 HTML 布局方面没有提供
太大的余地.

3.4 预览

支持 XSL 或CSS的流览器可以直接预览源文件.

    当前,作者没有使用任何流览器, 没有将源文件转换为文本或HTML格式.

3.5 查找

    作为文本编辑器,所有的文本查找工具 (如, grep) 都可以在源文件中使用.当然,有一些可阅读结
构化源程序的的查找工具可以获得.

    作者为此使用了 sgrep,版本为 1.9 [11], 如下:

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