Gentoo Linux XML 指南

来源：作者：出处：巧巧读书 2007-10-09 进入讨论组

　　内容简介：这个指南会告诉你怎样用轻量级的Gentoo GuideXML语法来创作网页式文档。这个语法是Gentoo Linux文档的官方格式，并且这个文档本身就是用GuideXML创建的。这个文档需要有对XML和HTML基本的了解。

　　1. Guide XML的基本知识

　　Guide XML的设计目标

　　这个Guide XML的语法是轻量级的，但确是很丰富的，因此学习和提供我们编写网页式文档所需特性是很容易的。标签的数目尽量保持最少，就只是那些我们需要的。这使得将Guide XML转还为其他格式也很容易，如DocBook, XML/SGML，或者直接用于网络的HTML格式。

　　设计的目标是让创建和转换Guide XML文档更容易。

　　更多的资源

　　如果你打算为Gentoo贡献一些文档，或者你要测试GuideXML，请阅读文档开发技巧，这个包含了文档开发的一些技巧和小戏法。

　　2. Guide XML

　　基本的结构

　　现在你知道怎样转换Guide XML了，你将开始学习GuideXML语法。我们将从一个Guide XML文档的初始化标签开始：

　　代码 2.1: 一个Guide XML文档的初始化部分

<?xml version='1.0' encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<guide link="relative_link_to_your_guide">
<title>Gentoo Linux Documentation Guide</title>
<author title="Chief Architect">
　<mail link="drobbins@gentoo.org">Daniel Robbins</mail>
</author>
<author title="Editor">
　<mail link="thomasfl@gentoo.org">Thomas Flavel</mail>
</author>
<abstract>
这个指南告诉你怎样用我们最新的轻量级的Gentoo GuideXML语法来创建网页式文档。
这个语法是Gentoo Linux网页式文档的官方格式，并且这个文档本身就是用GuideXML创建的。
</abstract>
<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
<license/>
<version>1.0</version>
<date>29 Mar 2001</date>

　　在第一行，我们看到表明此文档为XML文档的这个必须的标签。后面接着的，有一个<guide>标签 -- 这个文档都包含在<guide> </guide>标签对里。接着，有一个<title>标签，用来设定整个文档的标题。

　　接着，我们看到了标签<author>，这里包含了这个文档各个作者的信息。每个<author>标签允许有一个可选的元素title=，用来说明作者和文档的关系（作者，共同作者，编辑，等等）。在这个特定的例子中，作者的名字用另外一个标签<mail>围起来，用来说明指定人的email地址。标签<mail>是可选和可忽略的，每个指南文档都需要不少于一个<author>元素。

　　然后，我们来看看标签<abstract>，<version>和<date>，这些是用来描述这个文档的概要、版本和当前版本的日期（格式：DD MMM YYYY）。这些丰富了应该出现在一个Guide文档开始的标签。除开标签<title>和<mail>，这些标签不应随意出现在文档的任何地方，除非在标签<guide>之后的地方，并且为了一致性，推荐（并不是必须的）这些标签出现文档内容的前面。

　　最后我们看看标签<license/>，用来在Creative Commons - Attribution / Share Alike协议下发行此文档，这是由Documentation Policy所必须的。

　　段落和章节

　　一旦初始化的标签设定好以后，你就可以准备往这个文档添加结构性元素。Guide文档分为章，每章有一个或多个节组成。每章节都有一个标题。这里有一个只有一节的章的例子，包含了几个段落。如果你将这个XML追加到previous excerpt的XML里，并追加</guide>到这个文件的最后，你将获得一个合法的（虽然很小）的Guide文档：

　　代码 2.2

<chapter>
<title>这是我的一章</title>
<section>
<title>这是我一章中的一节</title>
<body>
<p>
这是一节中的实际内容。
</p>
</body>
</section>
</chapter>

