文档开发心得与技巧

1.  检出网站文档

使用匿名CVS

贡献者们应该使用我们的匿名CVS服务器。它与Gentoo开发者使用的官方CVS拥有相同的文件。匿名CVS仓库每小时更新一次。

创建一个专门用于文档开发的目录，然后从网站上检出文档。

$ cvs -d :pserver:anonymous@anoncvs.gentoo.org/var/cvsroot co gentoo/xml

要更新你的本地仓库，请在gentoo/xml目录下运行cvs update -dP命令。

Gentoo开发者使用的实时(live)仓库

你还没有检出gentoo模块么？赶紧的吧：

$ export CVSROOT=<your nick>@cvs.gentoo.org:/var/cvsroot
$ cvs co gentoo/xml

要更新你的本地仓库，请在gentoo/xml目录下运行cvs update -dP命令。

在线CVS仓库

你可以要求在线CVS仓库提供两个独立版本之间的不同之处(diff)。主英文仓库现已全面启用。在线CVS仓库会每小时更新一次。

2.  设置你的本地环境

安装gorg

我们的GuideXML文档是由www-server/gorg转换为HTML的，你需要安装它。

请依照gorg主页上的指南来配置它，你需要将检出CVS文档仓库的目录（.../gentoo/xml/htdocs）设置为web根目录。其他的参数只当你想在本地提供一份www.gentoo.org的副本时有用。

设置你的XML环境

你需要让系统知道上哪去找我们文档中用到的DTD文件。请用root权限编辑/etc/xml/catalog文件，并添加一下几行：

<rewriteURI uriStartString="/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>

如果根本没有/etc/xml/catalog文件或者文件中啥内容没有，你需要在<catalog>元素之中插入Ult;rewriteURI>元素

<?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">
  <rewriteURI uriStartString="/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>
</catalog>

另外，因为一些文档采用了在线DTD，你可以修改类似http://www.gentoo.org/dtd/guide.dtd的链接(uri)来避免因需要网络而带来的访问慢的问题。

<rewriteURI uriStartString="http://www.gentoo.org/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>

测试Gentoo指南

要测试Gentoo指南，首先请使用xmllint（来自dev-libs/libxml2）来检查其XML的正确性：

$ xmllint --valid --noout alsa-guide.xml

如果xmllint没有返回任何信息，说明文档的结构验证通过。下一步你需要将其转换为HTML：

$ gorg < alsa-guide.xml > alsa-guide.html

如果没有显示任何错误，你应该能用浏览器来查看alsa-guide.html文档;如果有错误，请修正你的指南文档。

浏览gentoo web站点的本地副本

自打你从我们的CVS中检出Gentoo web站点之后 ，你就也可以通过gorg来浏览你的本地副本了。如果你想拥有一模一样的主页，请确认你已经照gorg的主页上的方法下载了新闻索引。

3.  常见问题

如何转换文档编码为UTF-8？

这里有不少工具可以帮你。app-text/recode比较常用。iconv也比较流行，它是sys-libs/glibc的组件。

Recode使用起来相当直接。你告诉它当前文档的编码，以及你想转换成的编码就行。

比方说，要将一个编码为ISO-8859-15（经常被称为Latin-9）的文档转换成编码UTF-8，你可以用：

(l9 = ISO-8859-15, u8 = UTF-8)
$ recode l9..u8 file.xml

4.  文档提交的技巧

<guide>标签检查

请确认<guide link>属性指向了指南文档的正确位置。其通常为/doc/zh_cn/filename.xml。如果你有已经翻译好的文档，请指定访问此文档的绝对路径（例如：/doc/zh_cn/）。如果你正在写一个采用了guide或bookDTD的指南文档，那么你既可以用/doc/zh_cn/filename.xml也可以用filename.xml。通常GDP推荐使用前一种形式。

链接检查

你必须查实文档中所有的超链接都能正常访问。如果是翻译文档，请注意其链接中指向的另一个翻译文档是否也存在。

标签检查

在GuideXML中除了文档需要（例如教用户使用标签的文档）外绝对禁止出现标签。检查文档中的标签可以运行grep "CTRL+V<TAB>"file.xml。修正有grep屏显的任何行。

Bugzilla

一旦你完成了文档，请使用Bugzilla向文档小组提交它。你没必要提供诸如平台、emerge info信息、架构、完成的步骤等等。如果你提交的是翻译文档，提交bug时请务必选择Doc Translations组件。同时，请为你的翻译文档写个简介，格式如下："[zh_cn]New translation:/doc/zh_cn/gnupg-user.xml[zh_cn]"。请用你自己的语言代码替换[zh_cn]。

默认情况下，docs-team@gentoo.org即将会是你翻译文档的受理人。你不需要去修改它。

提交文档或补丁的附件时，请选择纯文本"plain text(text/plain)"。千万不要选择"XML source (application/xml)"，即便你提交的确实是.xml文档。文档补丁应当通过"Patch"选项的检查。不要提交一个包含很多文档的压缩包，文档也好，补丁也好，请一个一个单独提交。

5.  易犯的或危险的错误

Forgetting the all-arch-aspect of the Gentoo Handbook

[gentoo]/xml/htdocs/doc/en/handbook中不是以"-<arch>.xml"后缀结束的文件将会被所有手册读取，这意味着不管其中有什么内容一定是多架构支持的。

如果你需要针对你自己的架构做出修改，恐怕你需要就此先询问一下gentoo-doc@gentoo.org如何解决。往往会有对其他架构的用户也不太困难的方法的。

不要随意刷新或错误设置版本号/日期

按照规定，如果对文档做出了一定修改（实质性修改），必须更新版本号/日期。尽管版本号似乎不那么重要（SwifT will still kill you if you forget it），但日期会告诉读者文档的最后修改是什么时候。

如果对文档的内容(content)做出了修改（介绍啊，示例代码啊等等），就必须升级版本号。而对于非内容(non-content)的更改(例如排版或GuideXML修正)，版本号升级就没有必要了。

更新安装手册是，只需更新你所修改文档的日期和版本号。不要更新handbook-ARCH.xml，除非你确实修改了它们的内容。

另一个常见错误是更新版本号的数位时出现的。3.9应该变为3.10，而不是4.0，更不是3.91。

本文档的内容遵循知识共享-署名-相同方式共享许可协议