DG2.3. 文档源码
文档源码包括纯文本文件、手册页和 html。不过，Postgres 的新文档大多将使用标准通用标记语言（SGML） DocBook 文档类型定义（DTD）编写。现有文档的大部分已经或将被转换为 SGML。
SGML 的目的是让作者能够指定文档的结构和内容（例如使用 DocBook DTD），并由文档样式定义这些内容如何被渲染成最终形式（例如使用 Norm Walsh 的样式表）。
文档积累自多个来源。随着我们把现有文档整合成一个连贯的文档集，较旧的版本将逐渐过时，并会从发行包中删除。但是，这不会立即发生，也不会同时发生在所有文档上。为了简化过渡，并帮助引导开发者和作者，我们定义了一份过渡路线图。
DG2.3.1. 文档结构
目前有五份用 DocBook 编写的独立文档。每份文档都有一个容器源文档，它定义 DocBook 环境和其他文档源文件。这些主源文件位于
doc/src/sgml/，文档使用的许多其他源文件也在那里。主源文件有：
- postgres.sgml
这是集成文档，把所有其他文档作为部分包含在内。它以 HTML 格式生成输出，因为浏览器界面让你只需点击就能在全部文档之间轻松跳转。其他文档同时提供 HTML 和硬拷贝两种格式。
- tutorial.sgml
入门教程，带示例。不包括编程主题，旨在帮助不熟悉 SQL 的读者。这是“入门”文档。
- user.sgml
用户指南。包括数据类型和用户级接口的信息。这是放置“为什么”类信息的地方。
- reference.sgml
参考手册。包括 Postgres SQL 语法。这是放置“怎么做”类信息的地方。
- programming.sgml
程序员指南。包括 Postgres 可扩展性以及编程接口的信息。
- admin.sgml
管理员指南。包括安装说明和发行说明。
DG2.3.2. 样式与约定
DocBook 有一组丰富的标签和构造，其中直接而明显地适用于良构文档的百分比出人意料地高。Postgres 文档集最近才改写为 SGML，不久将来会从文档集中选出若干节，作为 DocBook 用法的示范性示例加以维护。此外，下面还会给出 DocBook 标签的简短摘要。
DG2.3.3. SGML 编写工具
当前的 Postgres 文档集是使用纯文本编辑器（或 emacs/psgml，见下文）编写的，内容用 SGML DocBook 标记。
SGML 和 DocBook 的开源编写工具并不多。最常见的工具集是带 psgml 功能扩展的 emacs/xemacs 编辑软件包。在某些系统（例如 RedHat Linux）上，典型的完整安装会包含这些工具。
DG2.3.3.1. emacs/psgml
emacs（以及 xemacs）有一种 SGML 主模式。正确配置后，它可以让你用 emacs 插入标签并检查标记的一致性。
把以下内容放入你的 ~/.emacs
环境文件（把路径名调整为适合你系统的值）：
; ********** for SGML mode (psgml)
(setq sgml-catalog-files "/usr/lib/sgml/CATALOG")
(setq sgml-local-catalogs "/usr/lib/sgml/CATALOG")
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
并在同一文件中为 SGML 向（已有的）auto-mode-alist 定义中加入一项：
(setq
auto-mode-alist
'(("\\.sgml$" . sgml-mode)
))
每个 SGML 源文件的末尾都有下面这一块：
!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
--
Postgres 发行包中包含一个已解析的 DTD 定义文件 reference.ced。你可能会发现
使用 emacs/psgml 时，处理这些分别保存书籍各部分的文件，有一种方便的方式：在编辑时插入适当的 DOCTYPE 声明。例如，当前这个源码文件是一章附录，因此可以将它指定为 DocBook 文档的“appendix”实例，把第一行写成这样：
!doctype appendix PUBLIC "-//Davenport//DTD DocBook V3.0//EN"
这意味着任何读取 SGML 的东西都能正确处理它，而且我可以用“nsgmls -s docguide.sgml”验证该文档。