关于项目

必备工具

没有金刚钻，不揽瓷器活。趁手的兵器往往让你事半功倍。为了更好地参与翻译计划，你最好能够熟练使用Sphinx和Subversion（SVN）。如果二者都不熟悉，那么也可以将无格式的译文文稿通过邮件发送给我。

Subversion

用于进行版本控制。如果你是Linux用户，那么命令行版本就挺好。如果你是Windows用户，那么推荐使用TortoiseSVN。

在使用SVN进行提交时，为了能够让生成的HTML文档直接显示，请注意设置文件的SVN属性，主要是svn:mime-type和svn:eol-style。对于Linux用户，可以在checkout出的SVN工作目录的根目录中执行以下命令：

find . -name "*.html" | xargs svn ps 'svn:mime-type' 'text/html'
find . -name "*.css" | xargssvn ps 'svn:mime-type' 'text/css'
find . -name "*.js" | xargs svn ps 'svn:mime-type' 'application/x-javascript'
find . -name "*.png" | xargs svn ps 'svn:mime-type' 'image/png'
find . -name "*.jpg" | xargs svn ps 'svn:mime-type' 'image/jpeg'
find . -name "*.gif" | xargs svn ps 'svn:mime-type' 'image/gif'
find . -name "*.rst" | xargs svn ps 'svn:eol-style' 'LF'
find . -name "*.txt" | xargs svn ps 'svn:eol-style' 'LF'

对于Windows用户，可以使用TortoiseSVN为新加入SVN的文件单独设置SVN属性。

方便起见，我在Sphinx自动生成的Makefile中增加了一个伪目标svn-ps，用于自动完成属性设置工作。

Sphinx

Sphinx是一套基于reStructuredText格式的文档编辑系统，相较于LaTeX、DocBook等重量级工具而言非常地轻便好用，对于需要经常撰写技术文档的懒惰程序员而言，是不可多得的利器。

初学者请参考Sphinx 的官方文档和这篇教程。

关于drafts目录

如果你不熟悉Sphinx，而且也没有什么精力去学（真可惜），那么也可以将无格式的译文草稿提交到SVN的drafts目录，我会将之适配到Sphinx下。译文草稿的命名规范为章节名称_译者ID，如chapter-8_liancheng或appendix-a_somebody。

Sphinx译稿格式约定

所有源文件应符合以下约定：

1. 文件名采用英文，章节译稿命名规则为：

   chapter-n.rst
   

   附录译稿的命名规则为：

   appendix-x.rst
   

2. 使用UNIX换行符格式。

3. 字符编码统一为UTF-8 。

4. 对中英文斜体的处理：

   • 原文中对应为斜体的中文文本，在译稿中请使用粗体。原因正如你所见，为手写体原本就右倾的英文设计的斜体并不适合于方正的汉字。为了去除不必要的空格，请使用“\”对加粗文本前后的空格进行转义：

     这是一个\ **粗体**\ 词汇

     其效果为：

     这是一个粗体词汇
     

   • 原文中对应为斜体的英文文本，保留斜体格式。

5. 插图图片约定：

   • 图片格式请保存为PNG格式。
   • 为了保证图片比例，对原文PDF中的插图进行截图时，请将PDF文件的缩放比例调整为100%后进行截图[1]。

脚注