LDP 作者指南

Jorge Godoy

Conectiva S.A.
出版部门

Emma Jane Hogbin

Mark F. Komarinski

David C. Merrill

david -AT- lupercalia.net

2005-03-04

修订历史
修订版 4.84.74.64.54.44.34.24.12006-04-202005-03-042005-01-232004-07-142004-04-192004-04-042004-04-022004-01-27修订者：MGejhejhejhejhejhejhejh
添加了关于首选提交格式的注释，更正了链接，打包了模板。修复了示例 DocBook 标记中的拼写错误。添加了新的基于 Web 的创作工具以及关于 LaTeX 到 DocBook 转换的信息。修复了 xmlto 注释和书籍模板中的拼写错误。将有关具有 DocBook 功能的文字处理工具的信息复制到“将文档转换为 DocBook XML”附录中；添加了新的 XML 编辑器；以及关于将其他格式转换为 DocBook XML 的工具的信息。更新了关于 CVS 帐户和连接到 CVS 服务器的信息。在“使用 DocBook”部分添加了编辑者署名要求。更新了提交程序。现在，只有在成功完成每个要求的审核后，才能由审核协调员添加新文档。删除了贡献给 LDP 的部分（替换为 LDP 流程摘要）。在参考书目中添加了 LyX 到 DocBook 转换的参考。更新了许可证要求并将其添加到目录中（将其从子部分移出）。

本指南描述了向 Linux 文档项目 (TLDP) 提交和发布文档的流程。它包括关于 TLDP 使用的工具、工具链和格式的信息。本文档的主要受众是新的 TLDP 作者，但也包含有经验的文档作者的信息。

目录
1. 关于本指南
1.1. 关于本指南
1.2. 关于 LDP
1.3. 反馈
1.4. 版权和商标
1.5. 致谢
1.6. 文档约定
2. 编写 TLDP 文档：简介
2.1. LDP 流程摘要
2.2. 邮件列表
3. 撰写您的提案
3.1. 选择主题
3.2. 文档的范围
3.3. 未维护和过时的文档
3.4. 制定大纲
3.5. 研究
4. 写作
4.1. 编写文本
4.2. 编辑和校对文本
4.3. 用于编写、编辑和维护文档的工具
5. 标记
5.1. 标记：概述
5.2. DocBook：它是什么以及我们为什么使用它
5.3. XML 和 SGML：我们为什么使用 XML
5.4. TLDP 接受的标记语言
6. 分发您的文档
6.1. 分发文档之前
6.2. 许可和版权
6.3. 致谢
6.4. TLDP 审核流程
6.5. 提交给 LDP 以供发布
7. 维护
7.1. 维护您的文档
7.2. 修复错误
参考文献
A. 模板
A.1. 文档模板
A.2. 样式表
A.3. GNU 自由文档许可证
B. 系统设置：编辑器、验证和转换
B.1. 适用于您操作系统的工具
B.2. 编辑工具
B.3. 验证
B.4. 转换
B.5. DocBook DTD
B.6. 格式化文档
C. 并发版本系统 (CVS)
C.1. 获取 CVS 帐户
C.2. 使用 CVS
C.3. CVS 资源
D. DocBook：示例标记
D.1. 一般提示和技巧
D.2. <section> 和 <sectN>：有什么区别？
D.3. 命令提示符
D.4. 编码索引
D.5. 插入图片
D.6. 元数据的标记
D.7. 参考书目
D.8. 实体（快捷方式、文本宏和可重复使用的文本）
D.9. 自定义您的 HTML 文件
E. 将文档转换为 DocBook XML
E.1. 文本到 DocBook
E.2. OpenOffice.org 到 DocBook
E.3. Microsoft Word 到 DocBook
E.4. LaTeX 到 DocBook
E.5. LyX 到 DocBook
E.6. DocBook 到 DocBook 转换
术语表
F. GNU 自由文档许可证
F.1. 0. 前言
F.2. 1. 适用性和定义
F.3. 2. 逐字复制
F.4. 3. 大量复制
F.5. 4. 修改
F.6. 5. 合并文档
F.7. 6. 文档集合
F.8. 7. 与独立作品的聚合
F.9. 8. 翻译
F.10. 9. 终止
F.11. 10. 本许可证的未来修订版
F.12. 附录
表格列表
D-1. 有用的标记
图表列表
B-1. epcEdit 屏幕截图
B-2. nedit 屏幕截图
B-3. 向 nedit 添加 shell 命令
B-4. nsgmls 成功输出
示例列表
B-1. 设置 SGML_CATALOG_FILES 和 XML_CATALOG_FILES 环境变量
B-2. SGML 目录的示例
B-3. XML 目录文件示例
B-4. 使用 xmllint 调试示例
B-5. "安装" DSSSL 样式表
B-6. 创建 HTML 输出的示例
B-7. "安装" DocBook 文档类型定义
B-8. 在文章中插入摘要的样式表
B-9. 配置外部实体以包含索引
D-1. 带 programlisting 的命令提示符
D-2. 带 screen 的命令提示符
D-3. 生成索引的代码
D-4. 属性 zone 的使用
D-5. 属性 class 上值 startofrange 和 endofrange 的用法
D-6. 插入图片
D-7. 使用 <imageobject>
D-8. 其他署名
D-9. 编辑者
D-10. 示例元数据
D-11. 参考书目
D-12. 添加实体
D-13. 参数实体的用法

第 1 章. 关于本指南

1.1. 关于本指南

本文档由 Mark F. Komarinski 于 1999 年 8 月 26 日在花费两天的时间让工具正常工作后开始编写。如果即使一位 LDP 作者能从中获得帮助，那我就完成了我的工作。

本文档的第 4 版由 Emma Jane Hogbin 于 2004 年初发布。对文档进行了彻底的修改，以将创作 HOWTO 与技术 HOWTO 分离。审查大约花费了八个月。

本文档的最新版本可以在 LDP 主页 http://www.tldp.org 找到。原始 DocBook、HTML 和其他格式都可以在那里找到。

有很多方法可以为 Linux 运动做出贡献，而不需要具备生产软件的能力。其中一种方法是编写文档。易于理解、技术上准确的文档的可用性可以为正在努力使用 Linux 软件的人带来巨大的改变。本指南旨在帮助您研究和编写 HOWTO，并将其提交给 LDP。附录还包括示例模板、标记提示以及关于如何将您的文档从 DocBook 转换为另一种格式（如 HTML）以便于校对的信息。

1.2. 关于 LDP

Linux 文档项目 (LDP) 的启动是为了为新用户提供一种快速获取关于特定主题的信息的方式。它不仅包含一系列关于管理、网络和编程的书籍，而且还有大量关于个别主题的小型作品，由那些使用过它的人编写。如果您想了解关于打印的信息，您可以获取 打印 HOWTO。如果您想了解您的以太网卡是否适用于 Linux，请获取 以太网 HOWTO，等等。

LDP 以各种方便的格式向世界提供文档，并接受多种格式的提交。存储源文档的当前标准是一种称为 DocBook 的格式，请参阅 第 5.2 节。

 

Linux 文档项目 (LDP) 正在努力为 GNU/Linux 操作系统开发免费、高质量的文档。LDP 的总体目标是在所有 Linux 文档问题上进行协作。这包括创建 "HOWTOs" 和 "Guides"。我们希望为 Linux 建立一个易于使用和搜索的文档系统。这包括集成手册页、info 文档、HOWTOs 和其他文档。

 
--LDP 宣言位于 http://www.tldp.org/manifesto.html 

人类可读的版本更像是这样：LDP 由一大群志愿者组成，他们正在编写关于 Linux 和在 Linux 内核上运行的程序的文档。这些文档主要以较短的 HOWTO 和较长的 Guides 的形式存在。两者都可以在 http://www.tldp.org/ 上找到。本指南主要侧重于如何编写您自己的 HOWTO 并提交给 LDP。

1.3. 反馈

发送反馈至请在您的电子邮件中引用本文档的标题。请注意：您必须订阅才能向列表发送电子邮件。

1.4. 版权和商标

版权所有 1999-2002 Mark F. Komarinski, David C. Merrill, Jorge Godoy

在GNU自由文档许可证1.1版或自由软件基金会发布的任何后续版本的条款下，允许复制、分发和/或修改本文档，无不变部分，无封面文本，无封底文本。 许可证副本包含在标题为"GNU自由文档许可证"的附录中。

1.5. 致谢和感谢

1.5.1. 版本 1 - 版本 3

感谢所有在我写作过程中提供意见的人。 包括 David Lawyer, Deb Richardson, Daniel Barlow, Greg Ferguson, Mark Craig 和其他列表成员。 我从HOWTO 索引 和 sgmltools 文档中获得了一些章节。 关于网络访问CVS的部分由 Sergiusz Pawlowicz 编写（）。 DocBook章节由 Jorge Godoy 编写（）。 非常感谢他们两位的帮助。

1.5.2. 版本 4

感谢 Tabatha Marshall 和 Machtelt Garrels (Tille) 确保我真正完成了文档。 感谢我的审阅者：Charles Curley, Martin Brown 和 Tille； 以及 Saqib Ali 提供的在线转换和验证工具。 我还采纳了来自 LDP 邮件列表的一些有用电子邮件。 原始作者已在文档中注明。 特别感谢 Steve Champeon 让我对标记语言产生了兴趣，并成为了我的良师益友； 以及我的伴侣 Graig Kent，他给予了我极大的支持。 [EJH]

1.6. 文档约定

本文档使用以下约定[1]

描述外观
需要特别注意的信息

Warning

这是一个警告。

注意

Caution

这提醒读者。

提示

Tip

这是一个提示。

注释

Note

这是一个注释。

文件名file.extension
目录名directory
要键入的命令command
应用程序名称application
Prompt bash shell下用户命令的提示符bash$
Prompt bash shell下root用户命令的提示符bash#
Prompt tcsh shell下用户命令的提示符tcsh$
环境变量VARIABLE
强调的词word
引用的文本"quote"
代码示例
<para>Beginning and end of paragraph</para>

第2章. 编写TLDP文档：简介

2.1. LDP流程概述

以下部分概述了为Linux文档项目创建和/或维护文档的过程。 本节包括所有步骤——其中一些步骤可能与您的特定文档无关。

  1. 加入 discuss 邮件列表。 有兴趣接管他人文档维护的作者也应该加入此列表。 这是为了确保 LDP 知道谁在做什么文档。

    如果您尚未撰写文档，请查看我们的文档（当前，未维护 和 正在进行中），并向列表提交提案。 您的提案应包括您的文档与已在集合中的文档不同的原因； 或者确定我们文档中当前缺少的主题。 有关编写提案的更多信息，请阅读第 3 章。

    有关邮件列表的更多信息，请阅读第 2.2 节或访问lists.tldp.org进行订阅。 如果您的文档已经编写完成，请将副本提交到 discuss 列表（或包括可以找到该文档的 URL）。

  2. 编写您的文档。 如果您的文档尚未编写完成，请务必在开始编写之前向 discuss 列表发送电子邮件。您可以选择您感觉最舒服的格式来编写您的文档。 如果它不是 LDP 接受的格式之一，将会有一名志愿者为您转换。 有关编写技术文档的更多信息，请阅读第 4 章。

  3. 如果您要添加自己的标记，您可能还想加入 docbook 邮件列表。 有关 LDP DocBook 列表的更多信息，请阅读第 2.2 节。 如果您想从模板开始，您可能会发现附录 A中的模板很有用。 第 5 章中还有关于标记的一般介绍，附录 D 中有一节包含大量示例。

  4. 提交您的文档以进行技术、语言和元数据审核。 通过将您的文档通过电子邮件发送至来完成。 在主题行中，请务必提供文档的标题。 在电子邮件正文中，说明您已准备好进行审核过程。 概述您的文档可能已经收到的任何其他审核。 您应该在一周内被分配一名审阅者。 审核可能需要额外的一周时间。 有关此过程的更多信息，请阅读第 6 章。

    如果您的文档尚未采用 DocBook 或 LinuxDoc 格式，审阅者会为您转换。

  5. 一旦您的文档通过了每一项审核，审核协调员会将它添加到 CVS，将版本号更新为 1.0，并让该文档发布在公共网站上。 有关您最终提交给 LDP 的更多信息，请阅读第 6.5 节。

Tip如果您不以 DocBook 格式提交您的文档
 

为您的文档添加标记的志愿者可以选择任何接受的标记语言。 但是，《作者指南》仅参考 DocBook。 如果您要提交纯文本或其他格式，请告知 LDP 您是否希望以 LinuxDoc 或 DocBook 维护您的文档，这两种格式是最终结果的接受格式。

2.2. 邮件列表

您可以订阅以下邮件列表

  • 首先是, 它是 LDP 的主要讨论组。

  • 另一个是列表，该列表用于有关 DocBook 使用的问题，包括标记和转换。 如果您在使用特定标记时遇到问题，可以将您的问题发送到此处寻求解答。

您可以通过向以下地址发送请求消息来订阅任一列表或。 您的消息的主题应为"subscribe"（不带引号）。 要从列表中删除自己，请发送主题为"unsubscribe"的电子邮件至或.

如果您对 DocBook 的兴趣超出了 LDP 文档的简单标记，您可能需要考虑加入 OASIS DocBook 邮件列表。 请访问 http://docbook.org/mailinglist/index.html 了解更多信息。

第 3 章. 撰写您的提案

3.1. 选择主题

如果您正在阅读《作者指南》，那么您很可能已经有一个主题。 这个想法可能来自于您自己在尝试使某些东西正常工作时遇到的挫折； 或者您可能已经在为其他目的编写或已编写文档，并且您想将其提交给 LDP。 例如，如果您在邮件列表中发布了一个问题，并且需要多次发布才能解决该问题——这可能成为您编写文档的动力。

无论您如何选择您的主题，重要的是 LDP 社区要了解为什么您的文档应该包含在其集合中。 如果有人要求提供文档，或者您与邮件列表合作解决了问题，您应该在提交给 LDP discuss 邮件列表的提案中包含详细信息。 这可能有助于其他人理解您特定文档的需求。

3.2. 您的文档的范围

现在您已经有了一个主题，您需要确定文档的范围。 范围或主题领域应该是

  1. 明确定义的。在开始之前定义您的主题领域的边界。 不要重复另一个 HOWTO 中的信息，并且不要在您的 HOWTO 和其他人的 HOWTO 之间留下信息空白。

  2. 不要太宽泛，也不要太狭窄。如果您试图涵盖太多的信息，您可能会牺牲深度。 详细涵盖一个小的课题领域比糟糕地涵盖一个大的课题领域要好。 Linux 工具以只做一件事并做好这一件事而闻名。 同样，您的 HOWTO 应该涵盖一个主题并做好它。

    如果您的提案文档的范围非常狭窄，最好将您的信息作为另一个 HOWTO 的一部分包含在内。 这使得读者更容易找到他们需要的 HOWTO。 在 LDP 存储库中搜索与您的文档相关的主题。 如果您找到一个非常匹配的文档，请通过电子邮件发送给作者，询问他们是否愿意包含您的贡献。

  3. 未记录的。在记录特定主题之前，始终进行网络搜索（特别是 LDP 文档内的搜索），以查看您的主题是否已在其他文档中涵盖。 如果是，请参考其他文档，而不是在您自己的文档中复制信息。 您可能希望包含可在其他文档中找到的信息的简要摘要。

    如果已有的 HOWTO 不够或需要更新，请联系作者并提供帮助。 另请参阅第 3.3 节，了解如何接管旧的或未维护的文档。

    大多数作者都感谢提供的任何帮助。 此外，向作者发送评论和意见通常被认为是肯定和奖励：对于作者来说，反馈是证明编写文档并非毫无意义的最终证据。

  4. 经过 LDP 预先批准的。在您继续编写 HOWTO 之前，请发布到 discuss 列表并从其他 LDP 志愿者那里获得一些反馈。 在您开始之前与列表核对可以稍后节省您的麻烦。

Note保持联系！
 

加入 discuss 列表并定期关注它，即使您从不发帖，也是了解 LDP 的活动、需求和政策的好方法。

3.2.1. 文档模板

在您确定了文档的范围之后，您应该开始考虑您将编写的文档类型。 有许多不同的 LDP 文档模板：指南、HOWTO、手册页和 FAQ。 Rahul Sundaram 在 Linux 文档项目 (LDP) FAQ 中描述了它们的范围。 以下是它们的简要概述以及有关如何开始编写您自己的文档的指针

  • 指南 (Guides)。 指南涵盖范围广泛的主题，而且篇幅较长。《作者指南》（本文档）就是一个指南。其他指南包括：Linux 入门：实践指南，Linux 内核模块编程指南等。完整的指南列表可从以下网址获取：Linux 项目文档指南。指南使用 “book” 模板，位于 附录 A 中。

  • HOWTOs。 HOWTO 通常是一系列指令，逐步说明如何完成特定任务。HOWTO 的例子包括：CDROM-HOWTO，Module-HOWTO。完整的 HOWTO 列表可从以下网址获取：HOWTO 单一列表（警告：页面很大）。HOWTO 通常使用 “article” 模板，默认情况下输出到多个 HTML 页面。模板位于 附录 A 中。

  • man 页面。 man（Manual）页面是许多 Linux 应用程序和实用程序可用的标准帮助形式。可以通过在提示符下键入 man 应用程序名称来查看它们。完整的 man 页面列表可从以下网址获取：Linux Man 页面。由于 man 页面与软件捆绑在一起，因此目前没有 LDP 模板。

  • 常见问题解答 (FAQs)。 常见问题解答 (FAQs) 是问题和答案的列表，旨在防止新用户一遍又一遍地问相同的问题。完整的常见问题解答列表可从以下网址获取：Linux 文档项目常见问题解答。常见问题解答通常使用 “article” 模板，其中包含一些特定的 DocBook 元素来形成问答结构。您可以在 附录 A 中找到编写常见问题解答的模板。

Notemini-HOWTOs 和 HOWTOs
 

LDP 不再区分 HOWTOs 和 mini-HOWTOs。所有先前编写的 mini-HOWTOs 都已包含在较长的 HOWTOs 中。所有新文档的长度至少必须达到 HOWTO 的级别。这意味着文档应该涵盖更大的主题领域，而不是较小的主题领域。如果您的文档非常小，您可能希望将其提交，以便包含在另一个现有的、更大的 HOWTO 中。如果您不确定您的文档的大小，请发送电子邮件到 discuss 列表并寻求反馈。

3.3. 未维护和过时的文档

如果您希望成为未维护文档的 “所有者”，则必须完成几个步骤。

  • 联系作者。确保作者不再希望维护相关文档。请注意，显示的电子邮件地址可能不再有效。在这种情况下，请尝试使用 搜索来查找作者。如果在经过 “诚意”的努力后找不到文档的原始作者，请告知我们（--需要订阅）。

  • 确定是否存在比 LDP 上提供的更新的文档副本。如果是这样，请尝试获取一份副本以供您使用。

  • 告知 LDP 您希望维护哪个文档，以便我们可以跟踪谁在做什么，并防止重复工作。我们还建议您加入 LDP 一般讨论列表（）。此步骤也是新文档所必需的。

  • 将文档连同任何打算进行的修改一起提交给 LDP。确保继续在文档中的某个位置（致谢、修订历史等）引用原始作者。重新提交文档后，我们将从未维护的文档列表中删除该条目。

Note需要反馈
 

某些未维护的文档可能已过时，或者内容可能已包含在另一个（积极维护的）HOWTO 中。如果是这种情况，请联系我们（最好在 discuss 邮件列表中）并告知我们。

3.4. 制定大纲

在您真正开始写作之前，请准备一个大纲。大纲将帮助您清楚地了解主题，并使您可以一次专注于 HOWTO 的一小部分。

除非您的 HOWTO 异常小，否则您的大纲可能将是多级的。在制定多级大纲时，顶层应包含一般主题领域，而子标题应更详细和具体。独立地查看您的大纲的每个级别，并确保它涵盖了主题的所有关键领域。子标题应涵盖它们所属标题下的所有关键领域。

大纲中的每个项目都应遵循其之前的项目，并引导到下一个项目。例如，关于特定程序的 HOWTO 不应在关于安装的部分之前包含关于配置的部分。

您可以选择使用以下大纲来编写关于使用特定程序的 HOWTO

  • 开发历史

  • 从哪里下载软件

  • 如何安装软件

  • 如何配置软件

  • 如何使用软件

您可能会发现在写作过程的这个阶段尝试一些 “卡片分类”会很有帮助。将您的所有小型主题区域写在纸上。现在将这些纸张分类到主标题及其子部分中。在您开始之前，洗牌这些纸条可能会有所帮助。这将有助于您在工作时获得一套新的视角。

当您对您的大纲感到满意时，请再次仔细地查看它，并用批判的眼光看待它。您是否以足够的细节涵盖了每个相关主题？您是否没有超出文档的范围？最好将您的大纲展示给其他人（包括 LDP discuss 列表）以获得一些反馈。请记住：在您的大纲阶段重新组织您的文档比在编写后执行此操作容易得多。

Tip轻松编写 HOWTO
 

如需帮助编写您的 HOWTO 大纲，并抢先开始标记您的文档，请查看 LDP HOWTO 生成器。请注意，这是用于生成 HOWTOs 的。FAQ 和指南的模板可在 附录 A 中找到。

