develop.cnx

Vim 中文文档

*develop.txt*	 For Vim version 6.2.   最后更改：2002年9月3日
 

		    Vim 参考手册    作者：Bram Moolenaar
	  翻译：jwdu <[e-mail]>, iCrazy <[e-mail]>
			    http://vimcdoc.sf.net


Vim 的开发						*development*

这一节的内容对那些想进一步开发 Vim 的人来说是很重要的。

1. 设计目标		|design-goals|
2. 编程风格		|coding-style|
3. 设计决定		|design-decisions|
4. 假定			|design-assumptions|

请先看一下 "src" 目录下的 README.txt 以便对源代码有一个总体的了解。

==============================================================================
1. 设计目标						*design-goals*

首先说最重要的内容（概略的说一下）。

Note 许多项目是互相冲突的，但这是故意的。对于它们，你必须自己平衡一下。

VIM 是 ... 和 VI 兼 容 的				*design-compatible*

首先，必须使 Vim 能够代替 Vi 。如果用户愿意，他可以在兼容模式下使用 Vim 而且
很难发现它和原先的 Vi 有什么不同。

例外：
- 在 Vim 中不再有明显的 Vi 错误。
- 有很多不同的 Vi 版本。我用 3.7 (6/7/85) 版作为参考。但是如果可能，也会支持
  其它的版本。 POSIX 中的 Vi 部分不是最主要的来源。
- Vim 中有一些新的指令，你不要指望一些命令会失效，因为它们在 Vi 中是不存在的
- Vim 有许多特性是 Vi 所没有的。从 Vim 回到 Vi ，将会出现一些不可避免的问题。
- 有一些指令可能是很少用到（开放模式、在崩溃时发送一封邮件等等）。它们仅仅在
  您的确需要时才会被加入，并且增加这些功能不会增加多少代码量。
- 对一些命令是否仍需兼容 Vi 是一个有争议的问题。对这些，会使用一个选项来作标
  记。


VIM 是 ... 改 进 过 的					*design-improved*

Vim 的改良使它成为一个更好的 Vi，而没有变成一个完全不同的编译器。对它的扩展是
本着 "Vi 精神" 完成的。
- 尽可能多的使用键盘，鼠标需要第三只手来操作，而我们没有第三只手。而且，许多
  终端没有鼠标。
- 当使用鼠标操作时，尽量少回到键盘操作，避免鼠标和键盘的混合操作。
- 用一致的方式增加命令和选项。否则，人们将会很难发现并记住它们。请记住：以后
  会加入更多的命令和选项。
- 一个人们不知道的特性是一个无用的特性。不要添加不明显的特性，或者至少在文档
  中说明它们的存在。
- 尽量少用 CTRL 和其它修饰符，因为它们很难输入。
- 因为对许多人来说，Vim 是他们刚接触或不熟悉的，所以请尽量使 Vim 容易上手。
- 特性是可以无限增加的，对它们的选择基于以下方面：(1) 使用者需要什么 (2) 实现
  它需要多少工作量 (3) 的确有人会去实现它。


VIM 是 ... 跨 平 台 的					*design-multi-platform*

Vim 设法支持尽可能多的平台，从而让尽可能多的人能够使用它。
- 支持多种终端。最小的需求是定位鼠标和清屏。指令最好用多数键盘都具有的那些键
  来执行。 在映射键盘时，支持键盘上所有的键。
- 支持多种平台。必要条件是有人想在此平台上开发 Vim，但这并不意味着会搞糟代码
- 支持多种编译器和库。并不是每个人都能够安装另一个编译器或图形库。
- 人们经常从一个平台转移到另一个平台，从图形界面转移到终端模式。特性应在每个
  版本中都加入，至少应该在尽可能多的版本中出现。尽量避免使用者为了有效的完成
  他们的工作而需要在不同平台间转移。
- 也许有些特性在某些平台上没有，或者只在某个平台上有，但这不意味着它不能被实
  现。[这个和上一个原则明显的冲突了，但我们必须在它们之间做个平衡。]


VIM 是 ... 具 有 详 尽 文 档 的				*design-documented*

- 一个没有文档的特性是一个无用的特性。针对新特性的补丁必须包含它的文档。
- 文档必须全面且容易理解。最好举例说明问题。
- 请使文件尽可能的短，短文档能使得找到它容易一些。

VIM 是 ... 速 度 快、体 积 小 的			*design-speed-size*

Vim 不能是一个大的系统资源使用者，必须使它体积小且速度快。
- 计算机每年都在变得更快、更大。 Vim 也可以同样的变化，但是速度不能超过计算机
  的变化速度。要使 Vim 在老的计算机上也可以使用。