　　在上面，我通过增加一个子元素<title>到元素<chapter>设定章的主题。然后，我通过增加一个元素<section>新增一个节。如果你看看元素<section>里面，你将发现他有两个子元素：一个<title>和一个<body>。标签<title>我们不再陌生了，标签<body> 包含了特定节的实际文本内容。我们来看看允许出现在元素<body>里的标签。

　　注释：元素<guide>可以包含多个<chapter>元素，一个<chapter>可以包含多个元素<section>。但是一个特定的元素<section>只能包含一个元素<body>。

　　一个<body>的例子

　　现在，我们该学学怎么标记实际内容了。这是一个元素<body>XML代码的例子：

　　代码 2.3

<p>
这是一个段落　<path>/etc/passwd</path> 是一个文件。<uri>http://www.gentoo.org</uri>
是我喜欢的网站地址。输入 <c>ls</c> 如果你喜欢他。我现在<e>真</e>的要睡了。
</p>
<pre>
这是文本输出或代码。
# <i>这是用户的输入</i>
选择性的使用强调让HTML/XML阅读起来更人性化：
<foo><i>bar</i></foo>
<codenote>这是在代码块中插入内部注解的方法</codenote>
</pre>
<note>
这是一个注解。
</note>
<warn>
这是一个警告。
</warn>
<impo>
这很重要。
</impo>

　　现在，看看元素<body>是怎样工作的：

　　这是一个段落。/etc/passwd是一个文件。http://www.gentoo.org是我喜欢的网站地址。输入ls如果你喜欢他。我现在真的要睡了。

　　代码 2.4

这是文本输出或代码。
# 这是用户的输入
选择性的使用强调让HTML/XML阅读起来更人性化。
<foo>bar</foo>
// 这是在代码块中插入内部注解的方法

　　注释：这是一个注解。

　　警告：这是一个警告。

　　重要：这很重要。

　　标签<body>

　　在上一节中，我们介绍了不少新的标签，这里也是你需要知道的。标签<p>（段落），<pre>（代码块）<note>, <warn>（警告）和<impo>（重要的）都可以包含一行或多行文本。除开元素<table>（我们呆会也会讲到）外，这些标签都应该出现在元素<body>里。另外，这些标签不应该堆起来，也就是说，不可以把一个元素<note>放在一个元素<p>里。你可能会猜到，元素<pre>可以准确的保留里面的空格，使得对代码编写摘录非常合适，你也可以给标签<pre>一个标题：

　　代码 2.5: 有标题的<pre>

<pre caption = "Output of uptime">
# <i>uptime</i>
16:50:47 up 164 days,　2:06,　5 users,　load average: 0.23, 0.20, 0.25
</pre>

　　元素<path>，<c>和<e>可以在任何一个子标签<body>里使用，但在标签<pre>里除外。

　　元素<path>是用来标记为磁盘上的文件的文本，不管是绝对或相对路径，或者一个简单的文件名都适合。这个元素一般情况下是用一种monospace字体来将他和标准段落的排版方式区别开。

　　元素<c>是用来标记一个命令或者用户的输入。想到<c>是一种提醒读者这是一种他们可以输入的，这会起到某种特殊的效果。比如说，这个文档里所有的XML标签都是圈在一个<c>元素里，表明这些都是用户可以输入的，但不是一个路径。使用元素<c>，你可以帮助你的读者快速区别出那些他们需要输入的命令。还有，因为标签<c>可以和普通文本区别开来，就不用将用户的输入用双引号圈起来。打比方说，不要想我这样引用元素"<c>"。防止双引号的不必要的使用可以使一个文档可读性更强，并且更可爱些。

　　元素<e>是用来强调一个单词或者词组。如：我真的应该多使用分号。就如你看到的，这个文本和普通的文本以强调形式区别开了。这可以帮助你得写作更加有棱有角。

　　早些时候我们已经看到了标签<mail>，它是用来将一个特定的email地址链接到一些文字上，并使用<mail link="foo@bar.com">Mr. Foo Bar</mail>这种形式。

