查看“UbuntuChina文档组/文档库”的源代码




=== 关于文档库 ===

文档库是版本控制系统 Subversion 项目的文档源码。[[UbuntuChina文档组]] 的工作就是围绕着 Subversion 文档库来展开的。Subversion 可以帮忙我们在同时对相同文件进行操作时不会出现问题。任何想对文档贡献的文档撰写者都可以从文档源码中检出他们自己的“工作副本”并对该副本做修改。

要检出你的工作副本，你需要安装`subversion`，如果你从来都没有用过版本控制系统，别担心 - 你不会破坏库中的任何东西，而只是你本地的工作副本。这是因为你是匿名用户 ，因此没有权限去改变库中的任何东西。只有拥有提交权限的人才可以改动文档库。

Subversion 有着很好的支持。目前已经有很多的学习资源，强烈推荐的资源也是最优秀的书 [http://svnbook.red-bean.com/ 《使用Subversion进行版本控制》]。

这本书很适合 Subversion 用户和管理员，仍然它是用命令行界面（CLI）来解释 Subversion 的特性和功能的。许多人更喜欢用 GUI 应用程序来代替 CLI。这里有一些 Subverion 的 GUI 前端工具。下面是你一些可用的工具列表：

* eSvn （源中有，基于QT开发）
* Rapid SVN （源中有，基于C开发）
* TortoiseSVN （Windows下的 Subversion 工具）
* Java SVN (JSVN) （大家都看得出吧）

=== 获取文档 ===

第一步: 用你喜欢的包管理工具安装 'subversion' 包文件。

现在如果你键入 `svn help` 你将看到 subversion 命令的一些帮助：
<pre><nowiki>
$ svn help
usage: svn <subcommand> [options] [args]
Type "svn help <subcommand>" for help on a specific subcommand.

Most subcommands take file and/or directory arguments, recursing
on the directories.  If no arguments are supplied to such a command, it will recurse on the current directory (inclusive) by
default.

Available subcommands:
add
[...]
</nowiki></pre>

然后决定你在哪儿存放你文档源码的工作副本。在本文档中，我们假设你将它放在你用户目录中的 "ubuntu-doc" 目录下。不要创建目录： subversion 会自动创建的。

接下来是获取文档库的工作副本 （这叫 ''检出（checkout）''）
* 进入你的用户目录 
<pre><nowiki>
cd ~ </nowiki></pre>
* 执行 svn checkout 
<pre><nowiki>
svn checkout https://docteam.ubuntu.com/repos/trunk ubuntu-doc
</nowiki></pre>

它将创建 ~/ubuntu-doc 目录（你可以将它改成你喜欢的名字），该目录包括最新版本的副本。

第一次是检出是要花一些时间的，因为它要下载开发版中的全部内容。这样的好处是你可以一次性获取全部代码。如果你想得到以后（或过去）的版本，subversion 将不会下载所有内容，而只是下载改变过的内容。

浏览一下检出的文档库. 你可以找到一份描述库中文件夹的文档。你也可以看到一些名为 `.svn` 的目录，这些目录是 subversion 专用的。

现在 ubuntu-doc 文件夹中已经有了文档库中所有源码，你可以按你喜欢的方式开始工作了。别担心你会搞乱什么：无论你做什么，你都不会影响到服务器上的文档库的。

=== 授权访问 ===

[[UbuntuChina文档组]] 的核心成员有向文档源写的权限。他们可以将在他们工作副本中的改变合并到文档库中。他们使用用户名和密码来使他们对文档库有读写权限。

文档提交者也要向上面所说的相同方式检出工作副本。仍然，当他们第一次提交（svn commit）时，系统会提示他们要输入用户名和密码。

这个只需要在第一次提交时做，用户名和密码会被保存在他们用户目录下的 '.subversion' 文件夹中， 以便被所有后续的提交操作使用。

=== 做一些修改 ===

你可以通过下列命令来编辑《Ubuntu桌面入门指南》中的“从这里开始”一章。
<pre><nowiki>
nano ~/ubuntu-doc/ubuntu/desktopguide/C/getting-started.xml
</nowiki></pre>
你可以发现文件是XML格式写的。XML格式是用 [[DocBook]] 格式来编写的. 它并不直观，而且很象 HTML 文件，但你可以从中得到一个大概的框架。例如 
<pre><nowiki>
<title>Introduction</title>
</nowiki></pre> 是一个标题，而 
<pre><nowiki>
<para>Thank you for your interest in Ubuntu Linux &distro-rev;
-- our &distro-version; release.</para>
</nowiki></pre> 则是一段正文。 注意 that `&distro-rev` 是一个变量，就象$HOME一样。相对于重复地输入相同的字符串，使用变量无疑会更方便。你可以再在新的 `<para>` 和 `</para>` 标识对中添加内容来生成一段新的正文。 与其他类型的编辑方式不对，你可以通过看看已经写好的 [[DocBook]] 来猜猜它是怎么工作的。因为你可能甚至在读到这些之前就注意到了这些。

在编辑后的下一步就是生成 HTML 文档。首先运行 make 命令，通过运行下面的命令以确保 docbook-xsl 文件包已经被安装:
<pre><nowiki>
sudo apt-get install docbook-xsl
</nowiki></pre>

一旦 docbook-xsl 文件包被安装, 你就可以用下面的命令来生成 HTML 文档了：
<pre><nowiki>
cd ~/ubuntu-doc/ubuntu
make dg
</nowiki></pre>
控制台输出的最后一行告诉你在哪找到 HTML 文档： 
<pre><nowiki>
Complete. Find outputs at ../build/ubuntu/desktopguide/C/
</nowiki></pre>
通常 HTML 文档是首页是 <code><nowiki>index.html</nowiki></code>. 
<pre><nowiki>
ls ../build/ubuntu/desktopguide/C/index.html
</nowiki></pre>
因为你编辑了“从这里开始”这一节，所以你要从首页中找到它，幸运的是它就在第一章，你可以点击进入并查看你所做的改变。

=== 公示你所作的改动 ===

在你确认没有错误之后，你就可以开始将你所作的工作公示出来了。首先你要检查你修改了哪个文件。 
<pre><nowiki>
cd ~/ubuntu-doc/ubuntu
svn status
?      desktopguide/C/db/getting-started.db
M      desktopguide/C/getting-started.xml
</nowiki></pre>
这将显示你修改了哪个文件。被修改的文件前会标记了一个 <code><nowiki>M</nowiki></code>. 如果文件前标记的是 <code><nowiki>?</nowiki></code>，那么这意味着它不属于文档库。它可能是在你工作期创建的其他文件。

其次，你要创建一个补丁文件以便将你的贡献合并到文档库中。
<pre><nowiki>
svn diff
</nowiki></pre>
结果如下所示： 
<pre><nowiki>
Index: desktopguide/C/getting-started.xml
===================================================================
--- desktopguide/C/getting-started.xml  (revision ....)
+++ desktopguide/C/getting-started.xml  (working copy)
</nowiki></pre>
However, you want to redirect the console output to a file such as 
<pre><nowiki>
svn diff > getting-started.xml.patch
</nowiki></pre>
最后，将该文件作为附件粘贴到 [[文档项目补丁列表]] 中，你可以选择直接贴在 [[文档项目补丁列表]] 中。

注意： 将几个小修改并成一个大改动再贴到 Wiki 中将更有效率。

=== 文档库结构 ===

下面是对 [[官方文档翻译项目]]文档库结构的说明。

作为标准的 Subversion 库所管理的文档库被分为三个文件夹：

* trunk/
* branches/
* tags/

trunk 文件夹是针对当前版本做开发的地方。这个是一个工作文件夹。一开始你只需要下载这个目录。branches 文件夹是放置从 trunk 文件夹的一个修定版分离出来的一个分支，工作在主流开发之外。为什么要这么做呢？因为有时你要做的改变非常大。 

这样改动将会干扰到其他开发人员，所以你需要在一个分支中进行开发，这样你所做的改变将不会影响他人。当会产生干扰的工作结束并且 trunk 中也做了相应的调整，使其随时都可以合并分支时分支就可以被并回 trunk 中了。使用分支的问题在于有时 branch 和 trunk 都得到了进一步发展，这就使得将分支并回 trunk 变得更加困难。因此一个好的做法是当工作在分支时监视 trunk，尽可能将 trunk 中的补丁合并到分支中来。其他开发人员也可以读写分支。更详细地说明如何管理分支可以参阅[http://svnbook.red-bean.com/ 《使用Subversion进行版本控制》]

tags 文件夹用于保存特定的文档版本。 标识通常会与发行版本保持一致所以被用发行版本来命名它。如：

* `WartyWarthog`
* `HoaryHedgehog`
* `BreezyBadger`
* `DapperDrake`

改变标识是不会发生的，因为一旦一个版本被做标识，那么它对于后续版本而言就是一种保护。没有人会期待一个库管理员会去做更换，即使它很少发生。tags 文件可以被看成是一个不再改变的存档.

==== 文档库结构树 ====

<pre><nowiki>
/trunk
|
- /ubuntu
|     |_ /about-ubuntu
|     |_ /desktopguide
|     |_ /quicktour
|     |_ /upstream (some gnome upstream documents)
|     |_ etc..
|
|
- /kubuntu
|     |_ /desktopguide
|     |_ /quickguide
|     |_ etc..
|
- /generic
|     |_ /installguide
|     |_ /serverguide
|
- /common
|     |_ etc... (entities, licences, any common stuff)
|
- /build
|_ etc.. (this contains builds of the documents when made)
</nowiki></pre>


=== 其他技巧 ===

如果有人对文档库做了改动，而你想更新你的文档库，那么你可以进入 ubuntu-doc 文件夹并键入：
<pre><nowiki>
svn up
</nowiki></pre>  然后，你的文档库将会升级，升级过程是非常快的。

在本地，subversion 也可以将任何文件恢复到最后一次 ''checkout'' 或 ''update'' 的状态。(使用 <code><nowiki>svn revert <filename></nowiki></code>)