- 许多使用者经常从 shell 启动 Vim 。启用时间必须尽量短。
- 指令必须有效的工作，它们消耗的时间要尽可能的短。有用的指令可以多消耗一点时
  间。
- 注意到许多人在慢速线路上使用 Vim，因此，要使信息的交流尽可能的少。
- 如果一个显著增加 Vim 体积的功能不被大多数人使用，则需要禁止它。
- Vim 只是其它许多组分中的一个，不要不要把它弄成一个笨重的应用程序，倒要使它
  能够和其它程序一起很好的工作。


VIM 是 ... 可 维 护 的					*design-maintain*

- 源代码不应该变成一团糟。它应该是可靠的代码。
- 所有的文件应使用相同的风格，使得它们易读性强。|coding-style|
- 根据需要有效的使用注释！
- 移植到另一个平台应该很容易，而不必改变太多独立于平台的代码。
- 使用面向对象的思想：把数据和代码放在一起，波及到代码其它部分的知识要尽可能
  的少。


VIM 是 ... 灵 活 的					*design-flexible*

Vim 应该让使用它的人很容易在他们喜欢的风格下工作，而不强迫他们使用一个特定的
方式工作。这个对于那些有巨大影响的选项和其他细节都是一样。缺省值是经过认真挑
选的，以便大多数使用者都乐意在默认设置下使用 Vim。用户可以用命令和选项来调整
Vim 来满足他们和环境的需要。


VIM 不 是 ... 						*design-not*

- Vim 不是一个 shell 或操作系统。你不能在 Vim 内运行一个 shell 或使用它控制一
  个调试器。应该使用其它方式工作：把 Vim 当作来自 shell 或 IDE 中的一个部分来
  使用。这里有一个讽刺的说法：“Vim 不像 Emacs 那样会包含除厨房中的水槽以外的
  每件事物，但有人说如果你需要的话，却可以用它来洗盘子。”
- Vim 不是一个为了看起来漂亮就牺牲多平台一致性的怪异的 GUI 编辑器。但我们欢迎
  具有强大功能的 GUI 特性。

==============================================================================
2. 编程风格						*coding-style*

这些改变 Vim 源代码的时候必须遵循的准则。为了保持源代码的可读性和可维护性，
请坚持使用这些原则。

这个列表是不完全的，请查看源代码以获得更多的例子。


修 改 代 码						*style-changes*

修改代码的基本步骤：
1. 首先调整文档，这样做将使你对你的更改如何影响使用者有一个印象。
2. 改变源代码。
3. 检查 ../doc/todo.txt，看看所作的修改是否影响其中的项目。
4. 用 "diff -c" 针对没有改变的代码和文档，做一个补丁。
5. 写一个修改了哪些地方的记录，并把它加到补丁中。


普 通 函 数 的 使 用					*style-functions*

一些普遍使用的函数都有一个特殊的 Vim 版本。因为引入它们是有原因的，因此，一般
应考虑使用这些 Vim 版本。

通用名		VIM 函数名	VIM 版本的不同
free()		vim_free()	检查释放 NULL 的情况
malloc()	alloc()		检查内存不足的情况
malloc()	lalloc()	类似于 alloc()，但是支持长参数
strcpy()	STRCPY()	对于 char_u* 类型的参数，会自动将其转换为
				(char*) 类型
strchr()	vim_strchr()	接受特殊字符
strrchr()	vim_strrchr()	接受特殊字符
isspace()	vim_isspace()	可以处理 ASCII 码 > 128 的字符
iswhite()	vim_iswhite()	仅当 Tab 和 空格 时返回真值
memcpy()	vim_memmove()	处理重叠的拷贝
bcopy()		vim_memmove()	处理重叠的拷贝
memset()	vim_memset()	对所有系统通用


名 称							*style-names*

函数名不能超过31个字符的长度（因为 VMS 的缘故）。

不要使用 "delete" 作为变量名称，C++ 不喜欢这样。

因为 Vim 需要在尽可能多的平台上运行，所以我们需要避免那些已经被系统定义过的名
称。这里是一个已知会造成麻烦的名称列表（使用 regexp 模式给出）。

is.*()		POSIX, ctype.h
to.*()		POSIX, ctype.h