　　标签<uri>是用来指向因特网中的文件或者位置。它有两种形式－－第一种用于在普通文本中将实际的链接显示出来，如这个链接：http://www.gentoo.org。我通过输入<uri>http://www.gentoo.org</uri>来创建这个链接。另一种形式是将一个URI链接到其他的文本，如the Gentoo Linux website。我是通过输入<uri link="http://www.gentoo.org">the Gentoo Linux website</uri>来创建这个链接的。

　　图片

　　这里告诉你怎样在一个文档里插入一个图片：<figure link="mygfx.png" short="my picture" caption="my favorite picture of all time"/>。属性link=指向实际图片的位置，属性short=设定一个简单的描述（目前用于图片的HTML的属性alt=）和一个标题。这并不复杂。我们也支持标准的HTML风格的标签<img src="foo.gif"/>来添加没有标题和边框等的图片。

　　表格和列表

　　Guide也支持同HTML类似的表格语法。要创建一个表格，使用标签<table>。用标签<tr>开始一行。但是，用来插入实际表格数据时，我们不支持HTML的标签<td>；而替代的，你如果要插入一个开头使用标签<th>，再使用标签<ti>用来插入普通的信息块。你也可以在任何使用标签<ti>的地方使用标签<th>代替，并没有要求元素<th>一定只能出现在第一行。目前，这些标签不支持任何属性，但是以后会加上一些（如即将给元素<table>增加属性caption=）。

　　要创建有序或无序的列表，只需简单的使用HTML风格的标签<ol>，<ul>和<li> tags。列表标签只能出现在标签<body>，<ul>或<ol>里。

　　文档内部链接

　　Guide在用超链接链接到文档的其他部分也很容易。你可以输入<uri link="#doc_chap1">Chapter One</uri>创建一个链接到Chapter One。为链接到section two of Chapter One，只需输入<uri link="#doc_chap1_sect2">section two of Chapter One</uri>。要链到第一章的图3，只需输入<uri link="doc_chap1_fig3">figure 1.3</uri>。或者输入<uri link="doc_chap2_pre2">code listing 2.2</uri>链接到code listing 2 in chapter 2。我们也即将增加自动链接的能力（如表格支持）。

　　但是，有些Guide文档更新很快，使用这种“计数形式”会导致一些错误链接。为解决这个问题，你可以使用属性id为一个设定<chapter>或者<section>一个名字，然后再链接到这个属性就可以了，就像这样：

　　代码 2.6: 使用属性id

<chapter id="foo">
<title>This is foo!</title>
...
<p>
更多信息可以在<uri link="#foo">foo chapter</uri>中查到。
</p>

　　3. 编码风格

　　简介

　　既然所有的Gentoo文档是合力的结果，并且可能有几个人头持修改一个已存在的文档，那么一种编码风格是必须的。一种编码风格包括两个部分。第一个是和内部的编码有关，怎样摆放xml标签。第二个便是和内容有关，怎样不让读者误解。

　　下面将讲解这两个部分。

　　内部编码风格

　　每个GuideXML标签（不管是开标签还是闭标签）后面都需要立即新开一行，下面这些除外：<version>，<date>，<title>，<th>，<ti>，<li>，<i>，<e>，<uri>，<path>，<b>，<comment>，<codenote>，<mail>。

　　每个元素<body>（仅对开标签）和每个标签<chapter>，<p>，<table>，<author> (set)，<pre>，<ul>，<ol>，<warn>，<note>和<impo>（仅对开标签）前都应加上空白行。

　　除开在在标签<pre>里，整字换行都要控制在80个字符内。只有在没有其他办法解决这个问题时（如一个URL超过了字符的最大数），编写者必须在任何出现空格时整字换行。

　　除开在XML父标签是<tr> (from <table>)，<ul>，<ol>和<author>的XML结构时，缩进可以不用。如果用上缩进，每次缩进必须是两个空格，也就是说不使用tab和不用更多的空格。

　　如果整字换行出现在<ti>，<th>或<li>结构中，内容中必须使用缩进。

　　缩进的一个例子：

　　代码 3.1: 缩进样例

