获取 Gentoo！
开发指南
  1. 主索引
  2. 附录

Gentoo DevBook XML 指南

DevBook XML 设计目标

DevBook XML 语法轻量级且表达力强，易于学习，同时提供了我们创建 Web 文档所需的所有功能。标签数量保持最少 - 仅包含我们需要的标签。这使得 DevBook XML 能够轻松转换为其他格式，例如 DocBook XML/SGML 或 Web 就绪的 HTML。

目标是简化 创建 和 转换 DevBook XML 文档。

基本结构

让我们开始学习 DevBook XML 语法。我们将从 DevBook XML 文档中使用的初始标签开始。

DevBook XML 文档的前言

<?xml version="1.0" encoding="UTF-8"?>
<guide self="appendices/devbook-guide/">
<chapter>
<title>Gentoo DevBook XML guide</title>

在第一行，我们看到 XML 声明，它将此标识为 XML 文档。接下来，有一个 <guide> 标签 - 整个文档都包含在 <guide> </guide> 对中。它的 self 属性必须指向文档相对于根节点的相对路径；在上面的示例中，路径为 appendices/devbook-guide/。根节点本身是一个例外，它使用 <guide root="true"> 代替。

接下来，有一个 <chapter> 标签。每个文档都必须恰好包含一个章节。它的 <title> 用于设置整个文档的标题。

当然，所有元素都必须关闭，因此文档以以下内容结尾：

</chapter>
</guide>

章节和子章节

指定初始标签后，就可以开始添加文档的结构元素了。章节分为若干部分；每个部分可以包含零个或多个子部分，子部分可以包含零个或多个子子部分。章节、子章节和子子章节元素必须具有标题。这是一个包含单个子部分（包含一个段落）的示例章节：

最小的 DevBook 示例

<section>
<title>This is my section</title>
<subsection>
<title>This is subsection one of my section</title>
<body>

<p>
This is the actual text content of my subsection.
</p>

</body>
</subsection>
</section>

在上面，我通过向 <section> 元素添加子 <title> 元素来设置章节标题。然后，我通过添加 <subsection> 元素创建了一个子部分。如果查看 <subsection> 元素内部，您会发现它有两个子元素 - <title> 和 <body>。虽然 <title> 没什么新意，但 <body> 是 - 它包含此特定子部分的实际文本内容。我们将在稍后查看允许在 <body> 元素内部使用的标签。

包含子文档

手册组织为树形结构。每个目录包含一个文档，该文档可以使用 <include href="foo/"/> 标签包含多个子文档。请注意，href 值中的尾部斜杠是必须的。

可以使用 <contentsTree> 生成目录。通常，这将是其自身章节主体中的唯一元素，如下例所示：

<section>
<title>Contents</title>
<body>
<contentsTree/>
</body>
</section>

一个示例 <body>

现在，是时候学习如何标记实际内容了。以下是一个示例 <body> 元素的 XML 代码：

主体元素示例

<p>
This is a paragraph. <c>/etc/passwd</c> is a file.
<uri>https://gentoo.ac.cn/</uri> is my favorite website.
Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
</p>

<pre>
This is text output or code.
# this is user input
</pre>

<codesample lang="sgml">
Make HTML/XML easier to read by using selective emphasis:
&lt;foo&gt;bar&lt;/foo&gt;
</codesample>

<note>
This is a note.
</note>

<important>
This is important.
</important>

<warning>
This is a warning.
</warning>

<todo>
Text inside a <c>todo</c> element will appear in the
<uri link="::appendices/todo-list/"/>.
</todo>

现在，以下是上面 <body> 元素的渲染方式：

这是一个段落。/etc/passwd 是一个文件。https://gentoo.ac.cn/ 是我最喜欢的网站。如果您想尝试，请键入 ls。我现在真的很想睡觉。

This is text output or code.
# this is user input

Make HTML/XML easier to read by using selective emphasis:
<foo>bar</foo>

主体元素

我们在上一节中介绍了许多新标签 - 以下需要了解的信息。<p>（段落）、<pre>（预格式化块）、<codesample>（代码块）、<note>、<important>、<warning> 和 <todo> 标签都可以包含一行或多行文本。除了 <figure>、<table>、<ul>、<ol> 和 <dl> 元素（我们将在稍后介绍）之外，这些是唯一应该出现在 <body> 元素内部的标签。还有一点 - 这些标签不应该堆叠 - 换句话说，不要将 <note> 元素放在 <p> 元素内部。正如您可能猜到的那样，<pre> 和 <codesample> 元素完全保留其空白字符，这使得它们非常适合代码摘录。<pre> 和 <codesample> 都可以具有 caption 属性。

命名 <pre>

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

代码示例和颜色编码