d_.*		POSIX, dirent.h
l_.*		POSIX, fcntl.h
gr_.*		POSIX, grp.h
pw_.*		POSIX, pwd.h
sa_.*		POSIX, signal.h
mem.*		POSIX, string.h
str.*		POSIX, string.h
wcs.*		POSIX, string.h
st_.*		POSIX, stat.h
tms_.*		POSIX, times.h
tm_.*		POSIX, time.h
c_.*		POSIX, termios.h
MAX.*		POSIX, limits.h
__.*		POSIX, system
_[A-Z].*	POSIX, system
E[A-Z0-9]*	POSIX, errno.h

*_t		POSIX, 用于 typedefs。请用 *_T 代替。

wait		不要使用它作为函数的参数，和 types.h 冲突
index		屏蔽全局声明
time		屏蔽全局声明
new		C++ 保留关键字
try		Borland C++ 不希望它作为变量名被使用。

basename()	GNU 串函数
dirname()	GNU 串函数
get_env_value()	Linux 系统函数


VARIOUS							*style-various*

Typedef 的名称应该以 "_t"结尾： >
    typdef int some_t;
Define 的名称应该全部是大写： >
    #define SOME_THING
Feature 应该总是以 "FEAT_"开头： >
    #define FEAT_FOO

不要使用 '\"'，一些编译器不能处理它。用 '"' 比较合适。

不要使用：
    #if HAVE_SOME
一些编译器不能处理它并报告说 "HAVE_SOME" 没有被定义。
请使用
    #ifdef HAVE_SOME
或
    #if defined(HAVE_SOME)


风 格							*style-examples*

一般原则: 每行一条语句。

错误：	    if (cond) a = 1;

正确：	    if (cond)
		a = 1;

错误：	    while (cond);

正确：	    while (cond)
		;

错误：	    do a = 1; while (cond);

正确：	    do
		a = 1;
	    while (cond);


函 数 的 开 始 ：

错误：	int function_name(int arg1, int arg2)

正确：	/*
	 * Explanation of what this function is used for.
	 *
	 * Return value explanation.
	 */
	    int
	function_name(arg1, arg2)
	    int		arg1;		/* short comment about arg1 */
	    int		arg2;		/* short comment about arg2 */
	{
	    int		local;		/* comment about local */

	    local = arg1 * arg2;

NOTE: 不要使用 ANSI 风格的函数声明。一些人仍然在使用不支持它的编译器。


空 格 和 标 点						*style-spaces*

不要在函数名和括号间留空格：

错误：  func (arg);
正确：	func(arg);

请在 if, while, switch 等之后留一个空格：

错误：	if(arg)		for(;;)
正确：	if (arg)	for (;;)

在逗号和分号后留一个空格：

错误：  func(arg1,arg2);	for (i = 0;i < 2;++i)
正确：	func(arg1, arg2);	for (i = 0; i < 2; ++i)

在 '=', '+', '/' 等的前后各留一个空格：

错误：	var=a*5;
正确：	var = a * 5;

概括：使用空行来把代码分组。在每组代码的上面写上注释，这样就可以快速的知道这
些代码是用来干什么的。

正确：	/* Prepare for building the table. */
	get_first_item();
	table_idx = 0;

	/* Build the table */
	while (has_item())
	    table[table_idx++] = next_item();

	/* Finish up. */
	cleanup_items();
	generate_hash(table);

==============================================================================
3. 设计决定						*design-decisions*

折叠

对同一个缓冲可以有多种折叠形式。例如，一个窗口显示函数体折叠后的文本，另一个
窗口显示函数体。

折叠是一种显示文本的方式。它会改变文本自身。所以折叠是被当作缓冲文本（缓冲行
）和窗口内显示的文本（逻辑行）之间的过滤器来实现的。


为窗口命名

我们一般用单词 "窗口" 来称呼很多东西：屏幕上的一个窗口、xterm 窗口、Vim 中一
个用来查看缓冲内容的窗口。
为避免混淆，我们给其他有时被称作窗口的项目起了其他的名称。这些是相关项目的概
述：

screen		整个屏幕。对于 GUI 来说，就是类似于 1024x768 的像素。Vim
		shell可以使用整个屏幕（例如，在命令行下面运行时）或它的一部分
		（xterm 或 GUI）。
shell		Vim 这个应用程序。这个可以覆盖整个屏幕（例如，在命令行下面运
		行时）或它的一部分（xterm 或 GUI）。
window		用来查看缓冲内容的地方。Vim 中可以包括很多窗口，还有命令行、
		菜单栏、工具栏等。它们被整合到 shell 当中了。


待续...

==============================================================================
4. 假定							*design-assumptions*

变量的大小:
char	    8位有符号数
char_u	    8位无符号数
int	    16/32/64位有符号数
unsigned    16/32/64位无符号数
long	    32或64位有符号数，可具有指针

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