Note你并不孤单
 

您可能已经注意到一个正在发展的主题。就像自由软件一样，自由文档在您 “尽早发布，频繁发布”时效果最佳。discuss 列表包含许多经验丰富的 LDP 作者，在您就您的贡献做出决定时，寻求他们的建议是明智之举。

3.5. 研究

在您处理您的大纲时，您很可能会研究您的主题 - 尤其是为了确认您即将编写的文档尚不存在！以下是一些指针，可以防止您以后抓狂

  • 在您研究时编译您的资源。 几乎可以保证您在最需要的时候不会记得在哪里找到关键信息。在您进行时，将重要（甚至不太重要）的页面添加为书签会有所帮助。确保书签的标题反映页面对您重要的原因。如果一个页面中存在多个关键思想，您可能希望使用不同的标题将同一页面添加为书签。

  • 假设您最重要的资源将消失。 可怕的 “错误 404：找不到页面”。即使您已将页面添加为书签，当您返回该页面时，它也可能不存在。如果页面包含非常关键的信息：请制作副本。您可以通过创建一个文本文件来实现此目的，该文本文件的标题为文档标题、作者姓名、页面 URL 以及页面的文本，并将其放入您计算机上的文本文件中。您也可以选择将文件 “打印”为 PDF（如果使用智能浏览器，则保存为或转换为 PDF 格式将捕获页面上的原始 URL）。

  • 现在开始您的 “资源”页面。 当您找到感兴趣的页面时，请将它们添加到资源文档中。您可以通过导出您的书签或通过保留一个单独的文本文件来实现此目的，该文本文件按子类别对资源进行排序。现在付出一点努力将为您节省以后的大量时间。

    有关 DocBook 书目标记的更多信息，请参见 第 D.7 节。

  • 在您进行时写下主题领域。 如果您正在进行卡片分类，您可能会发现写下主题卡片特别有用，因为您找到了涵盖该特定主题的页面。在卡片顶部写下主题领域。在卡片的主要区域中，写下一些关于您可能在该主题下涵盖的内容的注释 - 包括包含重要信息的页面的标题。如果一个子主题变得太大，您可能需要将其划分为多个卡片。

  • 将通用信息与版本特定信息分开。 您描述的软件的新版本可能会在您发布文档后的第二天发布。其他事情，比如从哪里下载软件，不会改变。或者，您可以选择记录特定软件的旧问题，以此鼓励读者升级到可用的最新版本：“已知软件的 X 版本存在特定错误。该错误已在 Y 版本中修复。”

  • 保存所有相关电子邮件。 人们通常会对您正在撰写的问题有有趣的见解。有关您主题的任何问题都应在最终文档中解决。如果您正在撰写有关软件的文章，请确保询问人们他们正在使用的系统。在您的文档中添加有关您的指令已在哪些系统配置上经过测试的信息。（拥有许多具有适度不同配置的朋友可能非常有利！）所有这些个人经历都可以大大添加到您的最终文档中。

第 4 章。写作

4.1. 撰写文本

到现在为止，您应该已经组织好了您的文档；您收集了原始信息，并将它们插入到大纲中。您接下来的挑战是将所有收集到的原始数据整合为一个可读、有趣且易于理解的整体。如果您正在使用现有文档，请确保将所有新的信息放在最合适的位置。

要到达您可以真正开始写作的地步，需要花费相当多的精力，不是吗？好吧，辛勤的工作现在开始为您带来回报。在这个阶段，您可以开始真正地发挥您的想象力和创造力来传达这堆信息。但不要太聪明！您的读者已经在努力理解新的概念了——不要让他们同时还要努力理解您的语言。

有很多经典的写作指南——其中许多可以在网上找到。它们的语言可能看起来很古老，但这些信息对今天的作者仍然很有价值。这些指南在[此处]列出。资源部分还列出了许多包含技术写作特定信息的网站。

如果不提及“简明语言运动”，《作者指南》就不完整。虽然它是针对简化政府文件的，但 编写用户友好的文档 非常有用。它包括修改前后的写作样本。还有一个 PlainTrain 写作教程。

任何讨论网页写作的文档，都不能不提及 useit.com。 以下文章可能特别感兴趣：

有很多关于网页文档写作的资源——快速的网页搜索 "web writing" 将找到很多资源。但是不要太分心：最终目标是写作，而不是阅读关于写作的文章！

4.1.1. 写作风格和风格指南

有很多行业风格指南定义了如何在文档中使用语言。美国英语的一个常见例子是 芝加哥风格手册。它定义了诸如：句号(.)应该在 “引号” 内部还是外部；以及引用另一个文档的格式。风格指南有助于保持文档的一致性——大多数公司会遵循风格指南来格式化媒体发布和其他宣传材料。风格指南也可能定义单词应该如何拼写（是color还是colour？）。

LDP不要求特定的风格指南；但是，您应该在整个文档中使用一致的风格。您的文档应该针对单一语言进行拼写检查（例如，美国英语与英国英语）。审核者HOWTO 目前列出了LDP文档的许多约定，它最接近于官方的LDP风格指南。

Tip个人术语表
 

制作一个列表，列出您在开始研究和编写文档时遇到的新术语，这很有帮助。您可以在编写文本时参考此列表。您可能还想将其作为术语表包含在最终文档中。

如果您事先决定如何编写文档，您可以节省大量的编辑时间。如果您要接手别人的文档，您可能需要：修改自己的风格以适应当前的文档；或者编辑文档，使其与您希望从现在开始使用的风格融合。

从写作风格的角度来看，在 HOWTO 中使用第一人称会增加其魅力——这是大多数其他文档所严重缺乏的属性。不要害怕为自己说话——使用单词 “我” 来描述您的个人经历和观点。

4.1.2. 在线写作资源

在本节中，您将找到一个资源列表，这些资源比本指南更能覆盖该主题。查阅它们，并遵循它们的建议。

4.2. 编辑和校对文本

一旦您写好了 HOWTO 的文本，就该对其进行润色和改进了。好的编辑可以使一个好的 HOWTO 变成一个伟大的 HOWTO。

编辑的目标之一是删除[多余的]材料，这些材料已经悄悄地进入您的文档。您应该仔细阅读您的 HOWTO，并无情地删除任何对读者理解主题内容没有贡献的内容。作者在写作过程中偏离主题是很自然的。现在是纠正的时候了。通常，在编写文档和编辑文档之间留出一段时间会有所帮助。

确保每个部分的内容与标题完全匹配。您最初的主题标题可能不再相关。如果您偏离了最初的标题，则可能意味着以下情况之一：最初的标题措辞不当，新材料实际上应该放在不同的部分，或者新材料对于您的文档而言实际上是不必要的。如果您需要更改标题，请检查原始主题标题是否仍然重要。如果是，请确保该主题在文档的其他地方有所涵盖。

在编辑和校对您的作品时，检查明显的错误，例如拼写错误和打字错误。您还应该检查更深层次但不太明显的错误，例如信息中的“漏洞”。如果您正在创建一组说明，则在新的机器上测试它们可能会有所帮助。例如，有时需要安装一些软件包，但您忘记在文档中提及。

当您对作品的质量和准确性完全满意时，将其转发给其他人进行第三方校对。您将过于接近该作品，无法看到根本性的缺陷。让其他人也测试这些说明。确保他们完全按照您所写的内容进行操作。要求任何测试您的文档的人在他们没有遵循您的说明的任何地方（以及他们没有遵循的原因）做具体笔记。例如：“我跳过了第 2 步，因为我已经安装了所需的软件包。”

从某种意义上说，编辑就像软件开发中的代码审查。让程序员审查他们自己的代码没有多大意义，让作者编辑他们自己的文档也没有多大意义。招募一个朋友，或在讨论列表中找到一个志愿者，在提交您的文档之前进行校对。您可能还需要将您的文档提交到与您的文档主题相关的邮件列表。列表成员应该能够帮助检查事实、说明的清晰度和文档的语言。

Note母语者？
 

如果您正在使用您不流利的语言进行写作，请找一位以该语言为母语的编辑。技术文档，比任何其他类型的写作，都必须使用极其精确的语法和词汇。滥用语言会降低您的文档的价值。

4.3. 写作、编辑和维护您的文档的工具

Caution提醒
 

您无需以纯文本以外的任何格式将您的初始文档提交给 LDP！也接受其他开放式提交格式，例如 OpenOffice 文档、RTF 文件或 HTML。LDP 志愿者会将您的文档转换为 DocBook。一旦转换完成，您将需要以 DocBook 格式维护您的文档，但这应该是显而易见的。

4.3.1. 编辑工具

您可以使用任何文字处理或文本编辑工具来编写您的初始文档。当您进入标记阶段时，您可能需要使用可以识别 DocBook 文件的文本编辑器。至少，一个为您的标记添加语法高亮显示的程序将使生活更加轻松。有关可以处理 DocBook 文件的编辑器的说明，请跳至 B.2 节。

4.3.2. 并发版本系统 (CVS)

LDP 为其作者提供可选的 CVS 访问权限。这可以实现协作写作，并具有以下积极影响：

  1. CVS 会保留您文档的异地备份。如果您将文档交给另一位作者，他们只需从 CVS 中检索文档并继续。如果您需要返回到文档的先前版本，您也可以检索它。

  2. 从组织的角度来看，让多个人员同时处理同一文档是一件很棒的事情。CVS 使您能够做到这一点。您可以让 CVS 告诉您在您编辑副本时其他作者所做的更改，并将这些更改集成起来。

  3. CVS 会保存所做更改的日志。这些日志（和一个时间戳）可以在发布文档时自动放置在您的文档中。

  4. CVS 可以与脚本结合使用，以在编写和提交新文档时自动更新 LDP 网站。这尚未到位，但这是一个目标。目前，CVS 更新会通知 HOWTO 协调员更新 LDP 网页，这意味着如果您使用 CVS，则无需通过电子邮件发送您的 XML 代码。（尽管当您准备好发布文档时，您仍然需要向提交列表发送电子邮件，因为整个发布过程尚未完全自动化。）

Note访问我们的 CVS 存储库
 

只有提交了至少三个文档的作者才能访问我们的 CVS，请参阅 附录 C。

有关如何使用 CVS 维护您的 LDP 文档的更多信息，请阅读 附录 C。

4.3.3. 拼写检查

某些写作工具会自带拼写检查工具。此列表仅适用于您的应用程序没有拼写检查选项的情况。

拼写检查软件

aspell http://aspell.sourceforge.net

此拼写检查应用程序可以绕过 XML 标签。通过区分内容和标记，aspell 能够检查您的内容并忽略它不应该关注的部分。如果您在标记标签中遇到拼写错误，您可能正在使用旧版本，应该升级。

aspell 命令随 aspell 软件包一起提供，该软件包包含在大多数 Linux 发行版中。按如下方式使用该命令：

aspell-c 文件

交互式用户界面允许快速轻松地纠正错误。使用--help阅读更多关于 aspell 功能的信息。

ispell http://www.cs.hmc.edu/~geoff/ispell.html

类似于 aspell，但会尝试拼写检查您的标记标签。如果可以选择，请使用 aspell，否则，ispell 是一个非常可以接受的替代品。

第五章. 标记

5.1. 标记：一个通用概述

标记语言是一种用于标记或给文档添加标签以定义文档结构的系统。您可以向文档添加标签来定义文档的哪些部分是段落、标题、章节、词汇表条目（列表还在继续！）。如今，有许多标记语言在使用。对于编写 Web 文档的人来说，XHTML 和 HTML 会很熟悉。LDP 使用一种称为 DocBook 的标记语言。每种标记语言都使用自己的“受控词汇表”来描述文档。例如：在 XHTML 中，一个段落会使用标签集 <p></p> 进行标记，而在 DocBook 中，一个段落会使用<para></para>进行标记。标签集是在一个准字典中定义的，该字典称为文档类型定义 (DTD)。

标记语言还遵循一套关于如何组装文档的规则。这些规则要么是 SGML（标准通用标记语言），要么是 XML（可扩展标记语言）。这些规则本质上是文档标记的“语法”。SGML 和 XML 非常相似。XML 是 SGML 的一个子集，但 XML 在标记文档时需要更精确地使用标签。LDP 接受 SGML 和 XML 文档，但更喜欢 XML。

一个 XML/SGML 文档有三个组成部分，供人阅读。

  • 内容。 作为 TLDP 作者，记住这是最重要的部分是好的。许多作者会先写内容，然后再添加标记。内容可能包括纯文本和图形。这是 LDP 作者唯一需要的部分！

  • 标记。 为了描述文档的结构，在内容之上添加一个受控词汇表。它用于区分不同类型的内容：段落、列表、表格、警告（等等）。标记还必须符合 SGML 或 XML 规则。如果您不习惯向文档添加标记，TLDP 志愿者会为您完成。

  • 转换。 最后，将文档从 DocBook 转换为 PDF、HTML、PostScript，以便以数字或纸质形式显示。这种转换通过文档样式语义和规范语言 (DSSSL) 进行控制。DSSSL 告诉进行转换的程序如何将原始标记转换为人类可以阅读的内容。LDP 使用一系列脚本来自动执行这些转换。您不需要转换自己的文档。

Note内容、标记和转换
 

Steve Champeon 在他的文章 标记的秘密生活 中，很好地解释了内容、标记语言和转换是如何结合在一起的。虽然他是从 HTML 的角度来写的，但这些想法是相关的，并且有一个 DocBook 标记的例子。

5.2. DocBook：它是什么以及我们为什么使用它

根据官方 DocBook 网站，

 

DocBook 是一种通用的 XML 和 SGML 文档类型，特别适合于关于计算机硬件和软件的书籍和论文（尽管它绝不仅限于这些应用）。

 
--DocBook.org 

Tip对于不耐烦的人
 

在接下来的章节中，我们将解释 DocBook 的理论方面、它的起源、发展、优点和缺点。如果您只想了解实践方面，请查看以下章节，了解 HOWTO DocBook 的概述：附录 D 和 附录 E 来自本指南。

Caution对于初学者
 

我们希望再次强调，任何开放的文档格式都将被接受。如果您觉得使用纯文本、OpenOffice 或 HTML 更舒服，那对我们来说都没问题。如果您不希望学习 DocBook，LDP 志愿者会将您的文档转换为 DocBook XML。对我们来说，对于我们的作者来说，最重要的任务是实际写作，而不是格式化，请记住这一点！

然而，从提交的那一刻起，您将必须以这种 XML 格式维护您的文档，但这很容易。保证。

尽管还有其他 DTD 用于编写文档，但有几个原因不使用它们。

  • DocBook 是最流行的 DTD，被 GNOME、Python 和 FreeBSD 等十几个主要的开源项目使用。

  • DocBook 的工具比其他工具更发达。大多数 Linux 发行版都包含 DocBook 支持，允许您发送原始文件以在接收者的端进行处理。

  • 最后，DocBook 拥有一套广泛的标签（总共有 300 多个），当您尝试描述文档的内容时，这非常有用。幸运的是，对于新作者来说，大多数标签不需要用于简单的文档。

仍然不相信？Eric Raymond 撰写了一篇 DocBook 揭秘 HOWTO，这可能会有所帮助。

相信了，但仍然不习惯使用 DocBook？试试 David Lawyer 的 Howtos-with-LinuxDoc-mini-HOWTO。

5.3. XML 和 SGML：我们为什么使用 XML

DocBook 有几种不同的风格——包括 XML 和 SGML 格式。这意味着您可以在添加标记时使用 SGML 语法/规则，也可以使用 XML 语法/规则。无论哪种方式，您只能在整个文档中使用一组规则，并且您必须在文档顶部定义您正在使用的规则。

LDP 更喜欢 DocBook 的 XML 风格。这有很多原因，包括以下几点

  1. 处理 XML 文件的库正在快速发展。这些实用程序可能会使新的创作工具更容易获得。

  2. 许多流行的文字处理程序现在正在创建 XML 输出。虽然它可能不是 DocBook XML，但这确实使应用程序编写者更容易添加 DocBook XML 支持，或者提供某种在他们的格式和 DocBook XML 之间进行翻译的方法。

  3. 其他人都这样做。虽然这可能不是一个真正的原因，但它允许 LDP 与类似的项目保持同步。工具、程序和问题可以在一个共同的框架中解决。

仍然不相信？幸运的是，LDP 确实接受许多其他输入文件格式。接受的标记语言列表可以在 第 5.4 节中找到

5.4. TLDP 接受的标记语言

LDP 将其文档存储在以下标记语言中

  1. DocBook XML 版本 4.2（首选），4.1.2

  2. DocBook SGML 版本 4.2、4.1 或 3.x

  3. LinuxDoc SGML

Note新文档
 

新文档可以以任何格式提交给 LDP。不是 DocBook 或 LinuxDoc 的文档将由志愿者转换。作者负责将标记添加到所做的任何修订中。

第六章. 分发您的文档

6.1. 在分发您的文档之前

在您分发文档之前，您还需要检查一些事项，并可能添加到您的文档中。

拼写和语法检查

您可以在 第 4.3.3 节中阅读更多关于助手应用程序的信息。您还应该检查文档的整体流程和清晰度。

摘要和其他元数据

添加一个简短的段落，清楚地定义文档的范围。有关如何使用 DocBook 添加此信息的更多信息，请阅读 第 D.6 节

致谢

给予应有的荣誉。有关何时给予荣誉的更多信息，请阅读 第 6.3 节。

许可证和版权

LDP 分发文档，但是，作者保留文档的版权。LDP 接受的所有文档都必须包含许可证和版权声明。您可以在 第 6.2.1 节中阅读更多关于此的信息。您可能还想添加免责声明，但这是可选的。有关此的更多信息，请参见 第 6.2.2 节。

验证标记

如果您要提交 DocBook 或 LinuxDoc 文档，请确保标记有效。在 第 B.3.1 节中阅读原因。

获取同行评审

您可能希望在将文档提交给 LDP 之前让其他人审查您的文档。请人们进行 同行评审 和/或 技术准确性审查。由于并非所有邮件列表都会对附件做出积极响应，您可能希望设置一个临时网站来托管您的文档。注意：这绝对是不需要的。

6.2. 许可和版权

为了使文档被 LDP 接受，它必须获得许可并符合位于 http://www.tldp.org/manifesto.html 的 LDP 宣言的 “许可要求”部分。

我们建议使用 GNU 自由文档许可证 (GFDL)，知识共享许可之一（署名-相同方式共享，或 署名-相同方式共享），或 LDP 许可证（目前正在审查中）。许可证的全文必须包含在您的文档中，包括您正在使用的许可证的标题和版本。LDP 不会接受不符合许可要求的新文档。

Warning与 Debian 兼容的许可证
 

LDP 文档的 Debian 软件包维护者已将 LDP 文档划分为具有“自由”许可证的文档和具有“非自由”许可证的文档。有关此列表的摘要，请阅读 Debian 许可证摘要。目前，艺术许可证、BSD 许可证和 GNU 通用公共许可证被列为“自由”。这些许可证也将被 LDP 接受。“非自由”的定义尚未透明化。通过选择任何类型的限制重新分发或文档是否可以修改的其他许可证，您的文档可能会被放入“非自由”软件包而不是“自由”软件包。我们正在与 Debian 合作，以阐明如何做出这些决定。

您可以从 GNOME 文档项目获取 GNU GPL 和 GNU FDL 的 DocBook 标记。然后，您只需将许可证完整地包含在您的文档中。许可证的 DocBook 格式副本可在 附录 A 中获得。

有关开源文档和许可的更多信息，请查看 。

6.2.1. 版权

作为作者，您可以保留版权并添加其他限制（例如：需要批准任何翻译或衍生作品）。如果您是现有 HOWTO 的新维护者，您必须包括先前作者的先前版权声明以及他们维护该文档的日期。

6.2.2. 免责声明

如果您想包含免责声明，您可以选择使用以下内容

对于本文档的内容，我们不承担任何责任。使用本文档中的概念、示例和信息，风险自负。文档中可能存在错误和不准确之处，可能会对您的系统造成损害。请谨慎操作。尽管遵循本文档中的建议或步骤而发生事故的可能性极低，但作者不对因这样做而造成的任何损害承担任何责任。

除非另有明确说明，所有版权均归其各自所有者所有。 在本文档中使用某个术语不应被视为影响任何商标或服务标记的有效性。对特定产品或品牌的命名不应被视为认可。

6.2.3. 源代码许可

如果您的HOWTO包含您希望其他人使用的源代码片段，您可以选择在GPL下发布该源代码。

6.3. 致谢

您的文档应该有一个“致谢”部分，您可以在其中提及以任何有意义的方式为您的文档做出贡献的每个人。您应该包括翻译人员和转换人员，以及向您发送大量良好反馈的人员，可能还有教您现在正在传递的知识的人，以及对文档的制作至关重要的任何人。 大多数作者将此部分放在文档的末尾。

当其他人协助制作 LDP 文档时，您应该给予他们适当的署名，并且有 DocBook 标签专门用于执行此操作。本节将向您展示您应该使用的标签，以及在应该给予荣誉的地方给予荣誉的其他方式。署名编辑很容易 - 已经有一个<editor>DocBook中的标签。但是有两种特殊情况需要您署名，但 DocBook 没有提供特殊标签。这些是翻译人员和转换人员。