<table>
<tr>
　<th>Foo</th>
　<th>Bar</th>
</tr>
<tr>
　<ti>这是一个缩进的例子。</ti>
　<ti>
　　如果文档不能在80字符的行中显示，如果父标签你
　　允许你必须使用缩进。
　</ti>
</tr>
</table>
<ul>
　<li>First option</li>
　<li>Second option</li>
</ul>

　　属性中，在属性、"=" 记号，和属性值之间都不许有空格。如例：

　　代码 3.2: 属性

错误:　　 <pre caption = "Attributes">
正确:　　 <pre caption="Attributes">

　　外部编码风格

　　在表格（<table>）和列表（<ul>和<ol>）里，除非在多个句子的情况下，不要轻易使用句号("。")。在这种情况下，每句话都应该以句号（或者其他标点符号）结束。

　　每句话，包括在表格和列表中的，都应该首字母大写。

　　代码 3.3: Periods and capital letters

<ul>
　<li>没有句号</li>
　<li>带有句号。必须是多个句子，记住了吗？</li>
</ul>

　　代码的列表应该都有一个标题。

　　使用<uri>时尽量用上属性link。也就是说，尽量用Gentoo Website替代http://www.gentoo.org。

　　如果在<pre>结构中插入注解，如果代码的内容是C/C++代码，只能使用<codenote>。其他情况下，组合使用<comment>和括号。还要将注解放在主题的注释之前。

　　代码 3.4: 注解的例子

(Substitute "john" with your user name)
# id john

　　4. 手册的格式

　　Guide文档 Vs 手册

　　对于内容很大的文档，如安装说明，我们需要一个更大方的格式。我们设计了一个与CuideXML兼容但增强的格式，允许我们书写模块和多页的文档。

　　主文件

　　第一个不同的就是我们需要一个“主”文档。这个文档并没有包含什么实际内容，只是指向不同的文档模块的链接。这和GuideXML的语法并没有多少不同：

　　代码 4.1: 手册的使用例子

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE book SYSTEM "/dtd/book.dtd">
<book link="example.xml">
<title>手册的使用例子</title>
<author...>
　...
</author>
<abstract>
　...
</abstract>
<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
<license/>
<version>...</version>
<date>...</date>

　　目前，还没有实际的不同（除开用标签<book>代替标签<guide>）。和以前以一个单独的<chapter>开始文档不同，我们定义了一个<part>，这等同于手册的一个分散的部分：

　　代码 4.2: 定义一个part

<part>
<title>第一篇</title>
<abstract>
　...
</abstract>
(定义几个段落)
</part>

　　每个篇章都是由一个<title>和一个<abstract>实现的，其中后者给出这篇的简单介绍。

　　在每个篇章中，我们定义了不同的单独的<chapter>。每个段落都必须是一个单独的文档。因此，毫无疑问的要增加一个特别的标签（<include>）允许来包含分散的文档。

　　代码 4.3: 定义一个段落

<chapter>
<title>第一段</title>
<abstract>
　这是第一段的简单说明。
</abstract>
　<include href="path/to/chapter-one.xml"/>
</chapter>

　　设计不同的段落

　　一个单独的段落结构如下所示：

　　代码 4.4: 段落的语法

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
<!--　The content of this document is licensed under the CC-BY-SA license -->
<!--　See http://creativecommons.org/licenses/by-sa/1.0 -->
<sections>
(定义几个<section>和<subsection>)
</sections>

　　在每个段落中，你可以定义<section>（等同于Guide文档的chapter）和<subsection>（等同于Gudie文档的section）。

　　5. 资源

　　开始写作

　　Guide文档是经特殊设计为“简单而传神”，这样开发者可以多花时间于写文档和少花时间于学习实际的XML语法。我们希望这个可以允许那些不是对文档异常敏锐的开发者开始写出高质量的Gentoo Linux文档。如果你愿意提供帮助（或者有关于这个文档的问题），请回复一条信息到gentoo-doc 邮件列表，告诉我们你想处理什么。祝你愉快！

通告:http://www.qqread.com/xml/t348000.html