<pre> 标签不支持任何语法高亮显示。当您需要语法高亮显示时，请使用 <codesample> 标签以及 lang 属性 - 通常您希望将其设置为 "ebuild" 以突出显示 ebuild 代码片段。目前，支持以下语言：

  • c
  • ebuild
  • make
  • m4
  • sgml

示例 <codesample lang="c"> 块

#include <stdio.h>

main()
{
	/* This is a comment */
	printf("Hello, world!\n");
}

您还可以指定 numbering="lines" 以启用行号，如下例所示：

01: # Copyright 1999-2021 Gentoo Authors
02: # Distributed under the terms of the GNU General Public License v2
03: 
04: EAPI=7
05: 
06: DESCRIPTION="MicroGnuEmacs, a port from the BSDs"
07: HOMEPAGE="https://homepage.boetes.org/software/mg/"
08: SRC_URI="https://github.com/hboetes/${PN}/archive/${PV}.tar.gz -> ${P}.tar.gz"
09: 
10: LICENSE="public-domain"
11: SLOT="0"
12: KEYWORDS="alpha amd64 arm hppa ppc ~ppc64 sparc x86"
13: 
14: RDEPEND="sys-libs/ncurses:0=
15: 	>=dev-libs/libbsd-0.7.0"
16: DEPEND="${RDEPEND}"
17: BDEPEND="virtual/pkgconfig"
18: 
19: src_install() {
20: 	dobin mg
21: 	doman mg.1
22: 	dodoc README tutorial
23: }

图形

以下是如何将图形插入文档 - <figure link="mygfx.png" short="my picture" caption="my favorite picture of all time"/>。link 属性指向实际的图形图像，short 属性指定简短描述（当前用于图像的 HTML alt 属性），以及标题。不太难 :) 我们还支持标准的 HTML 样式 <img src="foo.gif"/> 标签，用于添加没有标题、边框等的图像。

表格

DevBook XML 支持类似于 HTML 的简化表格语法。要开始一个表格，请使用 <table> 标签。使用 <tr> 标签开始一行。但是，对于插入实际的表格数据，我们不支持 HTML <td> 标签；而是，如果您要插入标题，请使用 <th>，如果您要插入普通的信息块，请使用 <ti>。您可以在可以使用 <ti> 的任何地方使用 <th> - 没有要求 <th> 元素仅出现在第一行。

此外，表格标题（<th>）和表格项（<ti>）都接受 colspan 和 rowspan 属性，以跨行、列或两者扩展其内容。

此外，表格单元格（<ti> & <th>）可以使用 align 属性右对齐、左对齐或居中。

此标题跨越 4 列
此标题跨越 6 行 项目 A1 项目 A2 项目 A3
项目 B1 块状 2x2 标题
项目 C1
项目 D1..D3
项目 E1..F1 项目 E2..E3
项目 F2..F3

列表

要创建有序或无序列表，只需使用 XHTML 风格的 <ol>、<ul> 和 <li> 标签。列表只能出现在 <body> 和 <li> 标签内部，这意味着您可以在列表中嵌套列表。不要忘记您正在编写 XML，并且必须关闭所有标签，包括列表项，这与 HTML 不同。

定义列表 (<dl>) 也受支持。请注意，定义术语标签 (<dt>) 不接受任何其他块级标签，例如段落或提示。定义列表包含

<dl>
一个包含 Definition List 标签
<dt>
Definition Term 标签
<dd>
和 Definition Data 标签。

以下从 w3.org 复制的示例显示列表也可以嵌套，并且可以使用不同的列表类型。

配料
  • 100 克面粉
  • 10 克糖
  • 1 杯水
  • 2 个鸡蛋
  • 盐，胡椒粉
步骤
  1. 将干性配料充分混合。
  2. 倒入湿性配料。
  3. 混合 10 分钟。
  4. 在 300 度烘烤一小时。
备注
可以通过添加葡萄干来改进食谱。

内联元素

<c>、<b>、<e>、<sub> 和 <sup>

<c> 元素用于标记 命令 或 用户输入。可以将 <c> 视为一种提醒读者某些可以键入的内容，这些内容将执行某种操作的方法。例如，本文档中显示的所有 XML 标签都包含在 <c> 元素中，因为它们表示用户可以键入的非路径内容。通过使用 <c> 元素，您可以帮助读者快速识别需要键入的命令。此外，由于 <c> 元素已与常规文本偏移，因此很少需要用双引号括住用户输入。例如，不要像我在本句中那样引用 "<c>" 元素。避免使用不必要的双引号可以使文档更易读，也更可爱！

正如您可能猜到的那样，<b> 用于将某些文本加粗。

<e> 用于对单词或短语进行强调；例如：我确实应该更频繁地使用分号。如您所见，此文本与常规段落类型偏移以进行强调。这有助于使您的散文更有冲击力！

<sub> 和 <sup> 元素用于指定下标和上标。

<uri>

<uri> 标签用于指向互联网上的文件/位置。它有两种形式——第一种可以在您希望在正文中显示实际 URI 时使用，例如此链接到 https://gentoo.ac.cn/。要创建此链接，我键入了 <uri>https://gentoo.ac.cn/</uri>。另一种形式是当您希望将 URI 与其他文本关联时——例如，Gentoo Linux 网站。要创建此链接，我键入了 <uri link="https://gentoo.ac.cn/">the Gentoo Linux website</uri>。

请避免 点击此处综合征，如 W3C 所建议。

文档内引用

DevBook XML 使使用超链接引用文档的其他部分变得非常容易。您可以创建一个指向另一个章节的链接，例如 Ebuild 文件格式，方法是键入 <uri link="::ebuild-writing/file-format/">Ebuild file format</uri>，即两个冒号后跟从根节点开始的相对路径。要引用另一个章节中的某个部分，例如 第一个 Ebuild，请键入 <uri link="::quickstart/#First ebuild">First ebuild</uri>。

如果链接目标的章节（或部分等）标题用作链接文本，则可以使用空的 <uri> 元素。事实上，我可以更简洁地编写以上两个示例：<uri link="::ebuild-writing/file-format/"/> 和 <uri link="::quickstart/#First ebuild"/> 分别呈现为 Ebuild 文件格式 和 第一个 Ebuild。

编码风格

由于所有 Gentoo 文档都是共同努力的结果，并且很可能有多个人会更改现有的文档，因此需要一种编码风格。编码风格包含两个部分。第一个是关于内部编码——XML 标签的放置方式。第二个是关于内容——如何避免混淆读者。

接下来将描述这两个部分。

内部编码风格

必须在每个 DevBook XML 标签（开头和结尾标签）之后立即放置换行符，以下标签除外：<title>、<th>、<ti>、<li>、<dt>、<dd>、<b>、<c>、<e>、<d/>、<uri>。

必须在每个 <body>（仅开头标签）之后立即放置空行，并在每个 <section>、<p>、<pre>、<codesample>、<figure>、<table>、<ul>、<ol>、<dl>、<note>、<important> 和 <warning>（仅开头标签）之前放置。此规则的例外情况适用于位于列表项或表格单元格内的标签。

必须在 80 个字符处应用自动换行，<pre> 和 <codesample> 内部除外。只有在没有其他选择时（例如，当 URL 超过最大字符数时），您才能偏离此规则。然后编辑器必须在第一次出现空格时进行换行。您应该尝试将 <pre> 和 <codesample> 元素的渲染内容保持在 80 列以内，以帮助控制台用户。

缩进不得使用，除非父 XML 标签为 <tr>（来自 <table>）、<ul>、<ol> 和 <dl> 的 XML 结构。如果使用缩进，则必须每个缩进两个空格。这意味着不允许使用制表符并且不能使用更多空格。此外，DevBook XML 文档中不允许使用制表符（同样，

 和  除外）。



如果在 <ti>、<th>、<li> 或 <dd> 结构中发生自动换行，则必须对内容使用缩进。



缩进示例如下：



缩进示例


<table>
<tr>
  <th>Foo</th>
  <th>Bar</th>
</tr>
<tr>
  <ti>This is an example for indentation</ti>
  <ti>
    In case text cannot be shown within an 80-character wide line, you
    must use indentation if the parent tag allows it
  </ti>
</tr>
</table>

<ul>
  <li>First option</li>
  <li>Second option</li>
</ul>





带有单个属性的开头标签不得拆分到多行。例如，不要在 <uri 和其 link 属性之间放置换行符。而是在 <uri> 标签之前换行。




属性在属性、"=" 标记和属性值之间不得有空格。例如



属性


Wrong  :     <uri link = "https://gentoo.ac.cn/">
Correct:     <uri link="https://gentoo.ac.cn/">





用作句子内标点符号的连字符——像这样——应写为用空格包围的 <d/> 标签。使用等宽字体编辑源代码时，很难区分 Unicode em 连字符和连字符。

外部编码风格

在表格 (<table>) 和列表 (<ul>、<ol> 和 <dl>) 内部，不应使用句号 (".")，除非使用了多个句子。在这种情况下，每个句子都应以句号（或其他标点符号）结尾。

每个句子，包括表格和列表内的句子，都应以大写字母开头。

句号和大写字母

<ul>
  <li>No period</li>
  <li>With period. Multiple sentences, remember?</li>
</ul>

标题应使用句子大小写，即第一个单词应以大写字母开头，其他所有单词（专有名词除外）应为小写。

尽可能使用带有 link 属性的 <uri>。换句话说，Gentoo 网站 比 https://gentoo.ac.cn/ 更可取。