guides.txt

                      VIMCDOC TRANSLATION GUIDE


本文件用来作为一个翻译文档时的指南。包括必须统一的条目以及参考。
任何意见和建议请在 vim-translate mailinglist 讨论。

http://vimcdoc.sf.net
http://vcd.gro.clinux.org

Note:
后者是本项目的中文主页。请在翻译前先确认要翻译的文档没有被翻译过。
以下讨论仅以 sourceforge 为例。


==============================================================================
Sourceforge ~

本项目使用 sourceforge 服务。翻译人员必须有一个 sourceforge-ID。你可以到
http://www.sourceforge.net 申请。并通知项目管理员将你加入 developer list。


==============================================================================
CVS ~

从 2006 年 5 月 15 日起，vimcdoc 转用 Subversion 做版本管理。CVS repository 将
被废弃。

==============================================================================
Subversion ~

vimcdoc 的 Subversion repository 也由 Sourceforge 提供。现在有两个分支：trunk
和 vim6，分别位于：

https://svn.sourceforge.net/svnroot/vimcdoc/trunk
和
https://svn.sourceforge.net/svnroot/vimcdoc/branches/vimcdoc-vim6

trunk 用来更新完善 Vim 7.x 的翻译文档。vim6 分支用来维护 vim 6.x 相关的内容。

关于 svn 的使用，请参阅 sourceforge 文档
http://sourceforge.net/docs/E09, http://sourceforge.net/docs/B01
以及 Subversion 的官方文档
http://svnbook.red-bean.com/

Note 在 svn commit 时，尽量填写有意义的注释，并包括以百分比表示的翻译完成的进度。

==============================================================================
Mailing List ~

http://sourceforge.net/mail/?group_id=56777
项目共有3个mailing lists:
1. vimcdoc@googlegroups.com
   翻译者必须 subscribe 这个 mailing list 以和大家交流，互相帮助，保持一致。
   这个是用来替代 sourceforge 原有的 vimcdoc-translate 的。因为旧的 list 稳定
   性稍差。曾经瘫痪的半月之久。
   http://groups.google.com/group/vimcdoc/subscribe
2. vimcdoc-announce
   发布对外消息。如新版本发行等。
   mailto: vimcdoc-announce-request@lists.sourceforge.net
   subject: subscribe
3. vimcdoc-cvs
   用来自动通知 subversion commit 的状态。
   mailto: vimcdoc-cvscommit-request@lists.sourceforge.net
   subject: subscribe


==============================================================================
Compulsory Rules ~

1. 不能改动原文件的格式！不能改变各文本的颜色！
   请打开语法加亮，并使用
>
   :syntax on
   :set list
   :set listchars=tab:>-,trail:-
<
   命令来显示所有的字符用来帮助排板。
   同时，VIM 在帮助文件中使用了很多标记字符，
   用来帮助语法加亮。
>
   :hi Ignore guifg=color
   :hi Ignore ctermfg=color
<
   可以使它们被显示出来(使用比较醒目的 color)

2. 一些 VIM 的专用术语必须统一。参阅 dict.txt
   中的 Compulsory 区。

3. 在开始翻译一个新的文档前，请 cvs update 你的
   doc 目录，并确认你所要翻译的文档不在其中。
   在确定之后，cvs add && cvs checkin 一个 "完整"
   的英文原文用来通知大家该文档已被 taken。请不要
   commit 一个空文件。( 在决定要翻译哪个文件时，
   请参考 TODO 文件。)

4. 如果你不熟悉 VIM 帮助: 在 | | * * < > 等等
   之间的文本是 vim 用来 hyperlink 的。不用翻译。

5. 各文件之间的衔接: VIM 文档各文件之间互相参阅,
   例如在每个 usr_??.txt 的最后都将给出前后的
   文件主题, 翻译时请参考已经存在的文件, 以确保
   各个文件中的说法一致。

5. 所有文档应当使用 unix 行结束符。
>
   :set ff=unix
<
6. 当在 Vim 文档中出现全大写字母以表示某节的
   开始时，在翻译的中文字之间加入空格。例：
	DELETING VARIABLES
   =>
	删 除 变 量