转换人员是执行源代码转换的人员，例如从 HTML 到 DocBook XML。源代码转换有助于 LDP 实现元数据的长期目标，并允许我们以多种不同的格式分发文档。

翻译人员获取您的原始文档并将其翻译成其他人类可读的语言，例如从英语到日语，或从德语到英语。 每一次翻译都使世界各地更多的人能够使用您的文档和 Linux 操作系统！

我们建议您在以新格式发布的初始版本的注释中感谢转换人员，并且我们建议您在他们翻译的每个版本中都感谢翻译人员。

NoteDocBook 中的致谢翻译
 

有关如何使用 DocBook 添加这些署名的更多信息，请阅读第 D.6 节

6.4. TLDP 审核流程

您的文档被 LDP 集合接受之前，将至少经过三个正式审核。这些审核包括 技术准确性审核、语言审核和元数据审核。所有新文档都必须通过这些审核才能被 LDP 集合接受。

当您觉得您的文档已完成时，请将副本通过电子邮件发送到 submit 邮件列表（）。请在电子邮件的主题行中包含您的文档标题和“需要最终审核”。志愿者团队将为您的文档分配进行每次审核。可能需要长达一周的时间才能组建一支有资格审核您的文档的团队。通常，首先进行技术审核，然后进行语言审核，最后进行元数据审核。您的审核人员将阅读您的文档，并向您反馈他们是否认为您的文档已准备好在 LDP 集合中发布。

您的审核人员可能有必须更改的特定要点。 做出更改后，将您的文档提交回您的审核团队。他们将再次审核该文档，并告知您您的文档是否已准备好包含在 LDP 集合中。您可能需要进行多次编辑，文档才能准备好。或者可能不需要任何额外的工作。准备好至少为技术审核和语言审核进行一轮更改。理想情况下，此交流将在 LDP 的 CVS 中进行，以便更好地跟踪所做的每一项更改，并跟踪文档的最新版本。

您的文档通过技术审核和语言审核后，您可以按照 第 6.5 节中的说明提交它。

Tip比较两个源文件
 

您的审阅者可能会直接对您的源文件进行更改，或者他们可能会将其建议放在单独的电子邮件中。如果他们直接使用源文件，并且您的文档使用的是 DocBook XML，您可能会发现 XMLdiff 对于查看您的审阅者对您的源文件所做的更改很有用。 它是一个 python 工具，可以找出两个相似的 XML 文件之间的差异，就像 diff 实用程序比较文本文件一样。

XMLdiff 可从 http://www.logilab.org/projects/xmldiff 获取。

有关审阅者将寻找什么信息的更多信息，请阅读 Linux 文档项目审阅者 HOWTO。

6.5. 向 LDP 提交以供发布

Note最后一步
 

本节包含有关在您的文档收到 LDP 志愿者的技术审核和语言审核后该怎么做的信息。

作为审核过程的一部分，审核协调员会将您的文档（包括任何相关的图像文件）添加到 CVS 中，并通知 submit 邮件列表您的文档已准备好发布。

如果您还没有 CVS 帐户，请在提交您的文档以供发布时申请一个。您可以通过联系 LDP CVS 主管 Sergiusz mailto:ser@gnu.org 来申请帐户

第 7 章. 维护

7.1. 维护您的文档

仅仅因为您的文档现在已发布并不意味着您的工作已经完成。 Linux 文档需要定期维护，以确保它是最新的，并根据读者的想法和建议对其进行改进。 TLDP 是一个鲜活的、不断增长的知识体系，而不仅仅是一个发布即忘记的静态实体。

将相关的邮件列表添加到您的文档中，人们可以在其中获得支持。如果您有时间，请自己关注这些邮件列表，以了解最新信息。

将您的电子邮件地址放在文档中，并礼貌地向您的读者请求反馈。正式发布后，您将开始收到带有建议的笔记。其中一些电子邮件将非常有价值。在您的邮件程序中创建一个文件夹，用于存放收到的建议 - 时机成熟时，请查看该文件夹并更新您的文档。如果您关注相关的邮件列表，您也可以选择将列表中重要电子邮件的副本保存到此文件夹。

Note我们不是免费的支持服务，但是……
 

一些给您发送电子邮件的人会请求个人帮助。如果您没有时间，您可以自由拒绝个人帮助。 为 LDP 撰写投稿并不意味着您承诺为网络上的任何人提供终身免费支持； 但是，请尽量回复所有请求并建议一个（希望）能够为您的读者提供支持的邮件列表。

7.2. 修复错误

7.2.1. 修复您自己的文档

如果您在自己的文档中发现错误，请修复它并重新提交文档。您可以通过将文件通过电子邮件发送到.

如果您一直在使用 CVS，您可以将您的更改提交到 CVS 树，然后向 submit 邮件列表发送说明（）。请在您的电子邮件中提供您的文档在 CVS 树中的确切路径。

请记住更新文档顶部的修订历史。

7.2.2. 修复集合中的其他文档

如果您在其他人的文档中发现错误，请联系该文档的作者并提供更正。如果您在“合理”的时间内没有收到作者的回复，请发送电子邮件至 LDP 协调员(需要订阅) 并描述问题以及您认为需要如何修复它。如果许可证允许，您可能会被要求直接对文档进行更改。如果问题严重，该文档可能会从集合中删除，或者移至“未维护”部分。

Note接管未维护的文档
 

有关如何处理未维护的文档的更多信息，请阅读：未维护（包括接管未维护文档的“所有权”的步骤列表，以及未维护文档的列表）。

参考资料

标记和一般信息

标记的秘密生活, http://hotwired.lycos.com/webmonkey/02/42/index4a.html, Steve Champeon.

渐进增强和 Web 设计的未来: 我们现在在哪里 , http://hotwired.lycos.com/webmonkey/03/21/index3a_page2.html, Steve Champeon.

SGML, http://www.w3.org/MarkUp/SGML/.

DocBook 参考

DocBook XML 4.1.2 快速入门指南, http://www.jimweller.net/jim/dbxmlqs/index.html, Jim Weller.

 

描述如何安装、配置和使用 DocBook XML 4.1.2 的工具和资源。本快速入门指南的目的是让新的 docbook 作者、编辑和贡献者能够快速启动并运行 DoocBook 工具。 这些是在作者手中强大的工具。它假定对构建和安装源代码包有一定的了解。 可能有一百万零一种方法可以完成我安装和使用这些工具的最终目标。 这种方法对我来说效果很好。

 
--Jim Weller 

安装和使用 XML/SGML DocBook 编辑套件为 Windows 和 Unix/Linux/BSD 设置免费的 XML/SGML DocBook 编辑套件, http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/build/tutorials/docbooksys/docbooksys.html , Ashley J.S. Mills, 2002.

快速掌握 DocBook, http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/build/tutorials/UniDocBook/UniDocBook.html, Ashley J.S. Mills, 2002.

DocBook：权威指南, http://www.docbook.org/, Norman Walsh, Leonard Muellner, 1999, 1-56592-580-7, O'Reilly & Associates, Inc..

这本书由 O'Reilly 于 1999 年 10 月发布，是 DocBook 的优秀参考资料。但我认为它不是一本很好的实用书籍。您可以在您选择的书商处购买，也可以在上面的 URL 在线获取整本书（HTML 和 SGML 格式）。

Simplified DocBook: The Definitive Guide, http://www.docbook.org/tdg/simple/en/html/sdocbook.html, Norman Walsh, Leonard Muellner, 1999.

Simplified DocBook, http://www.oasis-open.org/docbook/xml/simple/.

XML Matters: Getting started with the DocBook XML dialect, http://www-106.ibm.com/developerworks/xml/library/xml-matters3.html.

FAQ for DocBook markup, http://www.dpawson.co.uk/docbook/markup.html.

Single-Source Publishing with DocBook XML, , http://www.lodestar2.com/people/dyork/talks/2002/ols/docbook-tutorial/frames/frames.html, Dan York, 2002.

DocBook Install mini-HOWTO, https://tldp.cn/HOWTO/mini/DocBook-Install/, Robert Easter.

Exploring SGML DocBook, http://lwn.net/2000/features/DocBook/, Giorgio Zoppi.

LinuxDoc

Howtos-with-LinuxDoc-mini-HOWTO, http://www.tldp.org/HOWTO/Howtos-with-LinuxDoc.html, David Lawyer.

LinuxDoc-SGML User's Guide, http://www.nmt.edu/tcc/doc/guide.html.

转换其他格式为 DocBook

Converting HTML to Docbook SGML/XML Using html2db, http://www.cise.ufl.edu/~ppadala/tidy/.

5-Minute Review: Using LyX for Creating DocBook, http://www.teledyn.com/help/XML/lyx2db/t1.html.

Document processing with LyX and SGML, http://www.karakas-online.de/mySGML/.

LDP 模板、工具和链接

LDP Templates, , http://www.tldp.org/authors/index.html#resources .

包含指向 SGML 模板及其生成的 HTML 输出的链接，以帮助您了解文档的外观。许多标签只需要替换为您 HOWTO 特有的信息。还包含指向工具和其他有用信息的链接。

Linux Documentation Project HOWTO Generator, The, http://www.nyx.net/~sgjoen/The_LDP_HOWTO_Generator.html.

这是一个独立的网页，其中包含许多要填写的字段和几个按钮。准备就绪后，单击编译按钮开始编译所有输入字段，并将所有内容包装在正确的 LinuxDoc SGML 中，以便使用 LinuxDoc SGML 工具进行处理。

编译后的输出会输出到网页底部的只读文本区域，因此必须将文本复制并粘贴到文件中进行编译。

目前不支持 DocBook。

DocBook 转换

DocBook XML/SGML Processing Using OpenJade, , https://tldp.cn/HOWTO/DocBook-OpenJade-SGML-XML-HOWTO/, Saqib Ali.

通用写作链接和风格指南

Guide to Grammar and Style, http://newark.rutgers.edu/~jlynch/Writing/, Jack Lynch.

Purdue's Online Writing Lab, http://owl.english.purdue.edu/.

Chicago Manual of Style, http://www.chicagomanualofstyle.org/.

Plain Language Resources, http://www.plainlanguagenetwork.org/Resources/.

Writing User-Friendly Documents, http://www.blm.gov/nhp/NPR/pe_toc.html.

这非常有用。 它包括写作样本的前后对比。

PlainTrain Writing Tutorial, http://www.web.net/~plain/PlainTrain/IntroducingPlainLanguage.html.

Writing for the Web, http://www.useit.com/papers/webwriting/.

Information Pollution, http://useit.com/alertbox/20030811.html.

Be Succinct! (Writing for the Web), http://useit.com/alertbox/9703b.html.

Politics and the English Language, http://www.k-1.com/Orwell/index.cgi/work/essays/language.html, George Orwell.

一部关于写作的经典著作。

Elements of Style, The, http://www.bartleby.com/141/, Strunk and White.

一部关于写作的经典著作。

A Short Handbook and Style Sheet, http://newark.rutgers.edu/~jlynch/Writing/m.html#mechanics, Thomas Pinney.

Technical Writing Links, http://www.techcomplus.com/tips.htm.

Technical Writing Tutorial, http://psdam.mit.edu/rise/tutorials/writing/technical-writing.html.

Strategies to succeed in technical writing, http://www.school-for-champions.com/techwriting.htm.

User Guides Online Tutorial, http://www.klariti.com/technical-writing/User-Guides-Tutorial.shtml.

DMOZ Technical Writing Links, http://dmoz.org/Arts/Writers_Resources/Non-Fiction/Technical_Writing/.

techwr-L, http://www.raycomm.com/techwhirl/magazine/.

Technical Writing Links, http://academic.middlesex.cc.ma.us/PeterHarbeson/links.html.

链接的汇总--仔细搜索好东西。

相关 TLDP 文档

Linux Documentation Project (LDP) FAQ, https://tldp.cn/FAQ/LDP-FAQ/index.html, Rahul Sundaram.

LDP HOWTO-INDEX, https://tldp.cn/HOWTO/HOWTO-INDEX/, Guylhem Aznar, Joshua Drake, Greg Ferguson.

软件：CVS

CVS: Project Management, http://doc.cs.byu.edu/programming/cvs/, Byron Clark.

CVS, http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/build/tutorials/cvstute/cvstute.html, Ashley J.S. Mills, Alan P. Sexton.

CVS--Concurrent Versions System, http://www.loria.fr/~molli/cvs/doc/cvs_toc.html, Pascal Molli.

Learning About CVS , http://cvshome.org/docs/.

软件：Emacs

Information about PSGML , http://www.lysator.liu.se/~lenst/about_psgml/.

Emacs: The Free Software IDE, https://linuxjournal.cn/article.php?sid=576.

Emacs/PSGML Quick Reference, http://www.snee.com/bob/sgmlfree/psgmqref.html, Bob Ducharme.

NT Emacs Installation, http://www.charlescurley.com/emacs.html, Charles Curley.

Cygwin Packages for DocBook Authoring, http://www.docbook.org/wiki/moin.cgi/CygwinPackages/.

SGML for Windows NT: Setting up a free SGML/XML editing and publishing system on Windows/Cygwin , http://ourworld.compuserve.com/homepages/hoenicka_markus/cygbook1.html, Markus Hoenicka, 2000.

Vim, http://www.newriders.com/books/opl/ebooks/0735710015.html, Steve Oualline.

XML 创作工具

Saqib's list of XML Authoring Tools, http://www.xml-dev.com/xml/editors.html.

文档许可证

Licensing HOWTO, http://www.catb.org/~esr/Licensing-HOWTO.html, Eric Raymond, Catherine Raymond.

 

本文档解释了美国版权和许可法如何应用于开源软件项目。它比较了现有开源许可证的优势和劣势，并提供了有关如何为您的项目选择许可证的指导。它还解释了更改项目许可证的合法性。它为应对当今高威胁的法律环境提出了新的实践——这部分是所有项目负责人必读的。

 
--Eric Raymond 和 Catherine Raymond 

OPL, http://www.opencontent.org/openpub/.

OpenContent 已于 2003 年 6 月 30 日正式关闭。

Creative Commons, http://creativecommons.org/licenses/by-sa/1.0/.

GNU Free Documentation License, https://gnu.ac.cn/copyleft/fdl.html.

GNU General Public License, https://gnu.ac.cn/licenses/licenses.html#GPL.

如果您希望将您的文档包含在主要的 Debian 发行版中，您应该使用此许可证。然而，这不是 LDP 的首选许可证。

附录 A. 模板

LDP 将其文档存储在以下标记语言中

  1. DocBook XML 版本 4.2（首选），4.1.2

  2. DocBook SGML 版本 4.2、4.1 或 3.x

  3. LinuxDoc SGML

Note新文档
 

新文档可以以任何格式提交给 LDP。不是 DocBook 或 LinuxDoc 的文档将由志愿者转换。作者负责将标记添加到所做的任何修订中。

A.1. 文档模板

  1. HOWTO (文章) templates/ldp-howto.zip. 大多数 HOWTO 文档将使用此模板。

  2. 指南 (书籍) templates/ldp-guide.zip. 使用此模板创建完整的书籍（例如本作者指南）。 由 Tille Garrels 提供的模板。

  3. FAQ templates/ldp-faq.zip. 用于编写 FAQ（常见问题解答）列表的标准文章。

  4. LinuxDoctemplates/ldp-linuxdoc.zip. HOWTO 长度和 Guide 长度的标准模板。

  5. 免责声明 disclaimer.xml. 一个标准免责声明，警告读者 (1) 您的文档可能并不完美，并且 (2) 如果因文档导致任何问题，您概不负责。

A.2. 样式表

以下样式表可用于使您的文档看起来更漂亮。请记住，LDP 将使用其自己的样式表来分发您的文档。

  1. DSL 样式表 style.dsl. 此 DSL 样式表由 Tille 提供，将与 DSSSL 转换一起使用。

  2. 层叠样式表 style-ob.css. 此 CSS 文件由 Saqib Ali 和 Emma Jane Hogbin 提供。 "ob" 代表 "orange and blue"（橙色和蓝色）。 将此 CSS 文件与 HTML 文件一起使用。 CSS 文件中包含说明。

A.3. GNU 自由文档许可证

GFDL（GNU 自由文档许可证）的 XML 格式可在 https://gnu.ac.cn/licenses/fdl.xml 获取。 要获取适合包含在文档中的附录格式版本，您可以从 CVS 获取本文档的 XML，网址为 http://cvsview.tldp.org/index.cgi/LDP/guide/docbook/LDP-Author-Guide/fdl-appendix.xml。

用于 DocBook（XML 和 SGML）和 Linuxdoc SGML 的 TLDP 模板文件可从 TLDP 网站 http://www.tldp.org/authors/index.html#resources 获取。

附录 B. 系统设置：编辑器、验证和转换

在本节中，我们将介绍一些您可能用于创建自己的 LDP 文档的工具。如果您使用其他工具来帮助您编写 LDP 文档，请给我们留言，我们会在本文中添加一段介绍。 第 1.3 节包含联系方式。

B.1. 适用于您的操作系统的工具

关于设置您的系统进行 DocBook 发布的一些注意事项。这些工具更侧重于将文档从 DocBook 转换为 XHTML（例如）。

适用于您的操作系统的工具

Debian

http://www.docbook.org/wiki/moin.cgi/DebianGnuLinuxPackages

Morgon Kanter 建议使用 apt-get install docbook-xml docbook-xsl xsltproc 作为最低要求。 http://lists.tldp.org/index.cgi?1:mss:4851

Fedora (也就是新的 RedHat)

