PostgreSQL
上一页	附录 DG2. 文档	下一页

文档源文件

文档源文件包括纯文本文件，手册页和 html．不过，大多数新的 Postgres 文档将用标准的一般性标记语言（Standard Generalized Markup Language）（SGML）DocBook文档类型定义（Document Type Definition ）（DTD）书写．目前存在的许多文档都已经或将要被转换成 SGML．

SGML 的目的是允许一个作者声明一份文档的结构和内容（例如，使用 DocBookDTD），并且由文档风格定义内容是如何呈现为最后的形式（例如，使用 Norm Walsh 的风格表（stylesheets））．

文档是从几个不同的源收集来的．在我们把现有文档整合组装成一个连贯的文档集时，原先的文档就过时了并且将被从版本中删除．但是，这些动作不会立即发生，并且不会对所有文档同时产生作用．为简化翻译工作，以及为了给开发人员和作者提供帮助，我们定义了翻译过程图．

文档结构

目前有五套用 DodBook 书写的独立的文档．每个文档都有一个源文档容器，该容器定义 DocBook 环境和其他文档源文件．这些基本的源文件放在 doc/src/sgml/，与许多文档使用的其他源文件放在一起．主要的源文件是：

postgres.sgml
tutorial.sgml: 介绍教程和例子．不包括编程的话题，而且是试图帮助那些不熟悉 SQL 的读者．这是"启蒙"文档．
user.sgml: 用户手册．包括数据类型和用户级接口的信息．这是放关于"为什么"的信息的地方．
reference.sgml: 参考手册．包括 Postgres SQL 语法．这是放关于"怎么做"的信息的地方．
programming.sgml: 程序员手册．包括 Postgres 扩展性和编程接口的信息．
admin.sgml

管理员手册．包括安装和发布信息．

风格和传统

DocBook 有着丰富的标记和构件，并且让人惊奇的是其中有很大一部分很显然对格式良好的文档很有帮助．Postgres 的文档集只是最近才采纳了 SGML，并且在不远的将来，有一部分章节将被选择出来并且作为 DocBook 应用的样例原形进行维护．同样在下面将包括一个简短的DocBook 标记的概要．

SGML 写作工具

目前的 Postgres 文档集是用纯文本编辑器（或者说 emacs/psgml；见下文）用 SGML 对其内容进行标记写成的．

SGML 和 DocBook 没有受到过多的开放源码写作工具的影响．最常用的工具集是带有 psgml 扩展特性的 emacs/xemacs 编辑包．在一些系统上（例如．RedHat Linux）这些工具在典型的完全安装时是一并安装的．

emacs/psgml

emacs（以及 xemacs）有一个 SGML主模式（major mode）。如果正确的做了配置，它将允许你使用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" 校验此文档．

上一页	首页	下一页
文档项目	开头	制作文档