7. 行宽: Vim 帮助文件有固定的行宽--78，对于英文
   文本，Vim 可以自动排版，可是这对中文文本无效。
   所以，请在翻译时注意手动调整行宽，不要超过78。

8. 编码：所有翻译后的文本使用 UTF-8 编码。
   为保持最大兼容性，请在翻译完文档后，运行以下
   命令确保帮助文档能在 enc=euc-cn 环境下查看。

   $ iconv -f utf-8 -t euc-cn file.txt >/dev/null

9. 翻译日期：每个文档的第一行均有一个 Last Change:
   翻译为 “最近更新” 然后使用译文的更新日期。

10. 标点符号不能出现在行首。对引号一律使用 *英文引号* 。

11. 关于 note, Note 的翻译：视情况而定，可译为“注意”
    或“备注”，之后＿必须＿是英文 ':' 或空格。这样做
    是为了便于 Vim 分割 keyword。

==============================================================================
Recommended Rules ~

1. 译者: 译者可将自己的名字(nickname,etc)置于
   文件中原文作者的名字下面一行。格式为 译者: 
   （英文标点）但建议同时给出本项目网址: 
   http://vimcdoc.sf.net。

2. 这个项目翻译的目标是 Vim 6.3 的文档，如果
   你没有这个版本,请到 Vim 主页下载。注意：非
   Vim 官方发行的 plugin 的文档不再翻译之列。

3. 标点符号：建议在不改变原文的意思前提下"尽量"
   使用中文标点。有些地方的标点有特殊的功能，
   不能翻译为中文。例如 regexp 中的'.'

4. 中英文混和：因为英文本身带有空格，而中文没
   有，建议在混和中英文时加入空格。如同上面
   条目 2 中提到 Vim 的名字时。这样比较清楚。


==============================================================================
Using AAP ~

你可以使用 AAP 来 commit 你的翻译结果。 建议 Vimdoc 翻译的成员使用 AAP。 AAP 
是跨平台的，在 Linux/BSD 和 Windows 平台都可以使用。

1. 以下是 lang2 在 translate mailinglist中发的一份用法。

Download AAP from http://www.a-a-p.org

> In an effort to make my life (an hopefully others)
> easier :-), I've been playing with Bram's new toy - aap
>  for a while. I am now coming to a stage where it can be
>  used to more or less replace those Makefiles.
> 
> I've checked in three file:
> data/common.aap
> data/doc/main.aap
> data/doc/vim2html.pl
> 
> These at this moment only handles automatic updating
> of the HTML version of the translation for both sites
> (wandys have to patch the recipe for cosoft). I've tested
> it with pi_gzip.txt (forgot to mention this) and it
> looks OK so far.
> 
> I'd like to suggest you to install aap (http://www.a-a-p.org)
> and give it a try. It won't hurt you. After the installation,
> the first thing you have to do to use it is to modify the
> common.aap to use your own sf handle. Then goto data/doc and try this:
> - 'aap' will tell you what you can do
> - 'aap <filename.txt>' will check in your change to that file
> and generate HTML version and copy it to the remote server.
> 
> Quite easy isn't it?

2. 在 Windows 平台上要注意的问题。
  (1) AAP 安装完毕后，记得要把 AAP 可执行文件的路径和其下的子目录 bin 加到环境
      变量 PATH 中。在我这里，是这两个目录：

      C:\Program Files\Aap\Exec; C:\Program Files\Aap\Exec\bin

  (2) lang2 编写的脚本里面用到几个命令行软件:tar,gzip, 一般情况下，Windows 用户
      没有这些软件，不过没关系，可以很方便的使用 AAP 下载。直接在 Dos 窗口中执行：

      aap --install tar
      aap --install gzip

      软件自动安装在 AAP 子目录 bin 下面。

  (3) 还有一个软件 NSIS 需要安装。它是用来制作 vim 文档的 Windows 安装程序的。
      它的网址是 http://nsis.sf.net 。记住：安装完毕后，也要把的路径加到环境变
      量 PATH 中，只有这样，脚本才能使用这个软件。
  
  (4) 如果想发布软件，需要输入下面的命令：
      
      aap release
     
      会生成两个软件包，*nix 和 Windows 的安装包

 vim:tw=78:ts=8:ft=help:norl: