Gentoo Logo

声明: 本文档正在撰写中,不应该视本文为官方版本。


文档开发心得与技巧

内容:

1.  检出网站文档

使用匿名CVS

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

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

代码 1.1: 检出网站文档

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

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

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

你还没有检出gentoo模块么?赶紧的吧:

代码 1.2: 检出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-0.6.3以上的版本。请为你的架构添加关键字(keyword)。

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

设置你的XML环境

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

代码 2.1: /etc/xml/catalog addendum

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

注意: 当然,你可以根据从CVS检出DTD文件时的具体情况修改路径参数。

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

代码 2.2: /etc/xml/catalog的最简形式

<?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)来避免因需要网络而带来的访问慢的问题。

代码 2.3: /etc/xml/catalog的额外补充

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

测试Gentoo指南

要测试Gentoo指南,首先请使用xmllint(来自dev-libs/libxml2)来检查其XML的正确性:

代码 2.4: 使用xmllint验证GuidXML

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

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

代码 2.5: 转换为HTML

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

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

注意: 在安装手册的章节中,将不会生成指向其他章节的链接。因为在线访问安装手册的章节时,采用了master file以及chappart参数。

浏览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,你可以用:

代码 3.1: 文件编码转换

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

4.  文档提交的技巧

<guide>标签检查

请确认<guide link>属性指向了指南文档的正确位置。其通常为/doc/zh_cn/filename.xml。如果你有已经翻译好的文档,请指定访问此文档的绝对路径(例如:/doc/zh_cn/)。如果你正在写一个采用了guidebookDTD的指南文档,那么你既可以用/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



打印

更新于2007年 3月 8日

本文档的原始版本最后更新于2010年 12月 6日

总结: 一些将Gentoo文档开发工作变简单的心得技巧

Xavier Neys
作者

Sven Vermeulen
作者

楚石
翻译

Donate to support our development efforts.

Copyright 2001-2014 Gentoo Foundation, Inc. Questions, Comments? Contact us.