Charles Curley (http://www.charlescurley.com) 贡献的说明。

DocBook SGML 和 XML 的工具包含在发行版中。 Emacs 和 PSGML 模式 也包含在内，尽管您需要自定义您的.emacs。如果在安装 Fedora 后缺少软件包，请熟悉 yum 或 apt。

安装说明：无；在使用编写完成之前，请使用 Red Hat 9：https://127.0.0.1/docs/manuals/linux/RHL-9-Manual/。

Mandrake

Artemio (http://www.artemio.net) 贡献的说明。

在 Mandrake 中（就我当前的 9.2 而言），所有东西，包括 openjade、xmlto、docbook-utils 等等，都是标准配置。

所以我只需要获取 TLDP XSL sheet，仅此而已。从来没有任何依赖或其他问题，一切正常（敲木头 :-））。

RedHat

根据 Hal Burgiss 的说法，您的系统可能已经准备好编辑和处理 DocBook 文档，而无需安装任何其他软件包。

B.2. 编辑工具

编辑工具在对 XML（尤其是 DocBook）的支持方面已经取得了长足的进步。本节概述了两种类型的编辑器：文本编辑器（emacs、vim 等）和文字处理器（OpenOffice、AbiWord 等）。不熟悉标记语言的新作者可能应该选择可以输出 DocBook 文件的文字处理器。因此，文字处理器首先列出。

虽然许多编辑器也可以验证您的 DocBook 文件，但此信息已分隔到 第 B.3 节。

Note更多信息
 

查看资源部分以获取更多信息。

B.2.1. 文字处理器

即使您不习惯在文本编辑器中使用 DocBook 的标签集，您仍然可以使用文字处理器生成有效的 DocBook 文档。 目前的支持非常有限，但以下程序中确实存在。 当然，好处是程序内置了拼写检查等功能。 除此之外，对 DocBook（和 XML）的支持也在不断改进。

Note转换 Microsoft Word 文档
 

即使您想使用 MS Word 编写文档，您可能会发现 w2XML 很有用。 请注意，这不是免费软件 - 费用约为 130 美元。 但是，该软件有一个试用版。

Note专注于内容！
 

请记住，当您的文档由 LDP 发布时，您对文档所做的所有格式更改都将被忽略。 不要专注于您的文档看起来如何，而应专注于内容。

B.2.1.1. AbiWord

通过口口相传，我听说 AbiWord 可以（本地）使用 DocBook 文档。 这需要由某人（可能是我）进行测试，如果确实如此，则绝对应该包含在内。

B.2.1.2. OpenOffice.org

http://openoffice.org

从 OpenOffice.org (OOo) 1.1RC 开始，已经支持将文件导出为 DocBook 格式。

虽然 OOo 使用完整的 DocBook 文档类型声明，但它实际上并没有导出 DocBook 元素的完整列表。 它使用 “简化”的 DocBook 标签集，该标签集适用于即时渲染。 （尽管它不是 第 B.5 节中描述的官方简化 DocBook。）OpenOffice 简化（或 “特殊” docbook）可从 http://xml.openoffice.org/xmerge/docbook/supported_tag_table.html 获得。

B.2.1.2.1. Open Office 1.0.x

OOo 已经过 LDP 志愿者的测试，结果大多是积极的。 感谢 Charles Curley (charlescurley.com) 提供的有关使用 OOo 版本 1.0.x 的以下说明

Note检查您的 OpenOffice 版本
 

这些说明可能不适用于您正在使用的 OOo 版本。

  • 为了能够导出到 DocBook，您必须安装 Java 运行时环境 (JRE) 并在 OOo 中注册 - 建议至少使用 4.2.x 版本。 配置说明将取决于您安装 JRE 的方式。 请访问 OOo 网站以获取有关设置的帮助。

    与 OOo 文档相反，Linux OOo 没有附带 JRE。 我从 Sun 得到一个。

  • 导出的文件有很多空行。 我导出的 54 行文件有 5 行实际 XML 代码。

  • 没有进行美化打印。

  • 标头是<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

  • 文件格式的 文件->另存为对话框中的下拉菜单指示导出格式为 “DocBook (简化版)”。 没有任何解释说明 “简化” 表示什么。 OOo 是否导出 DocBook 的子集？ 如果是这样，哪些元素被忽略了？ 有没有办法手动输入它们中的任何一个？

  • 没有关于 DocBook 导出过滤器或 OOo 是否会再次导入它的文档。

结论：如果您想要一个用于准备 DocBook 文档的文字处理器，那么 OOo 1.1RC 值得一看。

但是，我希望他们能解决缺少文档的问题。 例如，很高兴知道哪些本机 OOo 样式映射到哪些 DocBook 元素。 也很高兴知道如何将自己的 OOo 样式映射到 DocBook 元素。

B.2.1.2.2. Open Office 1.1

Tabatha Marshall 提供了以下有关 OOo 1.1 的其他信息。

第一个问题是当我尝试在版本 1.0.1 上完成所有操作时。 这显然是一个问题。 我有 RH8，它是通过 rpm 软件包安装的，所以我把它撕下来并全新安装了 OpenOffice 1.1。 花了一段时间才发现 1.1 是 XML 工作的必要条件。

在安装过程中，我相信我被提供了安装 XML 功能的选择。 我倾向于完整安装我的办公程序，所以我选择了所有内容。

我无法为那些试图更新其当前 OO 1.1 的人提供任何建议。 他们的 “3 种方式” 在该网站 (xml.openoffice.org) 上没有得到很好的记录，并且在撰写本文时，我甚至无法在该网站上找到 THAT。 我认为需要更多当前的文档来引导人们完成整个过程。 大部分内容都不清楚，我必须进行实验才能使事情正常工作。

好吧，在我安装完所有内容后，我需要进行一些配置。 我打开了应用程序，然后通过打开一个新文件，选择模板，然后选择 DocBook 模板开始了。 出现了一个不错的 段落样式 菜单供我使用，这些是所有这些标签的名称，我注意到了（您可以看到我不经常使用 WYSIWYG）。

在一个空白文档摆在我面前（除非打开某种类型的文档，否则无法进入 XML 过滤器设置 菜单），我进入 工具->XML 过滤器设置，并编辑 DocBook 文件的条目。 我将我的配置如下

  • Doctype -//OASIS//DTD DocBook XML V4.2//EN

  • DTD http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd

  • 用于导出的 XSLT /usr/local/OpenOffice.org1.1.0/share/xslt/docbook/ldp-html.xsl

  • 用于导入的 XSLT /usr/local/OpenOffice.org1.1.0/share/xslt/docbook/docbooktosoffheadings.xsl（这是默认值）

  • 用于导入的模板 /home/tabatha/OpenOffice/user/template/DocBook File/DocBookTemplate.stw

起初，如果我打开一个甚至只有一个解析错误的 XML 文件，它仍然会打开该文件并在 OO 中显示标记。 我有很多 XML 文件使用 &copy; 和其他类型的实体，即使它们可以通过处理，也会显示为解析错误（具体取决于编码）。 但今天我无法打开任何这些文件。 我收到了输入/输出错误。 仍在调查这个问题。

但是，当您成功打开文档（没有解析错误的文档）时，它会根据标记自动将其放入 WYSIWYG 中，然后您可以像任何其他此类编辑器一样从段落样式菜单中使用它。

要验证文档，我使用了 工具->XML 过滤器设置，然后单击 测试 XSLT 按钮。 在我的屏幕上，我将用于导出的 XSLT 设置为ldp-html.xsl。 如果您测试并且存在错误，则会弹出一个新窗口，底部显示错误消息，顶部显示需要更改的行。 您可以在那里更改它们，并通过错误进行处理，直到它们全部消失，并不断测试直到它们消失。

如果要打开文件以查看源而不是处理后的结果，请转到 工具->XML 过滤器设置->测试 XSLT，然后在 导入 部分下，选中 显示源 框。 我当前的导入 XSLT 是docbooktosoffheadings.xsl（默认值）和导入模板是DocBookTemplate.stw（也是默认值）。

我认为这可能对某些人有效，但不幸的是对我不起作用。 我从未使用 WYSIWYG 来编辑标记。 带有 PSGML 的 Emacs 可以告诉我我的下一个标签是什么，无论我在哪里，都可以通过移动到问题点进行验证，并且我可以从命令行解析和处理。

使用 OpenOffice，您必须访问 http://xml.openoffice.org/filters.html 才能找到转换工具。

B.2.1.3. WordPerfect 9 (Corel Office 2000)

http://www.corel.com/

MS Windows 平台的 WordPerfect 9 支持 SGML 和 DocBook 3.0。 Linux 的 WordPerfect 9 没有 SGML 功能。

如果您在 Linux 操作系统上使用 WordPerfect，请阅读：Linux 上 WordPerfect 常见问题解答

B.2.1.4. XMLmind 的 XML 编辑器

http://www.xmlmind.com/xmleditor/

虽然严格来说，它不是一个字处理器，XMLmind 的 XML 编辑器允许作者专注于内容，而不是标记。它内置了拼写检查和转换实用程序，允许您转换文档，而无需安装和配置额外的处理工具，如 jade。有一个免费的“标准版”，这是他们的 “专业版”的简化版本。

B.2.1.5. Conglomerate

http://www.conglomerate.org

根据他们的网站，“Conglomerate 旨在成为每个人都可以使用的 XML 编辑器。 特别是，我们的主要目标是为 DocBook 和类似格式创建最终的编辑器。它旨在隐藏 XML 的术语和复杂性，并以一种有意义的方式呈现文档中的信息。”

B.2.1.6. Vex：XML 的可视化编辑器

http://vex.sourceforge.net/

根据他们的网站，“可视化部分来自于 Vex 向用户隐藏原始 XML 标签，而是提供类似字处理器的界面。 因此，Vex 最适合文档样式的 XML 文档，如 XHTML 和 DocBook，而不是数据样式的 XML 文档。”

B.2.2. 文本编辑器

Caution适用于高级作者
 

本节概述的工具允许您直接使用 DocBook 标签。 如果您不熟悉标记语言，您可能希望使用字处理器。 支持 DocBook 的字处理器在 第 B.2.1 节中进行了描述。

如果您熟悉标记语言和文本编辑器，您可能希望自定义当前选择的编辑器以处理 DocBook 文件。 以下是一些更常见的文本编辑器，经过一些调整后，可以处理 DocBook 文件。

B.2.2.1. Emacs (PSGML)

http://www.lysator.liu.se/~lenst/about_psgml/

Emacs 有一个名为 psgml 的 SGML 编写模式，这是一种主要模式，专为编辑 SGML 和 XML 文档而设计。 它提供

  • “语法突出显示”或“漂亮打印”功能，使标签脱颖而出

  • 一种插入标签的方式，而不是手动输入它们

  • 以及在编写时验证文档的能力

对于 Emacs 用户来说，这是一个不错的选择。 PSGML 同样适用于 DocBook、LinuxDoc 和其他 DTD。

B.2.2.1.1. 验证 PSGML 是否已安装

如果您安装了最近的发行版，您可能已经安装了 PSGML 以供 Emacs 使用。 要检查，启动 Emacs 并查找 PSGML 文档 (C-himpsgml)。

Tip依赖项
 

如果您现在没有安装 PSGML，那么现在可能是升级 Emacs 的好时机。 这些说明的其余部分将假定您已安装 PSGML。

B.2.2.1.2. 配置 Emacs 以与 PSGML 一起使用

如果您希望 GNU Emacs 在打开.xml文件时进入 PSGML 模式，它需要能够找到 DocBook DTD 文件。 如果您的发行版已经设置了 PSGML 以供 GNU Emacs 使用，您可能不需要做任何事情。

Note调整 Emacs
 

有关如何配置 Emacs 的更多信息，请查看 。

一旦您配置了系统以使用 PSGML，您需要使用 psgml-mode 覆盖 Emacs 的默认 sgml-mode。 这可以通过配置您的.emacs文件来完成。 编辑配置文件后，您需要重新启动 Emacs。

B.2.2.1.3. 创建新的 DocBook XML 文件

在 Emacs 中创建新的 DocBook XML 文件需要几个步骤。

  • 创建一个带有xml扩展名的新文件。

  • 在该文件的第一行输入您要使用的 DocBook 版本的 doctype。 如果您不确定 doctype 是什么，请查看 第 B.5 节

  • 输入 C-c C-p。 如果 Emacs 成功解析您的 DTD，您将看到Parsing prolog...done在小缓冲区中。

  • 输入 C-c C-e Enter 以自动插入文档的父元素。（新作者通常撰写articles。）

  • 如果一切正常，您应该在文档类型声明之后看到文档父元素的新标签。 换句话说，您现在应该看到两个额外的标签<article>和</article>在你的文档中。

B.2.2.1.4. Emacs 中的拼写检查

通过将以下内容添加到您的~/.emacs文件，可以将 Emacs 配置为使用 aspell。 感谢 Rob Weir 提供此配置信息。

;; Use aspell
(setq-default ispell-program-name "aspell")
;;Setup some dictionary languages
(setq ispell-dictionary "british")
(setq flyspell-default-dictionary "british")

B.2.2.2. epcEdit

http://www.tksgml.de

epcEdit 程序允许您编辑 XML 文件。它的优点是不需要在开始之前了解 Emacs 或 vi，并且是跨平台的，可以在 Windows 和 Linux 中工作。这是一个商业应用程序，定价可以在 http://www.tksgml.de/pricing.html 上找到

除了可视化编辑之外，epcEdit 还将在加载时以及通过使用 Document->Validate 命令按需验证文档。

图 B-1. epcEdit 屏幕截图

B.2.2.3. Morphon XML 编辑器

http://www.morphon.com/xmleditor/index.shtml

这是一个商业应用程序，目前可以免费使用（可选用户注册）。 它用 Java 编写，允许它在任何具有 Java 虚拟机的平台上运行（即，可以在 Windows 和 Linux 中工作）。

XMLEditor 的优点是屏幕的左侧显示文档的层次结构（从 Book 等开始）。 选择列表中的项目会将您带到文档的该部分，以便您可以对其进行编辑。 屏幕的右侧显示文本，不显示任何标记或标签。 如果您有作为 ELEMENT 的外部文件（如 LDP 作者指南），XMLEditor 将会跟踪链接并加载文件，因此您始终在整个作品上工作。 缺点是，如果文件丢失，您会收到错误。

B.2.2.4. nedit

http://nedit.org

公平地说，nedit 更适合程序员，因此对于新用户，特别是对于非程序员来说，它可能看起来有点过头。 撇开所有这些不谈，它非常强大，允许进行语法突出显示。 与 epcEdit 不同，nedit 不允许您自动插入标签或自动验证您的代码。 但是，它允许针对窗口的内容运行 shell 命令（而不是保存文件，然后检查）。

图 B-2. nedit 屏幕截图

B.2.2.4.1. 使用 nedit

当您打开 DocBook 文件时，nedit 应该已经启用了语法突出显示。 如果没有，您可以使用以下方法显式打开它：Preferences->Language Mode->SGML HTML

如果您启用了行号（使用 Preferences->Show Line Numbers），那么查找验证错误会简单得多。 nsgmls，我们将使用的验证工具，按其行号列出错误。

B.2.2.4.2. 配置 nedit

由于您可以将窗口的内容馈送到外部程序，因此您可以轻松地扩展 nedit 以执行重复的功能。 您将在此处看到的示例是使用 nsgmls 验证您的文档。 有关 nsgmls 和验证文档的更多信息，请阅读 第 B.3 节。

  • 选择 Preferences->Default Settings->Customize Menus->Shell Menu...。 这将打开“Shell Command”对话框，其中列出了 nedit 在 Shell 菜单下的所有 shell 命令。

  • 在“Menu Entry”下，输入 “Validate DocBook”。 这将是您在屏幕上看到的条目。

  • 在“Accelerator”下，按 Alt-S。 设置此菜单项后，您可以按 Alt-S 以自动运行 Validate DocBook。

  • 在“Command Input”下，选择“window”，在“Command Output”下，选择“dialog”。

  • 在“Command to Execute”下，输入 nsgmls -sv。 使用-v将版本号输出到屏幕，以便您知道该命令已运行。

    Note检查 PATH
     

    请注意，nsgmls 必须在您的PATH中才能正常工作。

图 B-3. 向 nedit 添加 shell 命令

  • 单击 OK，您将返回到主 nedit 屏幕。 加载 XML 文件，然后选择 Shell->Validate DocBook 或按 Alt-S。

  • nedit 程序将启动并检查窗口的内容。

  • 如果您看到的只是 nsgml 的版本号，那么您的文档是有效的。 任何错误都由文档中的行号报告。

图 B-4. 成功时 nsgmls 输出

B.2.2.5. VIM

http://www.vim.org

如果没有谈论 vi，那么对文本编辑器的任何提及都是不完整的。 VIM (Vi IMproved) 编辑器具有常规 vi 的功能，并包括标签的“语法突出显示”。

B.2.2.5.1. 入门

有许多版本的 vi。 新作者可能需要其中一个功能更丰富的版本，用于语法突出显示和一个图形界面，包括鼠标控制。

Red Hat 用户需要以下软件包：vim-common、vim-minimal 和 vim-enhanced。 Debian 用户需要以下软件包：vim。 对于 X 界面（包括 GUI 菜单和鼠标控制），用户需要 gvim。 gvim 中的 “g” 代表 “Graphical”（图形化）。

如果您需要构建自己的 VIM，则编译非常容易。 默认情况下会构建 vim 和 gvim。 如果您必须从头开始，则包含语法突出显示但默认情况下未启用；在 VIM 中使用 :syntax enable 命令来启用此功能。

B.2.2.5.2. 创建新的 DocBook XML 文件

在 vim 和 gvim 中，.xml文件将被识别并进入“SGML 模式”。 一系列已知的 DocBook 标签和属性已输入到 vim 中，如果名称已知，则将以一种颜色突出显示，如果名称未知，则将以另一种颜色突出显示（对于此作者，颜色为黄色和蓝色）。

在文档顶部使用正确的文档类型声明可以启用语法高亮。如果看不到语法高亮，你需要使用命令 :set ft=sgml 强制 VIM 进入 SGML 模式（即使是 XML 文件）。如果你正在处理单个 XML 文档的多个文件，你可以将文档类型添加到文件顶部的 <-- 注释 --> 中，以获得正确的语法高亮（你需要重启程序才能看到高亮的变化）。这个文件的第一行（tools-text-editors.xml）看起来像这样

 
<!-- <!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'> -->

B.2.2.5.3. 拼写检查

与 Emacs 一样，Vim 可以很好地与 aspell 配合使用。它可以从 Vim 中通过以下命令运行：:! aspell -c %.

对于更复杂的拼写检查替代方案，请尝试 Cream 或 vimspell。

B.2.2.5.4. 标签补全

以下信息由 Kwan Lowe 提供。

Vim 有一个 DocBook 辅助脚本，可以很容易地复制到你的.vimscripts目录中，并用于在编写 DocBook 文档时 "自动补全" 标签。该脚本可以从以下网址下载：http://www.vim.org/scripts/script.php?script_id=38。

获取该文件，然后解压它。复制dbhelper.vim到你的.vimscripts目录（如果存在）。

  	$ mkdir .vimscripts
	$ cp dbhelper.vim .vimscripts

你还需要将dbhelper.vim文件转换为 Unix 格式

	$ dos2unix dbhelper.vim

接下来，编辑你的.vimrc文件并添加以下行source /home/yourname/.vimscripts/dbhelper.vim

要使用这些脚本，进入 vi 并进入插入模式。按 , (逗号) 键，然后是快捷键。例如,dtbk

B.2.2.6. XMLForm

http://www.datamech.com/XMLForm/

这个基于 Web 的应用程序允许你输入 XML 源的 URL，或者直接将 XML 复制并粘贴到 Web 表单中。然后，该应用程序会将你的文档分解为一系列表单字段，这些字段隐藏了 DocBook 标签，以便你可以直接编辑内容。可以从 http://www.datamech.com/XMLForm/formGenerator5.html 获取版本 5。这个应用程序最适合较短的文档（少于 20 页打印）。

由于这是一个在线工具，它只适合小更新。

B.2.2.7. XMLmind XML 编辑器 (XXE)

http://www.xmlmind.com/xmleditor

David Horton 提供了以下信息

我是 XMLMind 的 XXE 编辑器和 XFC FO 转换器的忠实粉丝。它是 "免费啤酒"，但不一定是 "言论自由"。然而，对于个人使用，许可证非常宽松。它是基于 Java 的，所以它可以在各种操作系统上运行。

B.3. 验证

B.3.1. 为什么要验证你的文档

LDP 使用许多脚本来分发你的文档。这些脚本将你的文档提交到 LDP 的 CVS（一个免费的文档版本管理系统），然后将你的文档转换为用户可以阅读的其他格式。你的文档也会在世界各地的多个站点上镜像（另一组脚本）。

为了使这些脚本正常工作，你的文档必须同时 "格式良好" 并且使用 "有效的标记"。格式良好 意味着你的文档遵循 XML 期望的规则：它符合 XML 语法规则。有效的标记 意味着你只使用对你的文档 "有效" 的元素或标签：应用 XML 词汇规则。

如果你的文档格式不正确或使用无效的标记，脚本将无法处理它。因此，你的修订文档将不会被分发。

NoteDocbook 部分
 

DocBook 部分提供了关于如何验证你的文档的更多信息。查看 B.3 节 获取更多关于验证你的文档的帮助。

B.3.2. 为胆小者提供的验证

如果你不想仅仅为了验证而安装一套完整的工具，那么你的生活已经够艰难的了。你可以将你的原始 XML 文件上传到一个网站，然后访问 http://validate.sf.net，输入你的文档的 URL，然后验证它。

Note外部实体
 

当这个信息被添加到作者指南时，还不支持外部实体。如果你遇到问题，请按照 Validate 网站上提供的说明进行操作。

B.3.3. 为不太胆小者提供的验证

B.3.3.1. 目录

XML 和 SGML 文件包含你需要的大部分信息；但是，有时存在特定于 SGML 的实体。要将这些实体与其真实值匹配，你需要使用目录。目录的作用是告诉你的系统在哪里找到它正在寻找的文件。你可以将目录视为你工具的指南（或地图）。

大多数发行版（至少 Red Hat/Fedora 和 Debian）都有一个用于主 SGML 目录文件的通用位置，称为/etc/sgml/catalog。过去，它也可能在/usr/lib/sgml/catalog.

中找到。XML 目录文件的结构与 SGML 目录文件的结构不同。关于定制目录的部分（参见 B.3.4 节）将提供更多关于这些文件实际包含的内容的细节。

如果你的系统找不到目录文件，或者你正在使用自定义目录文件，你可能需要设置SGML_CATALOG_FILES和XML_CATALOG_FILES环境变量。使用 echo $SGML_CATALOG_FILES 检查它当前是否已设置。如果返回一个空行，则该变量尚未设置。使用相同的命令查看XML_CATALOG_FILES是否也已设置。如果变量未设置，请使用以下示例立即设置它们。

示例 B-1. 设置 SGML_CATALOG_FILES 和 XML_CATALOG_FILES 环境变量

bash$ export SGML_CATALOG_FILES="/etc/sgml/catalog"

要使此更改永久生效，你可以将以下行添加到你的~/.bashrc文件中。

SGML_CATALOG_FILES="/etc/sgml/catalog"
export SGML_CATALOG_FILES

如果你通过 RedHat 或 Debian 包安装了 XML 工具，你可能不需要执行此步骤。如果你正在使用自定义 XML 目录，你肯定需要执行此操作。下一节将介绍更多关于自定义目录的信息。为了确保我的备份脚本获取此自定义文件，我已将我的文件添加到了我的主目录中名为 "docbook" 的子目录中。

bash$ export XML_CATALOG_FILES="/home/user/docbook/db-catalog.xml"

如果你想保存这些更改，你也可以更改你的.bashrc。

XML_CATALOG_FILES="/home/user/docbook/db-catalog.xml"
export XML_CATALOG_FILES

如果你正在将更改添加到你的.bashrc，在你打开一个新的终端窗口之前，你不会看到这些更改。为了使更改在当前终端中立即生效，"source" 该配置文件。

B.3.4. 创建和修改目录

在前一节中，我提到目录就像你工具的指南。具体来说，目录将公共标识符中的规则映射到你系统的文件。

在每个 DocBook 文件（或者实际上每个 XML 文件）的顶部都有一个 DOCTYPE，它告诉处理工具它将要处理的文档类型。至少，此声明将包括一个公共标识符，例如-//OASIS//DTD DocBook V4.2//EN。此公共标识符有许多部分，所有部分都用//分隔。它包含以下信息：ISO 标准（如果有）（--- 在这种情况下，没有 ISO 标准），作者 (OASIS)，文档类型 (DTD DocBook V4.2)，语言（英语）。你的 DOCTYPE 也可能包含一个 URL。

公共标识符对处理工具来说是无用的，因为它需要能够访问实际的 DTD。如果处理工具处于离线状态，则 URL 是无用的。为了帮助你的处理器处理这些问题，你可以下载所有必要的文件，然后使用目录为你的处理工具 "映射" 它们。

如果你正在使用 SGML 处理工具（例如 Jade），你将需要一个 SGML 目录。如果你正在使用 XML 处理工具（例如 XSLT），你将需要一个 XML 目录。这里包含关于两者的信息。

B.3.4.1. SGML 目录

示例 B-2. SGML 目录的示例

                                                           (1)
-- Catalog for the Conectiva Styles -- 

OVERRIDE YES
                                                          (2)
PUBLIC "-//Conectiva SA//DTD DocBook Conectiva variant V1.0//EN" 
			"/home/ldp/styles/books.dtd"

DELEGATE "-//OASIS"
        	"/home/ldp/SGML/dtds/catalog.dtd"
                                                          (3)
DOCTYPE BOOK /home/ldp/SGML/dtds/docbook/db31/docbook.dtd
 
-- EOF --
(1)
注释。注释以 "--" 开头，并持续到行尾。
(2)
公共类型关联"-//Conectiva SA//DTD books V1.0//EN"与文件books.dtd在目录/home/ldp/styles.
(3)
上。表示文件结束的注释。

如上例所示，要将标识符关联到一个文件，只需按照所示的顺序操作

  1. 复制标识符 PUBLIC

  2. 输入标识文本

  3. 指示关联文件的路径

B.3.4.1.1. 用于目录的有用命令

目录中最常用的映射是

PUBLIC

关键字PUBLIC为系统上的标识符映射公共标识符。

SYSTEM

关键字SYSTEM为系统上的文件映射系统标识符。

SYSTEM "http://nexus.conectiva/utilidades/publicacoes/livros.dtd" "publicacoes/livros.dtd"

SGMLDECL

关键字SGMLDECL指定应使用的 SGML 语句的系统标识符。

SGMLDECL "publishings/books.dcl"

DTDDECL

类似于SGMLDECL关键字DTDDECL标识应使用的 SGML 语句。DTDDECL将语句与公共标识符关联到 DTD。不幸的是，开源工具不支持此关联。可以通过多个目录文件以某种方式实现此语句的好处。

DTDDECL "-//Conectiva SA//DTD livros V1.0//EN" "publicacoes/livros.dcl"

CATALOG

关键字CATALOG允许在一个目录中包含另一个目录。这是一种利用多个不同目录而无需更改它们的方法。

OVERRIDE

关键字OVERRIDE通知标识符是否优先于系统标识符。大多数系统上的标准是系统标识符优先于公共标识符。

DELEGATE

关键字DELEGATE允许将目录关联到特定类型的公共标识符。该子句DELEGATE非常类似于CATALOG，除了它在指定特定模式之前什么也不做。

DOCTYPE

如果一个文档以一种文档类型开始，但没有公共标识符，也没有系统标识符，那么子句DOCTYPE将此文档与特定的 DTD 关联起来。

B.3.4.2. XML 目录

以下示例目录由 Martin A. Brown 提供。

示例 B-3. XML 目录文件示例

<?xml version="1.0"?>
<!DOCTYPE catalog PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN"
          "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
    
	<public publicId="-//OASIS//DTD DocBook XML V4.2//EN"
       uri="/home/mabrown/docbook/dtds/4.2/docbookx.dtd"/>
   <uri name="http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
       uri="/home/mabrown/docbook/dtds/4.2/docbookx.dtd"/>
   <uri name="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"
       uri="/home/mabrown/docbook/xsl/xhtml/docbook.xsl"/>
   <uri name="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"
       uri="/home/mabrown/docbook/xsl/xhtml/chunk.xsl"/>
   <uri name="http://docbook.sourceforge.net/release/xsl/current/xhtml/profile-chunk.xsl"
       uri="/home/mabrown/docbook/xsl/xhtml/profile-chunk.xsl"/>
</catalog>

B.3.5. 验证 XML

B.3.5.1. nsgmls

你可以使用 nsgmls，它是 jade 套件的一部分（在 Debian 上，使用 apt-get 安装 docbook-utils 包，请参阅 B.4.2 节），来验证 SGML 或 XML 文档。

bash$ nsgmls -s HOWTO.xml

如果没有问题，你只会得到你的命令提示符。-s-s告诉 nsgmls 只显示错误。

Tip找不到函数
 

如果你收到关于找不到函数的错误，或者关于 ISO 字符没有权威来源的错误，你可能需要将 nsgmls 指向你的xml.dcl文件。对于 Red Hat 9，它看起来像这样：nsgmls -s /usr/share/sgml/xml.dcl HOWTO.xml

有关使用 Jade/OpenJade 处理文件的更多信息，请阅读 使用 OpenJade 处理 DocBook XML/SGML。

B.3.5.2. onsgmls

这是 nsgmls 的替代方案。它随 OpenJade 软件包一起提供。与 nsgmls 相比，此程序提供了更多选项，并且允许您安静地忽略验证 XML 文件（而不是 SGML 文件）时出现的一些问题。这也意味着您不必每次都输入您的xml.dcl文件位置。

我能够简单地使用以下命令来验证文件，只显示与我的标记错误相关的错误消息。

bash$ onsgmls -s HOWTO.xml

根据 Bob Stayton 的说法，您还可以关闭特定的错误消息。以下示例关闭了 XML 特定的错误消息。

bash$ onsgmls -s -wxml -wno-explicit-sgml-decl HOWTO.xml

B.3.5.3. xmllint

您还可以使用来自 libxml2 软件包的 xmllint 命令行工具来验证您的文档。 此工具对标签的完整性以及所有打开的标签是否也已再次关闭进行简单检查。 默认情况下，xmllint 将输出结果树。 因此，如果您的文档一直输出到最后一行，则说明没有与标签不匹配、打开和关闭错误等相关的严重错误。

要防止将整个文档打印到您的屏幕上，请添加--noout参数。

bash$ xmllint --noout HOWTO.xml

如果未返回任何内容，则表示您的文档不包含语法错误。 否则，请从报告的第一个错误开始。 修复该错误，然后再次在您的文档上运行该工具。 如果它仍然返回输出，请再次修复您看到的第一个错误，不要理会其余的错误，因为进一步的错误通常是由第一个错误引起的。

如果您想检查文档中是否存在特定于您的文档类型定义的任何错误，请添加--valid. 

bash$ xmllint --noout --valid HOWTO.xml

xmllint 工具也可用于检查 XML 目录中的错误，请参阅手册页以获取有关如何设置此行为的更多信息。

如果您是 Mac OSX 或 Windows 用户，您可能还想查看 tkxmllint，它是 xmllint 的 GUI 版本。 更多信息可从以下网址获得：http://tclxml.sourceforge.net/tkxmllint.html。

示例 B-4。 使用 xmllint 的调试示例

以下示例展示了如何使用 xmllint 检查您的文档。 我创建了一些我经常犯的错误，作为一名 XML 初学者。 起初，文档无法通过，并且显示错误

bash$ xmllint ldp-history.xml
ldp-history.xml:22: error: Opening and ending tag mismatch: articlinfo line 6 and articleinfo
</articleinfo>
              ^
ldp-history.xml:37: error: Opening and ending tag mismatch: listitem line 36 and orderedlist
</orderedlist>
              ^
ldp-history.xml:39: error: Opening and ending tag mismatch: orderedlist line 34 and sect2
</sect2>
        ^
ldp-history.xml:46: error: Opening and ending tag mismatch: sect1 line 41 and para
for many authors to contribute their part in their area of specialization.</para
                                                                               ^
ldp-history.xml:57: error: Opening and ending tag mismatch: para line 55 and sect1
</sect1>
        ^
ldp-history.xml:59: error: Opening and ending tag mismatch: sect2 line 31 and article
</article>
          ^
ldp-history.xml:61: error: Premature end of data in tag sect1 line 24
 
^
ldp-history.xml:61: error: Premature end of data in tag article line 5
 
^

现在，正如我们已经提到的，除了第一个错误之外，不要担心任何事情。 第一个错误说的是文件第 6 行和第 22 行的标签之间存在不一致。 实际上，在第 6 行，我们省略了 "articleinfo" 中的 "e"。 修复错误，然后再次运行 xmllint。 现在第一个投诉是关于第 37 行，其中列表项的结束标记已被遗忘。 修复错误并再次运行验证工具，直到所有错误消失。 最常见的错误包括忘记打开或关闭段落标签，标签中的拼写错误和混乱的部分。

B.4。 转换

WarningTLDP 将转换您的文档
 

本节介绍如何将文档从 DocBook 转换为其他格式。 如果您不需要转换文档以用于您自己的网站，或者校对内容，请跳过本节。

如果您想转换文档以进行校对，请使用 XML to HTML 在线转换器。 您需要将您的 XML 文件上传到网站。 然后只需将 URL 放入表单中，然后单击提交按钮。 您的文档将神奇地转换为漂亮的（且可读的）HTML 文档。 支持外部文件。 您可以使用绝对或相对 URI。

另一个易于使用的软件包是 xmlto。 它是 xsltproc 的前端。 它可以作为 RedHat、Debian（等）软件包提供，也可以从 http://cyberelk.net/tim/xmlto/ 下载。 您可以使用它来转换文档，方法如下：

bash$ xmlto html mydoc.xml
bash$ xmlto txt mydoc.xml

在提交给 LDP 之前，您永远不需要转换文档。 LDP 志愿者有一个系统，可以将您的 DocBook 文件转换为 HTML、PDF 和纯文本格式。 在这里，您已经得到了警告。

还在这里？ 太好了！ 转换是将您编写的内容从混乱的标签汤转换为可读内容的基本要求。 本节将帮助您设置系统并准备好将您的最新文档转换为其他格式。 如果您想在将文档发布到世界之前查看它，这将非常有用。

目前有两种转换文档的方法：文档样式语义和规范语言 (DSSSL)；以及 XML 样式表 (XSLT)。 尽管 LDP 网站使用 DSSSL 来转换文档，但如果您愿意，可以使用 XSLT。 您只需要选择其中一个方法。 有关 DSSSL 的更多信息，请阅读：第 B.4.1 节，有关 XSLT 的更多信息，请阅读：第 B.4.3 节。

B.4.1. DSSSL

使用 DSSSL 转换文档有三个基本要求

  • 文档样式和语义规范语言文件（这些是纯文本文件）。 第 B.4.1.1 节

  • 与文档的 DOCTYPE 匹配的文档类型定义文件（这是一个纯文本文件）。 第 B.5 节

  • 用于执行实际工作的处理器。 第 B.4.1.2 节

B.4.1.1。 样式表

LDP 使用两种版本的文档样式语义和规范语言，将文档从原始 DocBook 文件转换为其他格式（然后在 Web 上发布）。 LDP 版本的样式表需要 Norman Walsh 版本 - 这基本上意味着如果您使用的是 DSSSL，则 Norman Walsh 版本可以被认为是系统设置的要求。

Norman Walsh DSSSL http://docbook.sourceforge.net/projects/dsssl/。 文档样式语义和规范语言告诉 Jade（参见 第 B.4.1.2 节）如何将 DocBook 文档呈现为打印形式或在线形式。 DSSSL 将title标签转换为 <h1> HTML 标签，或转换为 14 磅粗体 Times Roman（对于 RTF），例如。 DSSSL 的文档位于同一站点。 请注意，修改 DSSSL 不会修改 DocBook 本身。 它只是改变了渲染文本的外观。 LDP 使用修改后的 DSSSL（见下文）。

LDP DSSSL http://www.tldp.org/authors/tools/ldp.dsl。 LDP DSSSL 需要 Norman Walsh 版本（见上文），但它是一个稍微修改过的 DSSSL，用于提供目录之类的东西。

示例 B-5。 "安装" DSSSL 样式表

创建一个基本目录来存储所有内容，例如/usr/share/sgml/。 将 DSSSL 样式表复制到一个名为dsssl.

B.4.1.2。 DSSSL 处理器

有两个版本的 Jade 处理器：James Clark 的原始版本； 以及大约相同程序的开源版本 OpenJade。 您只需要其中一个程序。 它应该在 DTD 和 DSSSL "安装"后安装。

DSSSL 转换工具

Jade

ftp://ftp.jclark.com/pub/jade/

目前，该软件包的最新版本是jade-1.2.1.tar.gz.

Jade 是 SGML 和 XML 的前端处理器。 它使用 DSSSL 和 DocBook DTD 来执行 SGML 和 XML 的验证和渲染到目标格式。

OpenJade

http://openjade.sourceforge.net/

由 DSSSL 社区编写的 Jade 的扩展。 某些应用程序需要 jade，但正在更新以支持这两种软件包。

B.4.1.3。 DSSSL 转换的系统设置

  1. 告诉您的系统在哪里可以找到 SGML_CATALOG_FILES（是的，即使您使用的是 XML）。 您可以在 示例 B-1 中找到有关如何执行此操作的示例。

  2. 下载 DSSSL 和 DTD 文件并将它们复制到您的工作目录中。 您可以在 示例 B-5 和 示例 B-7 中找到有关如何执行此操作的示例。

B.4.1.4。 使用 DSSSL 进行转换

配置好系统后（请参阅上一节），您应该能够开始使用 jade 将文件从 XML 转换为 XHTML。

要创建单个 HTML 文件，请将 jade 指向正确的 DSL（样式表）。 以下示例使用 LDP 样式表。

bash$ jade -t xml -i html \
	-d /usr/local/sgml/dsssl/docbook/html/ldp.dsl#html \
	HOWTO.xml

如果您想生成单个 HTML 页面，请添加-V nochunks参数。 您可以通过在命令后附加 > output.html. 

bash$ jade -t xml -i html -V nochunks \
	-d /usr/local/sgml/dsssl/stylesheets/ldp.dsl#html \
	HOWTO.sgml > output.html

Note来指定最终 HTML 文件的名称。
 

不是函数名错误xml.dcl如果您收到关于 "不是函数名" 的错误，则需要添加一个指向的指针。 它必须紧挨着您的 XML 文档的指针之前列出。 尝试以下位置之一/usr/lib/sgml/declaration/xml.dcl，或者/usr/share/sgml/declaration/xml.dcl

bash$ jade -t xml -i html \
	-d /usr/local/sgml/dsssl/docbook/html/ldp.dsl#html \
	/usr/lib/sgml/declaration/xml.dcl HOWTO.xml

如果您想创建适合打印的文件而不是 HTML 文件，只需更改您使用的样式表。 在上面的文件名中，请注意结尾处的 "html/ldp.dsl"。 将其更改为 "print/docbook.dsl"，或者如果您想要 XHTML 输出而不是 HTML，请将文件名更改为 "xhtml/docbook.dsl"。

B.4.1.4.1。 更改 CSS 文件

如果您希望您的 HTML 文件使用特定的 CSS 样式表，您将需要编辑ldp.dsl。 紧随其后;; End of $verbatim-display$ redefinition添加以下行

(define %stylesheet-type%
  ;; The type of the stylesheet to use
  "text/css")

(define %stylesheet%
  ;; Name of the css stylesheet to use, use value #f if you don't want to
  ;; use css stylesheets
  "base.css")

替换base.css为您要使用的 CSS 文件的名称。

B.4.2。 docbook-utils 软件包

docbook-utils 提供诸如 db2html、db2pdf 和 db2ps 等命令，这些命令基于 jw 脚本，而 jw 脚本是 Jade 的前端。 这些工具简化了日常文档管理，并增加了舒适的功能。

该软件包最初由 RedHat 创建，可从 http://sources.redhat.com/docbook-tools/ 获取，并且可以在大多数系统上安装。

示例 B-6。创建 HTML 输出的示例

验证文档后，只需执行命令 db2html mydoc.xml 即可创建 HTML 文件。您也可以使用 docbook-utils 作为验证工具。请记住：发生错误时，始终从解决第一个问题开始。解决第一个错误后，其余问题可能会得到修复。

如果您收到有关函数名称的错误，请阅读 .

B.4.2.1。使用 CSS 和 DSL 获得漂亮的输出

您可以定义自己的其他 DSL 指令，其中可以包含指向个性化 CSS 文件的指针。 示例 DSL 和 CSS 文件在附录 A中提供。

示例 DSL 文件将创建一个目录表，并使所有 HTML 文件都以以下前缀开头intro2linux-并以以下后缀结尾.html. The%stylesheet%变量指向您的 HTML 文件应调用的 CSS 文件。

要使用特定的 DSL 样式表，应使用以下命令

db2html-d mystyle.dsl mydoc.xml

您可以在此处比较结果：http://tille.xalasys.com/training/unix/ 是一本使用标准工具格式化的书；http://tille.xalasys.com/training/tldp/ 是使用个性化的 DSL 和 CSS 文件的一本书。 例如，按钮中使用了柔和的色调和特殊效果，以达到最佳效果。

B.4.3。XSL

DSSSL 和 Jade/OpenJade 还有其他替代方案。

使用 DocBook XML 时，LDP 提供了一系列 XSL[2] 样式表，用于将文档处理为 HTML。这些样式表使用 XML 工具集创建输出文件，这些文件与使用 ldp.dsl 的 SGML 工具生成的文件相似。

使用ldp.dsl和 XSL 样式表之间的主要区别在于处理多个文件的生成方式，例如为每个章节、部分和附录创建单独的文件。使用 SGML 工具（例如 jade 或 openjade），该工具本身负责生成单独的文件。 因此，只有一个文件，ldp.dsl是标准 DocBook DSSSL 样式表的自定义层所必需的。

使用 DocBook XSL 样式表，由样式表控制多个文件的生成。 如果要生成单个文件，则调用一个样式表。 如果要生成多个文件，则调用另一个样式表。 因此，LDP XSL 样式表分发包含四个文件

  1. tldp-html.xsl- 调用样式表以生成单个文件。

  2. tldp-html-chunk.xsl[3] - 调用样式表以基于章节、部分和附录元素生成多个文件。

  3. tldp-html-common.xsl- 包含实际 XSLT 转换的样式表。它被其他两个 HTML 样式表调用，从不直接调用。

  4. tldp-print.xsl- 用于生成 XSL 格式化对象以进行打印输出的样式表。

您可以在 http://my.core.com/~dhorton/docbook/tldp-xsl/ 找到这些文件的最新副本。 该软件包包含安装说明，这些说明在 http://my.core.com/~dhorton/docbook/tldp-xsl/doc/tldp-xsl-howto.html 中重复。 安装说明的简短版本如下：从网站下载并解压缩最新软件包。 从htmlTLDP-XSL 的目录并将它们放在htmlNorman Walsh 样式表的目录中。从 TLDP-XSL 中获取文件fo目录并将其放入 Norman Walshfo目录中。

安装完这些文件后，您可以使用 xsltproc 从 XML 文档生成 HTML 文件。 要将 XML 文件转换为单页 HTML 文档，请使用以下命令

bash$  xsltproc -o HOWTO.html /usr/local/sgml/stylesheets/tldp-html.xsl HOWTO.xml

要生成一组链接的 HTML 页面，每个页面都对应一个章节, sect1或附录，请使用以下命令

bash$ xsltproc /usr/share/sgml/stylesheets/tldp-html-chunk.xsl HOWTO.xml

请注意，您永远不会直接调用样式表tldp-html-common.xsl。 它被其他两个样式表调用。

B.4.3.1。更改 CSS 文件

如果您希望您的 HTML 文件使用特定的 CSS 样式表，您将需要编辑tldp-html-common.xsl。 查找类似于以下的行<xsl:param name="html.stylesheet" select="'style.css'"/>.

替换style.css为您要使用的 CSS 文件的名称。

B.5。DocBook DTD

DocBook DTD 定义了 DocBook 文档的结构。 它包含有关如何使用元素以及元素应该描述什么的规则。 例如：DocBook DTD 指出所有警告用于警告读者（这是元素的定义）； 并且可能不包含纯文本（这是内容模型——并且强制您将警告文本包装在para或者列表中的位）。

Caution版本
 

重要的是，您要下载与您的文档匹配的版本。 如果您要编辑较旧的 LDP 文档，您可能希望立即配置您的系统以处理“所有” DocBook DTD。 如果您是新作者，则只需要列出的第一个：DocBook 版本 4.2 的 XML DTD。

XML DTD 可从 http://www.oasis-open.org/xml/4.2/ 获得。 LDP 首选此版本的 DocBook DTD。

如果您要使用 SGML 版本的 DocBook，则需要以下其中一个（或两个）：http://www.oasis-open.org/docbook/sgml/4.1/docbk41.zip 或 http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip

示例 B-7。“安装” DocBook 文档类型定义

创建一个基本目录来存储所有内容，例如/opt/local/sgml/。 将 DTD 复制到名为dtd.

Warning的子目录中
 

请勿编辑 DTD 文件

DocBook 标准在这些文件中进行了描述。 如果您更改这些文件，则您不再使用 DocBook。

B.6。格式化文档

B.6.1。在初始文章页面上插入摘要

在某些情况下可能很有价值的一项功能是在文章的初始页面上插入摘要。 DocBook 文章未将其作为标准功能包含在内。

要启用此功能，必须修改样式表文件。

<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!entity html-docbook PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA DSSSL>
<!entity print-docbook PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA DSSSL>
]>

<style-sheet>
<style-specification use="html">
<style-specification-body>

; Includes a summary at the beginning of an item. 
(define %generate-article-toc% #t)

</style-specification-body>
</style-specification>
<style-specification use="print">
<style-specification-body>

; Includes a summary at the beginning of an item.    
(define %generate-article-toc% #t)

</style-specification-body>
</style-specification>
<external-specification id="html" document="html-docbook">
<external-specification id="print" document="print-docbook">
</style-sheet>

示例 B-8。用于在文章中插入摘要的样式表

B.6.2。自动插入索引

  1. 尽管 DocBook 具有用于编写索引的标记，但索引不会自动生成。 collateindex.pl 命令允许从源 DocBook 生成索引，以便包含在完成/转换后的文档中。使用选项.

    bash$ jade -t sgml \
	-d html/docbook.dsl -V html-index document.sgml

  2. -V html-index使用样式HTML通过jade处理文档。使用 collateindex.pl 生成

    bash$  perl collateindex.pl \
	-o index.sgml HTML.index

index.sgml使用样式HTML通过jade处理文档。.

文件。

<!DOCTYPE article PUBLIC "-//OASIS//DTD
DocBook V3.1//EN" [

<!-- Insertion of the index --> <!entity index SYSTEM
"index.sgml"> ]>

为了使以上示例起作用，有必要通过调用文件来定义外部实体

Note示例 B-9。配置外部实体以包含索引
 

另请参阅 第 D.4 节，以获取有关如何在文本中插入必要信息的信息。

为打印版本生成索引的奇怪行为

LDP 为其作者提供可选的 CVS 访问权限。这可以实现协作写作，并具有以下积极影响：

  1. CVS 会保留您文档的异地备份。如果您将文档交给另一位作者，他们只需从 CVS 中检索文档并继续。如果您需要返回到文档的先前版本，您也可以检索它。

  2. 从组织的角度来看，让多个人员同时处理同一文档是一件很棒的事情。CVS 使您能够做到这一点。您可以让 CVS 告诉您在您编辑副本时其他作者所做的更改，并将这些更改集成起来。

  3. CVS 会保存所做更改的日志。这些日志（和一个时间戳）可以在发布文档时自动放置在您的文档中。

  4. CVS 可以与脚本结合使用，以在编写和提交新文档时自动更新 LDP 网站。这尚未到位，但这是一个目标。目前，CVS 更新会通知 HOWTO 协调员更新 LDP 网页，这意味着如果您使用 CVS，则无需通过电子邮件发送您的 XML 代码。（尽管当您准备好发布文档时，您仍然需要向提交列表发送电子邮件，因为整个发布过程尚未完全自动化。）

Note访问我们的 CVS 存储库
 

只有提交了至少三个文档的作者才能访问我们的 CVS，请参阅 附录 C。

请记住，如果您尝试在 PS 或 PDF 输出上获取目录或索引，则需要至少运行三次 jadetex 或 pdfjadetex。 TeX 需要这样做，但 DocBook 或相关应用程序不需要。

附录 C.并发版本系统 (CVS)

Caution您可以通过网络在 http://cvs.tldp.org/ 浏览 LDP CVS 存储库。
 

C.1。获取 CVS 帐户

  • 不会向所有申请人授予 CVS 帐户

  • 要获得 CVS 帐户，您必须符合以下类别之一

  • 文档已在集合中的作者，他们通过

对 LDP 进行了至少三次提交

由其中一位审核协调员批准的技术和语言审核员

审核过程中的新作者（还需要其中一位审核协调员的批准）

如果您不符合条件，请勿申请 CVS 帐户。

如果您有资格获得 CVS 帐户，您可以联系 CVS master Sergiusz mailto:ser@gnu.org 申请一个帐户。 包括有关您维护的文档的信息。

C.2。使用 CVSC.2.1。设置您的 CVS 帐户首先，您需要在 LDP 的 CVS 存储库中获取一个帐户。 请参阅以上有关获取帐户的说明。 此存储库包含各种文档，包括 HOWTO 和指南。 文档按文档类型（例如 HOWTO 或指南）以及文档使用的标记语言（例如 DocBook 或 LinuxDoc）进行排序。

帐户准备就绪后，您可以使用以下命令之一登录。 在所有情况下

your_userid

应替换为您在回复电子邮件中收到的用户名。 在第一步之后，系统将提示您输入密码。初始化您的 CVS 帐户C.2.1。设置您的 CVS 帐户Linux 系统cvs

-d :pserver

@cvs.tldp.org:/cvsroot登录Windows 系统C.2.1。设置您的 CVS 帐户设置

应替换为您在回复电子邮件中收到的用户名。 在第一步之后，系统将提示您输入密码。CVSROOTcvs

请耐心等待系统尝试登录。系统通常需要 10-20 秒或更长时间才能接受（或拒绝）您的密码。首次使用 cvs login 并被授予系统访问权限后，您的密码将存储在.cvspass中，以后您就不需要再次使用 cvs login 了。只需使用上面列出的 export 命令设置 CVSROOT，然后继续。如果 TLDP 的 CVS 服务器是您唯一使用的服务器，您也可以将 export CVSROOT 行添加到您的~/.bashrcshell 配置文件中。

C.2.2. 获取文档

您可以使用以下命令获取整个存储库（大约 150 MB）：cvs checkout LDP

或者，您可以使用以下命令获取您自己的文档的源文件：cvs checkout LDP/howto/docbook/YOUR-HOWTO.xml 或 cvs checkout LDP/guide/docbook/YOURGUIDE

Windows 用户需要使用此命令的修改版本。他们应该使用：cvs -d %CVSROOT% checkout LDP/howto/docbook/YOUR-HOWTO.xml

Note保持概览
 

checkout 命令将从 tldp.org 开始添加完整的目录结构。虽然将这些文件放在本地文件系统的什么位置并不重要，但您可能不希望将目录埋得太深。

C.2.3. CVS 命令

CVS 命令：简要提醒

commit

此 CVS 命令会将您的更改上传到 CVS 服务器。

请务必包含对您文档所做更改的有用描述。

如果您想绕过编辑器屏幕，可以使用

应替换为您在回复电子邮件中收到的用户名。 在第一步之后，系统将提示您输入密码。commit -m "对文档的此版本所做工作的描述。"

Note准备发布警告
 

当您准备好让您的更改显示在实际网站上时，您仍然需要发送电子邮件到。您的电子邮件应包含您希望更新的 LDP CVS 树中文件的相对路径。

add

您可以将新文件添加到您的 CVS 存储库。这些文件可能是图像文件或其他 XML 文件。首先，检查您的 HOWTO 是否位于其自己的目录中。您可能需要与以下人员协调以确保您可以将图形或其他文件添加到您的 HOWTO。

将要添加的文件复制到您的本地 CVS 存储库（所有已下载/正在工作的文件都在该存储库中）。然后

cvs add文件名

添加文件后，您仍然需要将它们 commit 到存储库（参见上文）。

remove

$Id: cvs.xml,v 1.32 2011/01/14 16:24:52 serek Exp $

虽然这不是 CVS 的 "命令"，但它可以用来自动插入有关文件的信息，包括上次修改的时间和日期、CVS 分配的版本号以及此特定文件的文件名。输出结果将如下所示$Id: cvs.xml,v 1.9 2002/04/21 09:44:26 serek Exp $

如果您需要更改文件名，您仍然需要使用 add 命令。首先，从您的本地磁盘中删除文件的副本。然后使用以下命令从 CVS 树中删除它：cvs remove filename。与 add 命令一样，您需要 >commit 您删除的文件。最后，现在旧文件已被删除，请使用上面的说明添加您的新文件（首先 add，然后 commit 附加文件）。

C.2.3.1. 恢复旧版本

您正在打字，突然搞砸了。非常糟糕。不管是什么，但足以说明您不仅破坏了本地驱动器上的版本，还在 CVS 服务器上创建了一个新版本。您需要做的是回到过去并复活您的文件的旧版本。

为此，您需要知道要检索的文件的版本号。cvs diff 如果有差异，将给出一个修订列表。您可以选择修订号，减去 1，这可能就是您想要查看的修订。

命令

cvs -Q update -p -r修订版 文件名

将输出到 stdout 的内容修订版的版本文件名。您可以将其管道传输到 more 或将输出重定向到文件。方便的是，您可以将 stdout 重定向到一个名为文件名的文件。您的本地文件现在是您想要的修订版，并且

cvs update

将使用新的（旧的）版本更新 CVS 服务器文件名.

C.3. CVS 资源

如果您完全不熟悉 CVS，您可以查看一些网页，这些网页可以帮助您

附录 D. DocBook：示例标记

D.1. 一般提示和技巧

有关标记的一般概述，请阅读 第 5 章

  • 能够根据 DTD 插入元素的编辑器将有很大帮助，因为它将强制执行 DTD。这样，您就可以确保您的文档中的任何位置都没有添加无效元素。

  • 为了确保将来的更改尽可能容易，作者应尽量保持与 DocBook DTD 的 XML 版本的兼容性。这意味着将元素名称保持为小写，在所有属性中使用双引号，并且不省略结束标记。大多数自动插入元素的工具（如 psgml+emacs）会自动或通过一些微调来遵循这些规则。

  • 创建的每种类型的文档都有特定的结构。本文档采用 "book" 格式。但是，大多数作者都希望使用更短的 "article" 格式。模板可从 附录 A 中获得。

D.1.1. 有用的标记

表 D-1 显示了一些可用于生成通用文档的标记。请记住，某些元素仅在某些上下文中有效。

Tip检查多种格式
 

有时，特定标记的外观会因一种转换格式而异。作为 DocBook 写作的初学者，您可能希望在发布文档之前查看文档在多种格式下的外观。建议您查看文档在 HTML、PDF 和 PostScript 中的呈现方式，因为一旦您发布文档，TLDP 将提供这些格式。

Note宁多勿少
 

由于格式取决于所选的输出样式，因此建议尽可能多地使用标记。即使输出的外观在使用标准输出样式时似乎没有改变，也可能有特定的输出格式会使这些标记脱颖而出。

表 D-1. 有用的标记

描述示例标记结果
电子邮件地址<email>address@domain</email>
关于作者<author>...</author>（请参见下面的示例）
作者姓名
<firstname>Mary</firstname>
<othername>Margaret</othername>
<surname>O'Hara</surname>
Mary Margaret O'Hara
键名（键盘上的打印）<keycap>F1</keycap>F1
键表示的符号<keysym>KEY_F1</keysym>KEY_F1
键的代码<keycode>0x3B</keycode>0x3B
键的组合或序列
<keycombo>
   <keycap>Ctrl</keycap>
   <keycap>S</keycap>
</keycombo>
Ctrl-S
程序菜单<guimenu>文件</guimenu>文件
菜单项<guimenuitem>保存</guimenuitem>保存
菜单序列
<menuchoice>
   <shortcut>
      <keycombo>
         <keycap>Ctrl</keycap>
         <keycap>S</keycap>
      </keycombo>
   </shortcut>
   <guimenu>File</guimenu>
   <guimenuitem>Save</guimenuitem>
</menuchoice>
文件->保存 (Ctrl-S)
鼠标按钮<mousebutton>左</mousebutton>左
应用程序名称<application>application</application>application
文本书目参考<citation>reference</citation>[reference]
引用
<blockquote>
   <attribution>Text Author</attribution>
   <para>Quote Text.</para>
</blockquote>

 

引用文本。

 
--文本作者 

索引(NA)请参见 第 D.4 节。
文件名
<filename>file</filename>
文件
目录
<filename id="directory">directory</filename>
directory/
强调文本[a]
<emphasis>text</emphasis>
text
脚注
<footnote>
   <para>Footnote text</para>
</footnote>
（有关示例，请参见此表末尾的注释）
URL
<ulink url="http://www.conectiva.com">Conectiva S.A.</>
Conectiva S.A.
项目（无编号）列表
<itemizedlist>
   <listitem>
      <para>item</para>
   </listitem>
   <listitem>
      <para>item</para>
   </listitem>
</itemizedlist>

  • 项目

  • 项目

有序（编号）列表
<orderedlist>
   <listitem>
      <para>item</para>
   </listitem>
   <listitem>
      <para>item</para>
   </listitem>
</orderedlist>

  1. 项目

  2. 项目

分段列表
<segmentedlist>
   <title>Binary to decimal conversion</title>
   <segtitle>Binary</segtitle>
   <segtitle>Decimal</segtitle>
   </seglistitem><seg>00</seg><seg>0</seg>
   </seglistitem>
   <seglistitem><seg>01</seg><seg>1</seg>
   </seglistitem>
   <seglistitem><seg>10</seg><seg>2</seg>
   </seglistitem>
</segmentedlist>

二进制到十进制转换

二进制00

十进制0

二进制01

十进制1

二进制10

十进制2

变量列表
<variablelist>
   <varlistentry>
      <term>Entry 1</term>
      <listitem>
         <para>Description</para>
      </listitem>
   </varlistentry>
   <varlistentry>
      <term>Entry 2</term>
      <listitem>
         <para>Description</para>
      </listitem>
   </varlistentry>
</variablelist>

条目 1

描述

条目 2

描述

简单列表
<simplelist type="horiz" columns="3">
   <member>1</member>
   <member>2</member>
   <member>3</member>
   <member>4</member>
   <member>5</member>
   <member>6</member>
</simplelist>
<simplelist type="inline">
   <member>A</member>
   <member>B</member>
   <member>C</member>
   <member>D</member>
   <member>E</member>
   <member>F</member>
</simplelist>

123
456

A, B, C, D, E, F
图片(NA)请参见 第 D.5 节
术语表
<glossentry>
   <glossterm>Term</glossterm>
   <glossdef>
      <para>Definition</para>
   </glossdef>
</glossentry>
（请参见本文档末尾的词汇表）
交叉引用
<section id="secao">
...
</section>
<section id="reference the other section">
...
<para>Please, see<xref linkend="secao" /> for more information.
(NA)
注释
a. 可以用几种方式强调文本。最常见的方式是斜体和粗体。但是，DocBook 仅支持斜体。使用粗体需要在所使用的样式表上进行其他设置。

D.2.<section>和<sectN>：有什么区别？

Note致谢
 

这些注释由以下人员提供：John Daily 和 Saqib Ali ().

<section>与<sectN>相比，主要是一个灵活性的问题。样式表可以使一个<section>中的<section>看起来就像一个<sect2>，在一个<sect1>中，因此没有输出优势。

但是，一个<section>，在一个<section>可以提取到其自己的顶级部分，甚至更深地嵌套，或者移动到文档的完全不同的部分，而无需重命名它及其自己的<section>子级。对于编号部分标签来说，情况并非如此，它们对重新排列非常敏感。对于不熟悉 DocBook 的作者来说，这可能比使用<sectN>.

更容易。创建结构化数据背后的主要思想是应该易于访问和查询。应该能够使用 XML 的查询语言 (XPath 和 XQuery) 来检索任何结构化数据的子部分。<sectN>在使用 XPath/XQuery 遍历文档时很有用。<sectN>在编写 XPath 表达式时，提供更大的灵活性和控制。

一个定义良好、有效且结构良好的文档使人们更容易编写 XPath/Query 以从文档中检索 "特定" 数据。例如，您可以使用 XPath 来检索<sect3>块中具有某些属性的信息。但是，如果您只使用<section>作为所有子部分的标签，那么检索您需要的信息块会变得更加困难。

那么您应该使用哪一个呢？您觉得最舒服的一个是一个好的起点。本文档是用<section>编写的。您可能认为或不认为这是一个好主意。:)

D.3. 命令提示符

可能有很多方法可以做到这一点，就像 DocBook 作者一样多；但是，这里有两种您可能会觉得有用的方法。感谢 Y Giridhar Appaji Nag 和 Martin Brown 在这里使用的标记。

示例 D-1. 使用programlisting

<programlisting>
	<prompt># </prompt><userinput><command>cd</command> /some/dir</userinput>
	<prompt># </prompt><userinput><command>ls</command> -l</userinput>
</programlisting>

的命令提示符显示为

# cd /some/dir
# ls -l

示例 D-2. 使用screen

的命令提示符首先在文档的开头创建内部子集中的一个通用实体。此实体将定义一个快捷方式的名称，您可以使用该快捷方式在文档中的任何位置显示完整提示。<!ENTITY prompt "<prompt>[user@machine ~/dir]$</prompt>">

关于实体的更多信息，请阅读第D.8节。

<screen>
&prompt; <userinput>cd /some/dir</userinput>
&prompt; <userinput>ls -l</userinput> </screen>

的命令提示符显示为

 
[user@machine ~/dir]$ cd /some/dir 
[user@machine ~/dir]$ ls -l

如果你想添加命令的输出，你可以添加<computeroutput>text</computeroutput>在<screen>或<programlisting>中，根据需要添加。

D.4. 编码索引

索引的生成取决于插入到文本中的标记。

这些标记将稍后由外部工具处理，并生成索引。 这样的工具的一个例子是collateindex.pl脚本（参见第B.6.2节）。 关于生成这些索引的过程的详细信息显示在第B.6.2节中。

索引具有嵌套级别。 索引的标记由代码示例D-3完成。

示例D-3。 用于生成索引的代码

<indexterm>
   <primary>Main level</primary>
   <secondary>Second level</secondary> 
	<tertiary>Third level</tertiary>
	</indexterm>

可以使用属性引用文档的章节、段落和其他部分zone.

示例D-4。 属性的使用zone

<section id="encoding-index">
<title>Encoding Indexes</title>
<indexterm zone="encoding-index">
<primary>edition</primary> <secondary>index</secondary>
</indexterm>

<para>
	The generation of indexes depend on the inserted markups on the text.
</para>

示例D-4包含用于在索引中生成此版本条目的代码。 事实上，由于使用了属性zone，索引语句可以位于文档中的任何位置，甚至可以位于单独的文件中。

但是，为了方便维护，索引的条目都放在它所引用的文本之后。

示例D-5。 值的用法startofrange和endofrange在属性上class

    <para>Typing the text normally
    sometimes there's the need of
   <indexterm class="startofrange"
   id="example-band-index">
      <primary>examples</primary> <secondary>index</secondary>
   </indexterm> mark large amounts of
   text.</para>

   <para>Keep inserting the paragraphs
   normally.</para>

   <para>Until the end of the section
   intended to be indexed.  <indexterm
   startref="example-band-index" class="endofrange">.
   </para>

D.5. 插入图片

必须为所有可能的完成文档类型插入图片格式。 例如：用于网页的JPG文件和用于PostScript和PDF文件的EPS。

如果你使用TeX格式，你将需要PostScript文件格式的图像。 对于在线发布，你可以使用任何常见的图像文件，例如JPG、GIF或PNG。

插入图片的最简单方法是使用fileref属性。 通常，图片以JPG和PostScript（PS或EPS）格式生成。

示例D-6。 插入图片

<figure>
   <title>Picture's
   Title</title> <graphic fileref="images/file"></graphic>
</figure>

替换<figure>为<informalfigure>消除了插入图片标题的需要。

仍然有float属性，其值为0指示图片应放置在标签出现的确切位置。 价值1允许将图片移动到更方便的位置（此位置可以在样式表中描述，也可以由应用程序控制）。

D.5.1. 图形格式

向LDP提交图形时，请提交一组图形，格式为.eps， 另一组为.gif, .jpg或.png。 首选格式是.png或.jpg，因为存在专利问题.gif.

你可以使用.jpg文件用于连续色调图像，例如照片或颜色逐渐变化的图像。 使用.png用于简单的图像，如图表、一些屏幕截图和颜色数量少的图像。

D.5.2. 替代方法

示例D-6的第一个替代方案是消除<figure>或<informalfigure>元素。

当你决定在不接受图片的媒体上发布文本时，另一个有趣的替代方案是使用包装器，<imageobject>.

示例D-7。 使用<imageobject>

<figure>
   <title>Title</title> 
   <mediaobject>
      <imageobject>
	 <imagedata fileref="images/file.eps" format="EPS">
      </imageobject> 
   <imageobject>
	 <imagedata fileref="images/file.jpg" format="JPG">
      </imageobject> 
      <textobject>
	 <phrase>Here there's an image of this example</phrase>
      </textobject> 
   <caption>
   <para>Image Description. Optional. </para>
   </caption>
   </mediaobject>
</figure>

使用以下格式的文件可用：BMP、CGM-BINARY、CGM-CHAR、CGM-CLEAR、DITROFF、DVI、EPS、EQN、FAX、GIF、GIF87A、GIF89A、IGES、JPEG、JPG、LINESPECIFIC、PCX、PIC、PS、SGML、TBL、TEX、TIFF、WMF、WPG。

此方法具有一个优点：更好地控制应用程序。 元素<imageobject>会被连续测试，直到其中一个被接受。 如果输出格式不支持图像，则<textobject>元素将被使用。 但是，使用格式示例D-7的最大优势是，在DocBook中5.0，<graphic>元素将不再存在。

缺点是，需要同一信息的多个表示代码。 由作者决定如何在文档中实现插图和图片，但为了与未来版本兼容，我建议使用此方法来处理图片和图形。

Warning标题页例外
 

<mediaobject>如果它们用在标题页上，则不会显示。 欲了解更多信息，请阅读： http://www.sagehill.net/docbookxsl/HtmlCustomEx.html#HTMLTitlePage

NoteASCII图像
 

你也可以尝试将你的图像转换为文件的ASCII表示形式。 JavE (Java ASCII Versatile Editor)可以为你做这个转换。 它可以从 http://www.jave.de/ 下载。 它有一个易于使用的GUI界面。

如果你更喜欢命令行，你可能想尝试： tgif (http://bourbon.usc.edu:8001/tgif/) 和 AA-Lib (http://aa-project.sourceforge.net/)。

D.6. 元数据的标记

D.6.1. 感谢翻译者、转换者和共同作者

有几种方法可以让你给这些人以及你的文档的其他贡献者一些认可，感谢他们给你的帮助。

D.6.1.1.<othercredit>

所有翻译者、转换者和共同作者都应该使用<othercredit>标签条目来表示感谢。 为了正确地感谢翻译者或转换者，使用<othercredit>标签，并设置role属性设置为 "converter" 或 "translator"，如下例所示

示例D-8。 其他感谢

<othercredit role='converter'>
  <firstname>David</firstname> 
  <surname>Merrill</surname> 
  <contrib>Conversion from HTML to DocBook v3.1 (SGML).</contrib>
</othercredit>

D.6.1.2. 感谢编辑和审阅者

为了帮助跟踪审查过程，所有新文档都必须包含对 技术、语言 和 元数据 审查的审阅者的引用。

示例D-9。 编辑

<editor>
  <firstname>Tabatha</firstname> 
  <surname>Marshall</surname> 
  <contrib>Language review of version 0.8</contrib>
</editor>

D.6.2.<revremark>s

在<revision>标签层次结构中有一个名为<revremark>的标签。 在此标签中，你可以对文档的每个特定修订版本进行任何简短的说明。

D.6.3. 修订历史

关键字<revhistory>标签应用于表示文档的各种修订版本。 指定日期、修订号以及有关更改内容的注释。

修订版本应列出最新版本在顶部（按降序排列）。

D.6.4. 日期格式

关键字<pubdate>标题中的标签应列出此特定版本的文档的发布日期（与修订日期一致）。 它应该是以下格式

<pubdate>2002-04-25</pubdate>

日期格式为YYYY-MM-DD，这是表示日期的 ISO 8601 标准格式之一。 对于你们这些美国佬（我也是），可以把它想象成从最大的时间单位到最小的时间单位。

D.6.5. 示例文章（或书籍）信息元素

这是一个完整的DocBook（SGML或XML）的示例<articleinfo>元素，其中包含一些先前描述的项目和结构。

示例D-10。 示例元数据

<!--
   Above these lines in a typical DocBook article would be the article
   element (the immediate parent of the articleinfo element) and above
   that typically, the DOCTYPE declaration and internal subset.
  -->

<articleinfo>

  <!-- 
  	Use "HOWTO", "mini HOWTO", "FAQ" in title, if appropriate
  --> 
  
<title>Sample HOWTO</title>

<author>   
	<firstname>Your Firstname</firstname>
	<surname>Your Surname</surname>
	<affiliation>
		<address><email>your email</email></address>
		</affiliation>
</author>

<editor>
  <firstname>Tabatha</firstname> 
  <surname>Marshall</surname> 
  <contrib>Language review of version 0.8</contrib>
</editor>

<othercredit role='converter'>
  <firstname>David</firstname> 
  <surname>Merrill</surname> 
  <contrib>Conversion from HTML to DocBook v3.1 (SGML).</contrib>
</othercredit>

   <pubdate>YYYY-MM-DD</pubdate>

	<revhistory>
		<revision>
		<revnumber>1.0</revnumber>
		<date>YYYY-MM-DD</date>
		<authorinitials>ABC</authorinitials>
		</revremark>first official release</revremark>
		</revision>
		
		<revision>
		<revnumber>0.9</revnumber>
		<date>YYYY-MM-DD</date>
		<authorinitials>ABC</authorinitials>
		<revremark>First draft</revremark>
		</revision>
	</revhistory>

   <!-- 
		Provide a good abstract; a couple of sentences is sufficient
   -->

  <abstract>    
		<para>
       This is a sample DocBook (SGML or XML) HOWTO which has been
       constructed to serve as a template.
		</para>
	</abstract>

</articleinfo>

D.7. 参考书目

并非每个人都会选择使用正确的格式来编写参考书目。 大多数人会使用某种列表。 这也没关系。 但是，当你准备好进入下一个级别时，这就是方法。

以下是两个书目条目的示例。 第一个是非常简单的条目。 它只有标题、URL，可能还有简短的描述（摘要）。 第二个稍微复杂一些，适用于具有ISBN、出版商和版权日期的完整条目（例如书籍）。

NoteDocBook对书目参考的要求
 

至少一个元素在<biblioentry>是必需的，但你拥有哪一个并不重要。 所以你可能有一个<title>， 或者一个URL (<bibliosource>)， 或者一个<author>， 或者， ...

有关所有选项的完整列表，请访问 http://docbook.org/tdg/en/html/biblioentry.html。 欲了解更多示例，请访问 http://docbook.org/tdg/en/html/bibliography.html。

Caution显示<abstract>内容
 

默认情况下<abstract>不会在网页上显示。 你需要修改biblio.xsl文件。 搜索单词"abstract"，然后将此信息添加到 <xsl:template> 标签内。 如果这没有意义，请不要太担心，但请注意，需要显示摘要。

<div xmlns="http://www.w3.org/1999/xhtml" class="{name(.)}">
    <xsl:apply-templates mode="bibliography.mode"/>
</div>

示例D-11。 参考书目

<bibliography>
<title>Bibliography title</title>

<bibliodiv>
<title>Section title</title>
<biblioentry>
<title>Book or Web Site Title</title>
<bibliosource><ulink url=""/></bibliosource>
<abstract></abstract>
</biblioentry>

<biblioentry>
<title></title>
<bibliosource><ulink url=""/></bibliosource>
<author><firstname></firstname><surname></surname></author>
<copyright><year></year>
<holder></holder></copyright>
<editor><firstname></firstname><surname></surname></editor>
<isbn></isbn>
<publisher>
<publishername></publishername>
</publisher>
<abstract></abstract>
</biblioentry>
</bibliodiv>
</bibliography>

查看 参考文献 以查看实际效果。

D.8. 实体（快捷方式、文本宏和可重用文本）

可能有一些文本段或标记，你想一遍又一遍地使用。 你可以使用 外部实体，而不是多次键入它（然后如果要进行更改，则必须多次编辑它）。 实体可以为你提供一个捷径：重用整个文档、文本片段和特殊标记。 使用实体的常见方法包括

  • 标记的文本宏。一个例子是公司URL。 通过使用参数实体，你可以简单地引用 &my-company-url; 而不是每次都键入完整的 <ulink url="http://foo.bar">Foo.bar</ulink>。

  • 软件许可。例如GNU自由文档许可证：它很长。 并且必须完整地包含在每个文档中。 通过将许可证保存在单独的文件中，你可以轻松地将其包含在许多文档中，而无需每次都重新进行标记。

  • 重复文本。例如，一个主题的介绍，既作为一节中的摘要包含，又作为另一节中完整信息的介绍包含。 如果你需要更改两组文本，则可以节省编辑时间。

示例D-12。 添加实体

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ 
<-- I can add comments here --> 
<!ENTITY shortcut "Replace 'shortcut' with this text."> 

<!ENTITY sc-to-a-file SYSTEM "anotherfile.xml">
<-- note: the square bracket on the third line is closed on the next
line--> ]>

要使用这些实体，只需将您给实体的名称插入到 "&" (与符号) 和 ";" (分号) 之间。例如："&shortcut;" 将展开为 "Replace 'shortcut' with this text"；"&sc-to-a-file;" 将包含anotherfile.xml 的全部内容。.

在编写文本时，一个重要的特性是检查它是否会在最终稿中呈现。通常，文本的几个部分会被标记为草稿，尤其是在更新现有文档时。

通过使用参数实体，您可以通过仅更改文档开头的一行来包含或删除这些草稿。

示例 D-13. 参数实体的使用

<!ENTITY % review "INCLUDE"> ...
<![%review;[ <para>This paragraph will
be included on the draft when the entity "review" is defined with the
value "INCLUDE". </para> ]]>

实体review可能定义了多个文本，如 示例 D-13 中所示。当对文本的更改被认为是最终版本时，您只需要删除第 3rd 行和第 6th 行之间的文本部分。

要保留草稿定义并在最终稿中隐藏文本，只需将实体的规范从INCLUDE更改为IGNORE.

D.9. 自定义您的 HTML 文件

D.9.1. HTML 文件名

默认情况下，当创建单独的 HTML 文件时，SGML 处理器会为生成的文件分配任意名称。这可能会让读者感到困惑，他们可能会将某个页面添加为书签，但发现它发生了变化。无论您的理由是什么，以下是如何以您想要的方式命名单独的文件

在您的第一个<article>标签（应该是唯一的标签）中，包含一个id参数，并将其命名为 "index"。这将使您的标签看起来像这样

<article id="index">

不要修改第一个<chapter>标签，因为它通常是一个介绍，您希望它位于第一页。对于每个其他<section>标签，包含 id 参数并为其命名。名称应仅包含字母数字字符，并且应足够短以理解它的含义。

 
	<chapter id="tips">

Note明智地选择节 ID
 

我们都知道 Cool URIs Don't Change。这意味着您的 ID 也不应更改。除非 ID 的内容发生了重大变化，并且 ID 名称不再相关。

Warning使用 Jade 生成 HTML 文件名
 

如果您使用 Jade 将您的 DocBook 转换为 HTML，则必须使用以下参数-V %use-id-as-filename%.

D.9.2. 页眉和页脚

没有添加页眉和页脚的 "简单" 方法。如果您正在使用 DocBook XSL 并执行自己的文档转换，您可以自定义 XSL 模板以满足您的需求。有关更多信息，请阅读 http://www.sagehill.net/docbookxsl/HTMLHeaders.html。

附录 E. 将文档转换为 DocBook XML

存在各种免费和商业工具，用于将非 XML 格式 "向上转换" 为 DocBook。为了您的方便，这里列出了一些。更全面的列表可从 将其他格式转换为 DocBook 获取。

E.1. 文本到 DocBook

txt2docbook 工具允许将 ascii (类似 README) 文件转换为有效的 docbook xml 文档。它显著简化了较小论文的发布。输入格式的灵感来自 http://www.xmlmind.com/aptconvert.html 的 APT-Convert 工具。

该脚本可以从 http://txt2docbook.sourceforge.net/ 下载。

E.2. OpenOffice.org 到 DocBook

从 OpenOffice.org (OOo) 1.1RC 开始，支持将文件导出为 DocBook 格式。

尽管 OOo 使用完整的 DocBook 文档类型声明，但它实际上并没有导出完整的 DocBook 元素列表。它使用 "简化" 的 DocBook 标签集，该标签集适用于动态呈现。（尽管它不是 第 B.5 节 中描述的官方简化 DocBook。）OpenOffice 简化 (或 "特殊" docbook) 可从 http://www.chez.com/ebellot/ooo2sdbk/ 获取。

E.2.1. Open Office 1.0.x

OOo 已经过 LDP 志愿者的测试，结果大多是积极的。 感谢 Charles Curley (charlescurley.com) 提供的有关使用 OOo 版本 1.0.x 的以下说明

Note检查您的 OpenOffice 版本
 

这些说明可能不适用于您正在使用的 OOo 版本。

  • 为了能够导出到 DocBook，您必须安装 Java 运行时环境 (JRE) 并在 OOo 中注册 - 建议至少使用 4.2.x 版本。 配置说明将取决于您安装 JRE 的方式。 请访问 OOo 网站以获取有关设置的帮助。

    与 OOo 文档相反，Linux OOo 没有附带 JRE。 我从 Sun 得到一个。

  • 导出的文件有很多空行。 我导出的 54 行文件有 5 行实际 XML 代码。

  • 没有进行美化打印。

  • 标头是<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

  • 文件格式的 文件->另存为对话框中的下拉菜单指示导出格式为 “DocBook (简化版)”。 没有任何解释说明 “简化” 表示什么。 OOo 是否导出 DocBook 的子集？ 如果是这样，哪些元素被忽略了？ 有没有办法手动输入它们中的任何一个？

  • 没有关于 DocBook 导出过滤器或 OOo 是否会再次导入它的文档。

结论：如果您想要一个用于准备 DocBook 文档的文字处理器，那么 OOo 1.1RC 值得一看。

但是，我希望他们能解决缺少文档的问题。 例如，很高兴知道哪些本机 OOo 样式映射到哪些 DocBook 元素。 也很高兴知道如何将自己的 OOo 样式映射到 DocBook 元素。

E.2.2. Open Office 1.1

Tabatha Marshall 提供了以下有关 OOo 1.1 的其他信息。

第一个问题是当我尝试在版本 1.0.1 上完成所有操作时。 这显然是一个问题。 我有 RH8，它是通过 rpm 软件包安装的，所以我把它撕下来并全新安装了 OpenOffice 1.1。 花了一段时间才发现 1.1 是 XML 工作的必要条件。

在安装过程中，我相信我被提供了安装 XML 功能的选择。 我倾向于完整安装我的办公程序，所以我选择了所有内容。

我无法为那些试图更新其当前 OO 1.1 的人提供任何建议。 他们的 “3 种方式” 在该网站 (xml.openoffice.org) 上没有得到很好的记录，并且在撰写本文时，我甚至无法在该网站上找到 THAT。 我认为需要更多当前的文档来引导人们完成整个过程。 大部分内容都不清楚，我必须进行实验才能使事情正常工作。

好吧，在我安装完所有内容后，我需要进行一些配置。 我打开了应用程序，然后通过打开一个新文件，选择模板，然后选择 DocBook 模板开始了。 出现了一个不错的 段落样式 菜单供我使用，这些是所有这些标签的名称，我注意到了（您可以看到我不经常使用 WYSIWYG）。

在一个空白文档摆在我面前（除非打开某种类型的文档，否则无法进入 XML 过滤器设置 菜单），我进入 工具->XML 过滤器设置，并编辑 DocBook 文件的条目。 我将我的配置如下

  • Doctype -//OASIS//DTD DocBook XML V4.2//EN

  • DTD http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd

  • 用于导出的 XSLT /usr/local/OpenOffice.org1.1.0/share/xslt/docbook/ldp-html.xsl

  • 用于导入的 XSLT /usr/local/OpenOffice.org1.1.0/share/xslt/docbook/docbooktosoffheadings.xsl（这是默认值）

  • 用于导入的模板 /home/tabatha/OpenOffice/user/template/DocBook File/DocBookTemplate.stw

起初，如果我打开一个甚至只有一个解析错误的 XML 文件，它仍然会打开该文件并在 OO 中显示标记。 我有很多 XML 文件使用 &copy; 和其他类型的实体，即使它们可以通过处理，也会显示为解析错误（具体取决于编码）。 但今天我无法打开任何这些文件。 我收到了输入/输出错误。 仍在调查这个问题。

但是，当您成功打开文档（没有解析错误的文档）时，它会根据标记自动将其放入 WYSIWYG 中，然后您可以像任何其他此类编辑器一样从段落样式菜单中使用它。

要验证文档，我使用了 工具->XML 过滤器设置，然后单击 测试 XSLT 按钮。 在我的屏幕上，我将用于导出的 XSLT 设置为ldp-html.xsl。 如果您测试并且存在错误，则会弹出一个新窗口，底部显示错误消息，顶部显示需要更改的行。 您可以在那里更改它们，并通过错误进行处理，直到它们全部消失，并不断测试直到它们消失。

如果要打开文件以查看源而不是处理后的结果，请转到 工具->XML 过滤器设置->测试 XSLT，然后在 导入 部分下，选中 显示源 框。 我当前的导入 XSLT 是docbooktosoffheadings.xsl（默认值）和导入模板是DocBookTemplate.stw（也是默认值）。

我认为这可能对某些人有效，但不幸的是对我不起作用。 我从未使用 WYSIWYG 来编辑标记。 带有 PSGML 的 Emacs 可以告诉我我的下一个标签是什么，无论我在哪里，都可以通过移动到问题点进行验证，并且我可以从命令行解析和处理。

使用 OpenOffice，您必须访问 http://xml.openoffice.org/filters.html 才能找到转换工具。

E.3. Microsoft Word 到 DocBook

即使您想使用 MS Word 编写文档，您可能会发现 w2XML 很有用。 请注意，这不是免费软件 - 费用约为 130 美元。 但是，该软件有一个试用版。

E.4. LaTeX 到 DocBook

Siep Kroonenberg 报告说，有一个软件包 tex4ht http://www.cse.ohio-state.edu/~gurari/TeX4ht/，可以将 TeX 和 LaTeX 转换为各种 XML 格式。目前，它对 DocBook 输出的支持有限。如果您想在其当前状态下使用 tex4ht for LDP，您可能需要事先破解您的 LaTeX 源代码，并在之后生成 XML。

E.5. LyX 到 DocBook

本节由 Chris Karakas 贡献。

您可以使用 LyX-to-X 软件包在 LyX（最初开发为 LaTeX 的图形前端的可视化编辑器）中方便地编写文档，然后将其导出到 DocBook SGML 并将其提交给 The LDP。 Chris Karakas 使用 LyX 和 SGML 进行文档处理 介绍了这种方法。

在 LyX-to-X 项目中，LyX 被用作舒适的图形 SGML 编辑器。一旦文档从 LyX 导出到 SGML，它就会通过一系列 sed 和 awk 脚本进行转换，这些脚本可以更正 SGML 代码，计算索引，插入书目和附录，并注意正确调用 openjade、pdftex、pdfjadetex 以及生成 HTML（分块或不分块）、PDF（带有图像、书签、缩略图和超链接）、PS、RTF 和 TXT 版本的其他所有必要程序。

处理文档的所有方面，包括自动生成索引，在线和打印格式中以 TeX 质量显示数学，以及使用带有 RefDB 的书目数据库。特别注意使文档处理对用户尽可能透明 - 目的是用户在 LyX 中编写，然后按下一个按钮，LyX-to-X 脚本完成其余工作。从 Formats section 下载文档和 LyX-to-X 软件包。

E.6. DocBook 到 DocBook 转换

E.6.1. XML 和 SGML DocBook

DocBook XML 和 SGML 之间有一些变化。对于大多数小型文档来说，处理这些差异应该相对容易，并且许多作者不需要进行任何更改来转换他们的文档，除了文档开头的 XML 和 DocBook 声明。

对于其他人，以下是您在将文档从 SGML 转换为 XML 时应记住的一些事项的列表。

NoteXML 和 SGML 元素之间的差异
 

一个 XML 元素通常有三个部分：开始标签、内容（您的单词）和结束标签。限定符添加到开始标签中，称为属性。它们总是有一个名称和一个带引号的值。

<filename class="directory">/usr/local<filename>

开始标签包含一个属性（class），其值为 "directory"。结束标签（也是文件名）不得包含任何属性。

  • 元素名称（标签）及其属性区分大小写——通常为小写。以下内容将无法验证，因为结束标签 <PARA> 为大写

    <para>This part will fail XML validation</PARA>

  • 开始标签中的所有属性必须用“引号”。可以是单引号 (') 或双引号 (")，但不能使用反引号 (`) 或 "智能引号"。用于启动 name="value" 对的引号必须与用于结束该值的引号相同。换句话说：“this”将验证，但 'that" 将不验证。

  • 具有开始标签但没有结束标签的标签称为 "空" 标签，因为它们不包含（围绕）任何内容。这些标签仍然必须以尾部斜杠 (/) 关闭。例如xref必须写成 <xref linkend="software"/>。您可能在 / 和 > 之间没有任何空格。（虽然您可能在最后一个属性后有一个空格：<xref linkend="foo" />。）

  • 发送到转换引擎（DSSSL 或 XSLT）的处理指令必须在标签末尾带有一个问号。所有处理指令都将从输出流中删除。此标签的 XML 版本将如下所示

    <?dbhtml filename="foo"?>

  • 如果您要从 SGML 转换为 XML，请确保文件名指向 .xml 文件而不是 .sgml 文件。如果 .sgml 文件包含 XML，某些工具可能会感到困惑。

  • 在 SGML 中使用标签最小化，而不是在结束标签中写出元素名称。例子<para>This is foo.</>XML 不支持标签最小化，并且不鼓励在 DocBook 中使用它们。

E.6.2. 更改 DTD

DTD 版本更改之间的重大更改涉及对元素（标签）的更改。元素可能：已弃用（这意味着它们将在未来版本中删除）；已删除；已修改；或已添加。几乎所有作者在从较低版本的 DocBook 转换为较高版本时都会遇到更改或已弃用的标签。

DocBook: The Definitive Guide 在展示元素如何组合在一起方面做得非常出色。对于每个元素，它都会告诉您该元素必须包含什么（其内容模型）以及可以包含在什么中（其父元素是谁）。例如：一个note必须包含一个para。如果您尝试编写 <note>Content in a note</note>，您的文档将无法验证。了解元素如何组装将使您更容易理解抛给您的任何验证错误。如果您真的遇到了困难，您也可以发送电子邮件到 LDP 的 docbook 邮件列表以获取更多提示。有关订阅的信息可从 第 2.2 节 获取

所有已弃用或更改为 4.x 的标签都列在 DocBook: The definitive guide 中，由 O'Reilly and Associates 出版。本书也可从 http://www.docbook.org 在线获取。

E.6.2.1. 版本 3.x 和 4.x 之间的差异

以下是一些与 LDP 作者特别相关的元素

  • artheader. 已更改为articleinfo。大多数其他 header 元素已重命名为 info。

  • graphic. 已弃用，并将从 DocBook 5.x 开始删除。要为此做好准备，请开始使用mediaobject。有更多关于mediaobject的信息在 第 D.5 节 中。

  • imagedata. 文件格式现在必须以大写字母书写。如果您为文件格式使用小写或混合大小写拼写，它将失败。

    有效

    <imagedata format="EPS" fileref="foo.eps">

    无效

    <imagedata format="eps" fileref="foo.eps">

词汇表

Abiword

开源文字处理器。

aspell

拼写检查程序。

attribute

属性提供了关于其所在元素的额外信息。属性总是以名称-值对的形式出现在初始化指针上（即"开始标签"）。属性的示例是id="identification"，它赋予属性id的值identification.

层叠样式表 (CSS)

由您的 HTML 浏览器读取的一组叠加规则，浏览器使用这些规则来执行 XML 生成的 HTML 文件的显示、布局和格式化。CSS 允许快速更改外观和感觉，而无需深入 HTML 文件。

目录

用于显示和转换工具的辅助文件，它将公共标识符和 URL 映射到本地文件系统。

并发版本系统 (CVS)

LDP 使用的通用文档管理系统。

DocBook

一种 SGML（和 XML）应用程序，描述了一种文档格式，该格式允许轻松管理文档。

docbook-utils

简化 XML 转换的软件包。

文档类型定义 (DTD)

一组定义元素名称及其属性的语句，用于指定组合和序列的规则。DTD 定义了哪些元素可以或不能插入到给定的上下文中。

DSSSL

DSSSL 代表 Document Style Semantics and Specification Language (文档样式语义和规范语言)。它是一项 ISO 标准 (ISO/IEC 10179:1996)。DSSSL 标准在国际上被用作 SGML 的文档样式表页面语言。

元素

元素描述文档中内容的结构。大多数元素包含一个开始标签、内容和一个结束标签。例如，一个段落元素包括以下所有内容<para>This is the paragraph.</para>. 一些元素是"空"的，不包含内容和结束标记。 一个例子是链接到外部文档，其中URL被打印到页面。 此元素仅包含以下内容<ulink url="http://google.com/>.

Emacs

流行的文本编辑器，尤其是在 UNIX 系统或类似系统上。

实体

实体是一个为某些数据部分指定的名称，以便可以通过名称引用它。 数据可以是任何东西，从简单的字符到章节到 DTD 中的语句集。 实体参数可以是通用的、外部的、内部的或 SGML 数据。 实体类似于编程语言中的变量或宏。

epcEdit

跨平台 XML 编辑器。

外部实体

外部实体指向外部文档。 外部实体用于在 SGML 文档的某些位置包含文本。 它可用于包含示例屏幕、法律注释和章节等。

float

诸如侧边栏、图片、表格和图表之类的对象，当它们在文本上没有固定位置时，被称为浮动对象。 对于打印的文本，图表可以出现在页面的顶部或底部。 如果太大，也可以将其放置在下一页上。

常见问题解答 (FAQ)

LDP 托管许多以问题和答案形式出现的列表文档。 这些文档称为 FAQ。 FAQ 通常是单页文档。

通用实体

通过名称引用的实体，该名称以 "&" 开头并以分号结尾，是一个通用实体。 大多数时候，这种类型的实体用于文档中，而不是 DTD 中。 有两种类型的实体：外部和内部。 它们可以引用特殊字符或文本对象，例如重复的句子、名称或章节。

GNU 自由文档许可证 (GFDL)

类似于免费软件的 GNU 通用公共许可证，但对软件的书面文本和文档有具体说明。

GNU 通用公共许可证 (GPL)

软件的许可证类型，保证该软件仍然可以自由分发，源代码可用，您可以对其进行更改并重新分发这些更改，前提是您继续对您的衍生作品使用相同的许可证。

指南

对于 TLDP 文档来说，太长而无法成为 HOWTO 的文档通常存储为指南。 这些更像是深入处理特定主题的整本书。

HOWTO

讨论如何使用系统或应用程序执行操作的文档。 大多数托管在 TLDP 上的文档都是 HOWTO，解释如何在各种系统上安装、配置或管理数十个应用程序。 HOWTO 通常为 10-25 页。

内部实体

内部实体引用文本的一部分，通常用作频繁重复文本的快捷方式。

ispell

拼写检查程序。

Jade

一个应用程序，它将 DSSSL 样式表中定义的规则应用于 SGML 或 XML 文档，将文档转换为所需的输出。

标记、标记语言 (ML)

添加到文档内容的描述其结构的代码。

元数据

文档中的文本，对于理解主题并不重要，但无论如何都应该存在，例如版本信息、合作作者、对人员的致谢等。

nedit

面向程序员的文本编辑器。

nsgmls, onsgmls

SGML 文档解析器和验证器程序。

OpenOffice (OOo)

与 Microsoft Office 兼容的开源办公套件。

参数实体

一种实体类型，通常用于 DTD 或文档的内部子集中。 实体的名称以百分号 (%) 开头，以分号结尾。

PSGML

Emacs *major mode*，它自定义 Emacs 用于编辑 SGML 文档。

结构化信息标准促进组织 (OASIS)

OASIS 是一个非营利性的全球联盟，致力于推动电子商务标准的开发、融合和采用。

大纲

文档的草稿，它概念化了主题和范围。 即将开展的工作的摘要和待办事项列表。

便携式文档格式 (PDF)

各种操作系统上支持的标准文档类型。

处理指令

处理指令是传递给文档格式化工具的命令。 它以 "<?" 开头。 本文档在呈现为 HTML 时使用处理指令来命名文件<?dbhtml filename="file.html">

PostScript (PS)

专为可打印文档设计的文档格式。 PS 是 UNIX（及其类似系统）上的标准打印格式。

审阅者、审阅过程

TLDP 不接受任何东西。 提交文档后，将由审阅者（由审阅协调员分配的志愿者）检查其一致性、语法、拼写和样式。

SGML

Standard Generalized Markup Language（标准通用标记语言）。 它是一项国际标准 (ISO8879)，它指定了在标记系统中创建电子文档的规则，而与使用的平台无关。

主题和范围

显然，主题是你的文档是关于什么的。 范围定义了你将讨论该主题的哪些领域，以及将涉及多少细节。

标签

由标记 "<" 和 ">" 限定的 SGML 元素。 标签用于标记文档的语义或逻辑结构。 一个例子是标签 <title> 标记标题的开始。

TeX

流行的 UNIX 文本格式化和排版工具。

转换

将文档从其原始 DocBook XML 形式转换为另一种格式（如 PDF、HTML 或 PostScript）的过程。

验证

检查您的 XML 代码以确保其符合您在文档顶部声明的 XML DTD 的过程。

vi Improved (vIm)

UNIX 和类似系统上流行的文本编辑器。

WordPerfect (WP)

流行的文字处理器，可在许多系统上运行。

XML

eXtensible Markup Language（可扩展标记语言）。 专门为 Internet 使用而创建的 SGML 的一个子产品。

xmllint

命令行 XML 解析器和验证器。

XMLmind XML Editor (XXE)

免费但不是开放 XML 编辑器。

xmlto

命令行 XML 转换程序。

XSL

XML 样式语言。 XSL 对于 XML 文档的作用类似于 DSSSL 样式对于 SGML 文档的作用。 XSL 用 XML 编写。

可扩展样式表转换 (XSLT)

用于管理文档的框架，由 XSLT 转换语言、XPath 表达式语言和 XSL 格式化对象组成。

附录 F. GNU 自由文档许可证

F.1. 0. 前言

本许可证的目的是使手册、教科书或其他书面文档在自由的意义上“自由”：确保每个人都有有效的自由来复制和重新分发它，无论是否对其进行修改，无论是商业的还是非商业的。 其次，本许可证为作者和出版商保留了一种因其工作而获得荣誉的方式，同时不被认为对他人所做的修改负责。

本许可证是一种“反版权”，这意味着文档的衍生作品本身必须以相同的意义自由。 它补充了 GNU 通用公共许可证，后者是为免费软件设计的反版权许可证。

我们设计本许可证是为了将其用于免费软件的手册，因为免费软件需要免费文档：免费程序应附带提供与软件相同自由的手册。 但本许可证不限于软件手册； 它可以用于任何文本作品，无论主题或是否作为印刷书籍出版。 我们主要推荐本许可证用于以指导或参考为目的的作品。

F.2. 1. 适用性和定义

本许可证适用于任何手册或包含版权所有者声明其可以根据本许可证的条款分发的其他作品。 下面的“文档”是指任何此类手册或作品。 任何公众成员都是被许可人，并被称为“您”。

文档的“修改版本”是指包含文档或其一部分的任何作品，无论是逐字复制，还是经过修改和/或翻译成另一种语言。

“次要章节” 是指文档的具名附录或前置章节，它专门处理文档的出版者或作者与文档的总体主题（或相关事项）之间的关系，并且不包含任何可能直接属于该总体主题的内容。（例如，如果文档部分是数学教科书，则次要章节不得解释任何数学知识。）这种关系可以是与该主题或相关事项的历史联系，或者是关于它们的法律、商业、哲学、伦理或政治立场。

“不变章节” 是指某些次要章节，其标题在声明该文档根据本许可证发布的通知中被指定为不变章节的标题。

“封面文字” 是指某些简短的文字段落，它们在声明该文档根据本许可证发布的通知中被列为封面文字或封底文字。

“透明” 的文档副本是指一种机器可读的副本，它以一种规范对公众开放的格式表示，其内容可以使用通用的文本编辑器（对于由像素组成的图像，可以使用通用的绘图程序）或（对于绘图，可以使用一些广泛可用的绘图编辑器）直接且简单地查看和编辑，并且适合输入到文本格式化程序或自动翻译成各种适合输入到文本格式化程序的格式。如果以其他方式制作的透明文件格式的标记旨在阻止或劝阻读者进行后续修改，则该副本不是透明的。不是 “透明” 的副本被称为 “不透明”。

透明副本的合适格式示例包括没有标记的纯 ASCII 格式、Texinfo 输入格式、LaTeX 输入格式、使用公开可用的 DTD 的 SGML 或 XML 格式，以及为人类修改而设计的符合标准的简单 HTML 格式。不透明格式包括 PostScript、PDF、只能由专有文字处理程序读取和编辑的专有格式、DTD 和/或处理工具通常不可用的 SGML 或 XML 格式，以及某些文字处理程序仅用于输出目的而生成的机器生成的 HTML 格式。

“标题页” 对于印刷书籍而言，是指标题页本身，以及为了清晰地包含本许可证要求出现在标题页上的材料而需要的后续页面。 对于没有任何标题页的格式的作品， “标题页”是指最显著出现作品标题附近的文本，位于正文的开头之前。

F.3. 2. 逐字复制

您可以通过任何媒介复制和分发文档，无论是商业用途还是非商业用途，前提是在所有副本中都复制本许可证、版权声明以及声明本许可证适用于文档的许可证声明，并且您不得在本许可证的条款中添加任何其他条件。您不得使用技术措施来阻碍或控制您制作或分发的副本的阅读或进一步复制。但是，您可以接受报酬以换取副本。如果您分发足够多的副本，您还必须遵循 第 3 节中的条件。

您也可以按照上述相同条件出借副本，并且可以公开展示副本。

F.4. 3. 大量复制

如果您出版的文档印刷副本超过 100 份，并且文档的许可证声明要求 封面文字，则您必须将这些副本装在封面上，这些封面清晰且可读地包含所有这些封面文字：封面上的封面文字和封底上的封底文字。两个封面还必须清晰且可读地标识您为这些副本的出版者。封面必须以同样突出和可见的方式呈现完整的标题及其所有文字。您也可以在封面上添加其他材料。只要它们保留文档的标题并满足这些条件，则仅限于对封面进行更改的复制在其他方面可以被视为逐字复制。

如果任何一个封面的所需文字太多而无法清晰地容纳，则您应将列出的第一个文字（尽可能多的文字）放在实际封面上，并将其余文字继续放到相邻页面上。

如果您出版或分发超过 100 份不透明的文档副本，则您必须随每个不透明副本附上一个机器可读的 透明副本，或者在每个不透明副本中或附带一份公开可访问的计算机网络位置，其中包含文档的完整透明副本，该副本不包含添加的材料，并且普通网络用户可以使用公共标准网络协议免费匿名下载。如果您使用后一种选项，则您必须采取合理谨慎的措施，当您开始大量分发不透明副本时，确保该透明副本在所述位置保持可访问状态，直到您向公众分发该版本的最后一个不透明副本（直接或通过您的代理商或零售商）至少一年后为止。

我们建议（但不是强制要求）您在重新分发大量副本之前与文档的作者联系，让他们有机会为您提供文档的更新版本。

F.5. 4. 修改

您可以根据上述 第 2 节 和 第 3 节 的条件复制和分发 修改版本 的文档，前提是您完全根据本许可证发布修改版本，修改版本扮演文档的角色，从而允许拥有修改版本副本的任何人分发和修改该版本。此外，您必须在修改版本中执行以下操作：

  • A. 在 标题页（以及封面，如果存在）上使用与文档的标题以及以前版本的标题不同的标题（如果存在以前的版本，则应将其列在文档的历史记录部分中）。如果该版本的原始出版者给予许可，您可以使用与以前版本相同的标题。

  • B. 在 标题页上，作为作者列出对 修改版本 中的修改负责的一个或多个人员或实体，以及至少五位文档的主要作者（如果文档的主要作者少于五位，则列出所有主要作者）。

  • C. 在 标题页上，说明 修改版本 的出版者名称，作为出版者。

  • D. 保留文档的所有版权声明。

  • E. 在其他版权声明旁边添加一个适合您修改的版权声明。

  • F. 在版权声明之后立即添加一个许可证声明，允许公众根据本许可证的条款使用 修改版本，其形式如下面的附录所示。

  • G. 在该许可证声明中保留不变章节的完整列表和文档许可证声明中给出的所需封面文字。

  • H. 包含本许可证的未更改副本。

  • I. 保留标题为 “历史记录” 的章节及其标题，并在其中添加一项，至少说明 修改版本的标题页上给出的标题、年份、新作者和出版者。 如果文档中没有标题为 “历史记录” 的章节，则创建一个说明文档标题页上给出的文档标题、年份、作者和出版者的章节，然后添加一个描述修改版本的项目，如前一句所述。

  • J. 保留文档中给出的网络位置（如果有），以便公众访问文档的 透明 副本，同样保留文档中给出的基于先前版本的网络位置。 这些可以放在 “历史记录” 章节中。 您可以省略至少在文档本身之前四年发布的某个作品的网络位置，或者如果它所指的版本的原始发布者给予许可。

  • K. 在任何标题为 “致谢” 或 “献词” 的章节中，保留该章节的标题，并保留该章节中每个贡献者致谢和/或献词的所有实质内容和语气。

  • L. 保留文档的所有不变章节，不得更改其文本及其标题。 章节编号或等效内容不被视为章节标题的一部分。

  • M. 删除任何标题为 “背书” 的章节。 修改版本中不得包含此类章节。

  • N. 不要将任何现有章节重新命名为 “背书” 或与任何 不变章节的标题冲突。

如果修改版本包含符合次要章节条件且不包含从文档复制的材料的新前置章节或附录，您可以选择将这些章节中的一些或全部指定为不变章节。 为此，请将它们的标题添加到修改版本许可证声明中的 不变章节 列表中。 这些标题必须与任何其他章节标题不同。

您可以添加一个标题为 “背书” 的章节，前提是它仅包含各个方对您的 修改版本 的背书——例如，同行评审声明或该文本已被某个组织批准为标准的权威定义。

您最多可以在修改版本中 封面文字 列表的末尾添加一个最多五个单词的段落作为封面文字，以及一个最多 25 个单词的段落作为封底文字。 任何一个实体（或通过其安排）只能添加一段封面文字和一段封底文字。 如果文档已经包含了由您或由您代表的同一实体安排先前添加的相同封面的封面文字，则您不得添加另一个； 但是，您可以替换旧的封面文字，但需要获得先前添加旧封面文字的出版者的明确许可。

文档的作者和出版者不通过本许可证授予使用他们的姓名进行宣传或断言或暗示任何 修改版本 的认可的许可。

F.6. 5. 合并文档

您可以根据上述 第 4 节 中为修改版本定义的条款，将文档与根据本许可证发布的其他文档合并，前提是您在合并中包含所有原始文档的所有不变章节（未修改），并在其许可证声明中将它们全部列为您的合并作品的不变章节。

合并后的作品只需包含一份本许可证，并且多个相同的不变部分可以被替换为一份副本。如果存在多个名称相同但内容不同的不变部分，则通过在每个此类部分的末尾添加圆括号，并在圆括号中注明该部分的原始作者或出版商（如果已知），或者添加一个唯一的编号，来使每个此类部分的标题具有唯一性。对合并作品的许可证声明中不变部分列表中的章节标题进行相同的调整。

在合并时，您必须合并各个原始文档中所有标题为“历史”的章节，形成一个标题为“历史”的章节；同样地，合并所有标题为“致谢”的章节，以及所有标题为“献词”的章节。您必须删除所有标题为“背书”的章节。

F.7. 6. 文档集合

您可以创建一个集合，其中包含文档和其他根据本许可证发布的文档，并将各个文档中的本许可证的单独副本替换为包含在集合中的单个副本，前提是您在所有其他方面都遵循本许可证关于每个文档的逐字复制的规则。

您可以从这样的集合中提取单个文档，并根据本许可证单独分发它，前提是您将本许可证的副本插入到提取的文档中，并在所有其他方面都遵循本许可证关于该文档的逐字复制的规定。

F.8. 7. 与独立作品的聚合

将文档或其衍生作品与其他的、单独的和独立的文档或作品，组合在一个存储或分发介质的卷中或之上，整体上不被视为文档的修改版本，前提是没有为该组合声明组合版权。这样的组合被称为“聚合”，并且本许可证不适用于与文档组合的其他独立作品，因为它们这样被组合，如果它们本身不是文档的衍生作品。如果第3节的封面文字要求适用于这些文档副本，那么如果文档小于整个聚合的四分之一，则文档的封面文字可以放置在仅围绕聚合内文档的封面上。否则，它们必须出现在围绕整个聚合的封面上。

F.9. 8. 翻译

翻译被认为是一种修改，因此您可以根据第4节的条款分发文档的翻译版本。用翻译替换不变部分需要获得其版权持有者的特别许可，但您可以包含某些或所有不变部分的翻译，以及这些不变部分的原始版本。您可以包含本许可证的翻译版本，前提是您还包含本许可证的原始英文版本。如果翻译版本和原始英文版本之间存在分歧，则以原始英文版本为准。

F.10. 9. 终止

除非本许可证明确规定，否则您不得复制、修改、再授权或分发文档。任何其他复制、修改、再授权或分发文档的尝试都是无效的，并将自动终止您在本许可证下的权利。但是，根据本许可证从您那里收到副本或权利的各方，只要这些各方始终完全遵守本许可证，他们的许可证就不会被终止。

F.11. 10. 本许可证的未来修订

自由软件基金会可能会不时发布 GNU 自由文档许可证的新修订版本。这些新版本在精神上与当前版本相似，但在细节上可能会有所不同，以解决新的问题或疑虑。参见https://gnu.ac.cn/copyleft/。

许可证的每个版本都给出一个区分版本的编号。如果文档指定本许可证的某个特定编号的版本“或任何更高版本”适用于它，您可以选择遵循该指定版本或自由软件基金会发布的任何更高版本（不是草案）的条款和条件。如果文档未指定本许可证的版本号，您可以选择自由软件基金会发布的任何版本（不是草案）。

F.12. 附录

要在您编写的文档中使用本许可证，请在该文档中包含本许可证的副本，并在标题页之后放置以下版权和许可证声明

版权 � YEAR YOUR NAME。

允许根据 GNU 自由文档许可证 1.1 版或自由软件基金会发布的任何更高版本的条款复制、分发和/或修改本文档；不变部分是 列出它们的标题，封面文本是 列出，封底文本是 列出。许可证的副本包含在标题为“GNU 自由文档许可证”的章节中。

如果您没有不变部分，请写“没有不变部分”，而不是说哪些是不变的。如果您没有封面文本，请写“没有封面文本”，而不是“封面文本是 列出”；对于封底文本也一样。

如果您的文档包含程序代码的非平凡示例，我们建议您在您选择的自由软件许可证（例如GNU 通用公共许可证）下并行发布这些示例，以允许在自由软件中使用它们。

注释

[1]

请查看源代码，了解如何在您的文档中获得类似的结果。您还应该记住，这在您看来如何取决于您阅读本文档的格式：在线外观与 PostScript 或 PDF 格式略有不同。

[2]

事实上，“XSL”实际上由三个组成部分组成：XSLT 转换语言、XPath 表达式语言（由 XSLT 使用）和用于描述页面的 XSL 格式化对象 (FO)。样式表实际上是用 XSLT 编写的，并生成 HTML 或（对于打印输出）FO。然后 FO 文件通过 FO 处理器运行，以创建实际的打印（PDF 或 PostScript）输出。有关更多信息，请参见 W3C 网站。

[3]

在 XSL 术语中，生成多个文件的过程被称为“分块”。