自由软件发布方法惯例

自由软件发布方法惯例

Eric Steven Raymond

Thyrsus Enterprises

esr@thyrsus.com

版本号：3.0

版权所有@2000 Eric S. Raymond

翻译：[AKA] rover

$日期：2000年8月21日 18：29：23 $

本文档的修订历史

3.0修订版 2000年8月12日 修订人：esr

第一个DocBook版。SourceForge上的建议和一个主要章节被加入本文档。

本文档详细说明了如何发布一个Linux系统下的自由软件项目。依据这些说明，你就可以让用户非常容易的编译并使用你的代码，同时也可以让其他热心的开发人员很容易读懂你的代码并参与到你的项目中来，并优化、改进她。

本文档对与开发者来说应该算是是一本必读教材。即使是有经验的程序员在发布他们的软件时也需要温习一下本文档。另外本文档会定期修订以反映软件发布实践中更好的做法。

目录

1. 简介

1.1. 本文档的来由

1.2. 如何获得本说明更新的版本

2. 优秀项目--档案--的命名惯例

2.1. 用GNU风格的命名习惯，档案名加主版本号.辅版本号.补丁编号

2.2. 有时候也还要尊重一些在局部范围内流行的惯例

2.3. 尽量找一个独一无二并且又很容易输入的项目名称（前缀）

3. 选择一个好的许可证和版权说明（从理论上探讨）

3.1. 开源与版权

3.2. 怎样才有资格被称为开源软件

4. 选择好的许可证和版权（实践篇）

4.1. 让你自己或者自由软件基金会成为软件的版权所有者

4.2. 采用遵照开源定义的许可证

4.3. 如果没有特别的需要，最好不要自搞一套许可证

5. 好的开发习惯

5.1. 写标准ANSI C程序或者可移植的脚本程序

5.2. 遵守C程序的可移植惯例

5.3. 使用autoconf/automake/autoheader工具

5.4. 发布前要仔细的检查代码

5.5. 发布前要仔细的检查文档和Readmes文件

6. 制作项目发布包的好经验

6.1. 确保tar包解压时会建一个独立的新目录

6.2. 制作一个README文件

6.3. 遵照标准文件命名规则

6.4. 为项目升级做好准备

6.5. 提供RPM包

7. 好的文档编写惯例

7.1. 现行的一些好的做法

7.2. 也许未来会有些更好的做法

8. 好的沟通方式

8.1. 在c.o.l.a和Freshmeat上公布

8.2. 在相关主题新闻组中公布

1. 简介

1.1. 本文档的来由

历史上已经有大量的发布开放源码项目的好传统存在，这些惯例使得人们可以更为方便的移植、使用或者直接加入项目的开发。许多这些传统都来源于原来的UNIX世界和早期的Linux社区中；还有一些则是最近随着新开发工具和技术的出现（如WWW）才应运而生的。

本文档就是帮助你学习这些惯例的。我们将分主题讲述所有要点。一个好的自由软件开发者应该在发布他的软件之前把这些要点都捋一遍才好。

1.2. 如何获得本说明更新的版本

本文将每隔一个月在 comp.os.linux.answers 新闻组中更新一次。你还可以从互联网上获得这份HOWTO文档的最新版本，具体地址(URL)是： http://www.linuxdoc.org/LDP/HOWTO/Software-Release-Practice.html。

如果你对本文档有什么建议和问题，请尽管给Eric S. Raymond写Email，地址是：。

2. 优秀项目 -- 档案 -- 的命名惯例

由于档案维护者的工作量不断增大，许多站点如：Metalab, PSA 和 CPAN 都存在这种情况。因此趋势是许多工作将会由程序来自动完成，而不是全部由人手工去做。

这种情况就使得项目和文档名称规范化工作变得越来越重要，规范的命名可以让程序更容易的识别和获得文档所包含的信息。

2.1. 用GNU风格的命名习惯，档案名加主版本号.辅版本号.补丁编号

让档案名称符合GNU命名规则是一个与人与己都有好处的事情，GNU的命名规则是：以所有字母都小写的主名称作为前缀，后跟一个破折号，再跟一个版本号，扩展说明，以及其他后缀。

我们举例说明如下：假定你有一个项目叫做“foobar”，现在他的进展状况是 第一版、第二次发布、第三级。如果她只有一个档案包（可能就是所有的源码）， ~~~~~~~~~~~~~~~~~~~~~~~~~一般把这里的level叫做什么？ 那么她的名称应该是：foobar-1.2.3.tar.gz

源代码档案 foobar.lsm

LSM文件名 （如果你需要将这个项目提交到Metalab上，则需要这个LSM文件）

千万不要把名字起成下面的样子：foobar123.tar.gz （这会让人误解为是一个名为“foobar123”的项目）

foobar1.2.3.tar.gz （这会让人误解为是一个名为“foobar1”项目的第2.3版）

foobar-v1.2.3.tar.gz （许多处理程序将会把她理解为名为“foobar-v1”的项目）

foo_bar-1.2.3.tar.gz （下划线读起来即不上口，也不容易让别人输入和记住）

FooBar-1.2.3.tar.gz （除非这个项目是面向市场运作的，最好不要大小写混用， ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~`marketing weenie是什么意思？ 因为这种写法同样不易读、输入和记忆）Unless you like looking like a marketing weenie. This is also hard for people to speak, type, and remember.

如果你想对源代码包和二进制包有所区别，或者想区分不同类型的二进制包、由不同编译选项编译出来的二进制包，请在文件名的“扩展说明”部分来表示那些信息，扩展说明紧跟在版本号之后。也就是说你可以这样起名字：

foobar-1.2.3.src.tar.gz 表示源代码包

foobar-1.2.3.bin.tar.gz 表示二进制包

foobar-1.2.3.bin.ELF.tar.gz 表示ELF格式的二进制包

foobar-1.2.3.bin.ELF.static.tar.gz 表示静态链接库的ELF格式二进制包

foobar-1.2.3.bin.SPARC.tar.gz 表示SPACE格式的二进制包

千万不要使用“foobar-ELF-1.2.3.tar.gz”格式的名称，因为处理程序对“-ELF” 这样的中缀将难以解释。

一个好的名称将按顺序包含下面这些项：

项目名称 前缀 破折号 版本号 点

“src”或“bin”标记（可选）点或者破折号（建议使用点）二进制格式和选项（可选）

归档和压缩后缀

2.2. 有时候也还要尊重一些在局部范围内流行的惯例

在有些个别项目或社区中还存在着与上面命名规则并不完全一致的，同时又是定义的非常好的他们自己的命名规则。比如Apache的模块通常就采用“mod_foo”那样的命名方式，而且模块名中还会既包含模块的版本号又包含模块可工作的Apache的版本号。同样，Perl模块在版本号中还有形如浮点数那样的表示方式（如1.303，而不是 1.3.3），所以Perl 1.303版的模块Foo:Bar的发行包一般会被命名为Foo-Bar-1.303.tar.gz。（顺便说一句，Perl项目本身在1999年末已经采用了本文前面所介绍的GNU标准命名方法）

一方面我们要寻找并尊重那些特殊社区和开发者的特殊命名习惯；同时对于大部分其他的项目，我们建议大家按照标准的命名规则来工作。

2.3. 尽量找一个独一无二并且又很容易输入的项目名称（前缀）

项目的主名称应该可以被整个项目中的其他文件通用，同时最好她既好读又好写 （输入），还容易让人记住。所以建议你在没有充足理由的时候最好不要用下划线，不要使用大写字母或有的字母大写。那些垃圾字符会污染人类视觉的阅读习惯，干扰人们的搜索顺序，当然那么做对于一个商业发行版本命名可能是一个好主意。 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~`而且看起来有点象小市民在耍小聪明。

当两个不同的项目有同样的主名称的时候就会产生混淆。所以最好在你第一次发 布你的项目的时候就能避免这种冲突。有两个网站上的名称统计列表可以帮助你 检查是否冲突，他们是 Metalab(http://www.ibiblio.org/pub/Linux)和 Freshmeat(http://www.freshmeat.net)，另外还有一个好地方是：SourceForge (http://www.sourceforge.net)，在这些地方你可以做一点名称检查的工作。

3. 选择一个好的许可证和版权说明（从理论上探讨）

许可证的选择实际上是为你自己选择一个你与其他开发者以及用户之间的社会契约。给软件附加版权说明实际上是使得给你创作的软件和其衍生产品加上许可证的行为合法化。

3.1. Open source and copyrights

任何非公共的东西几乎都有版权，有的甚至还有不止一个版权。根据伯尔尼公约（1978年成为了联邦的法律），版权并不必显式地声明。也就是说，即使没有给出版权声明，一部作品的作者仍然是持有版权。

如何确定谁是某个东西的版权所有者是非常困难的，特别是在软件行业，因为有时候软件是许多人共同编写出来的。这也就是为甚么许可证在软件发布中非常重要的原因。通过设定一些指出在何种情况下可以使用的条款，许可证授予用户权利并保证用户免受版权所有者各种行为对他们造成的伤害。

在私有软件领域，许可证条款总是被设计成保护版权所有者。这是一种只给用户少得可怜的权利的做法，然而这种做法却保留尽可能多的合法权利给版权所有者。版权所有人非常关键，而且许可证的逻辑是如此严密以至于那些条款中的技术上精确已经都不重要了。

相反，开源软件领域，则是另一番景象；在这里版权是用来保护许可证的。版权所有者唯一的权利就是确保许可证的落实。如果不这样的话，将只有很少的权利得到保留而让用户面临更多的取舍。特别是版权所有者自己也不能对你已经拥有的副本更改任何许可证条款。因此，在开源软件领域，版权所有者的作用要小的多而许可证条款显得更为重要。

通常一个项目的版权所有者就是该项目的首席开发人员或发起组织。项目的首席开发员易人一般就意味着版权所有者发生了变化。不过这并不是一个严格的规则，许多自由软件项目有着多个版权所有人，这种领导模式至今还没有出现任何法律问题。

许多项目选择让自由软件基金会作为版权所有者，理论上来说这样更有利于开源软件受到保护并让专业的律师来处理各种法律问题。

3.2. 怎样才有资格被称为开源软件

根据许可的目的，我们可以区别许可证赋予你的各种不同权利。复制和再发布的权利，使用的权利，为个人目的修改的权利，发布修改后的作品的权利。一个许可证可能会对这些权利加上一些限制或给出一些附加条件。

开源原动力站点（http://www.opensource.org）就是各种对软件“开源”或“自由”思考的结果。该站点许可证的约束条款包括：无限制的拷贝权

无限制的使用权

无限制的针对个人使用目的而修改的权利

这些指导方针保证修改后的二进制代码的再发布权；这与那些要求可以无障碍的取用软件的发行商的需求相吻合。这个做法使得软件的作者们可以要求修改的原始源代码采取把原有代码加上补丁程序的方式来再发布，这样就保全了作者们的原意同时又可以让他们“审查”其他人对项目的改进工作。

OSD（开放源代码定义）是对“OSI开源软件认证”证书的法律定义，实际上她和人们曾经提出的各种关于“自由软件”的定义一样好。所有标准的许可证协议（如MIT、BSD、Artistic、GPL和LGPL协议）都与该提法一致（然而有时候，比如GPL，有更多的限制条款，在选择这些许可证时请仔细理解）。

值得注意的是有些只允许非商业用途的许可证并没有资格被成为开源许可证，尽管他们标榜自己是“GPL”或者其他典型的许可证。这种许可证对特殊的拥有者，或者对个人和小组有着歧视。他们对通过光盘渠道再发布的做法以及其他商业化的推广开源软件的尝试做出种种限制，从而把事情搞的非常复杂。

4. 选择好的许可证和版权（实践篇）

本节将告诉你如何将上节介绍的原理转化为实际的行动：

4.1. 让你自己或者自由软件基金会成为软件的版权所有者

有些情况下，如果你和你的项目背后有一个有法律专家的组织支持，你可能更 愿意将版权授予那个组织。

4.2. 采用遵照开源定义的许可证

开源软件的定义（OSD）是许可证的公共标准。OSD本身并不是一个许可证；而 是给出了某个许可证要想成为开源许可证所必须包含的一个最小集合。OSD和其 他辅助资源可以从开源原动力站点（http://www.opensource.org）获得。

4.3. 如果没有特别的需要，最好不要自搞一套许可证

广为人知的OSD规范许可证有着相对固定的解释惯例。开发人员（甚至用户）已经了解这些许可证的真正内涵，合理的协调了各种风险和所需的代价。因此，在各种的情况下最好采用开源原动力站点上的某一许可证即可。

如果你非要制作你自己的许可证协议，最好将这个许可证提交给开源原动力站点，让他们帮你把把关。这样可以省去日后不少争论和其他开销。如果没有认真考虑过，你很难想象一个在许可证方面发生的争吵所带来的后果是多么糟糕，由于许可证这种神圣盟约是开源软件价值体系中的核心问题，人们多半会在这个问题上反目为仇。

此外，如果某个许可证已经在法庭上经过了考验，将证实这个许可证所建立的解释惯例是重要和合适的。不过截至本文编撰的时候（2000年中期），还没有任何开源许可证有着被支持或者被驳倒地法律案例。一般法庭应该会根据制定许可证的发起组织的期望和实践来解释那些许可证和契约，这几乎是一定的（至少在美国以及其他有着类似法律的英联邦国家是这样）。

5. 制作项目发布包的好经验

本章节主要内容侧重于确保程序的可移植性，这不仅限于各种Linux系统，而且也针对各种UNIX系统。对其他UNIX系统保持可移植性并非是故意卖弄技术或者是遵守黑客的礼节，而是一种保持未来Linux自身发展不分裂的保障手段。

另外，如果其他人试图将你的项目移植到其他非Linux系统上，一个可移植性好的项目可以让你最大限度的避开各种烦人的Email质询。

5.1. 写标准ANSI C程序或者可移植的脚本程序

要有可移植性和稳定性，你最好只用ANSI C写程序，要不就用某种教本语言，这样能够保持可移植性的原因是他们底层的实现对于不同平台是一致的。

有资格被成为跨平台的脚本语言包括 Python、Perl、Tcl、Emacs Lisp 和 PHP。普通的老式Shell则不具有好的可移植性；因为他们在不同平台上的实现有许多细微的语法差别，而且Shell的外壳环境极易受到用户个性化设置（如alias设置）的干扰。

Java总是声称自己是跨平台的语言，但是Java在Linux上的实现还非常少而且与Linux系统的集成度还比较差。虽然Java以后成熟了将会变得非常流行，不过时下还是不要选她的好。

5.2. 遵守C程序的可移植惯例

如果你用C写程序，请记住一定要完全遵从ANSI标准----包括函数原型，这样可以帮助你去掉跨平台模块的不一致性。老的K&R编译器已经成为了历史。

另外，不要认为一些GCC特有的特征，比如“-pipe”编译选项以及嵌套函数等，在所有平台上都有效。因为这样的选项会在其他人试图将项目移植到非Linux、非GCC系统上时起作用并被“咬”一口。

5.3. 使用autoconf/automake/autoheader工具

如果用C写程序，记住一定要用autoconf/automake/autoheader工具来处理各种移植性的问题，用这些工具完成系统配置信息的收集，制作makefile文件。现在许多人在打算编译源码时只希望通过“configure; make”这样简单的命令就可以得到干净利落的编译，事实上大家就是这么干的。

5.4. 发布前要仔细的检查代码

用C写程序，至少在每次发布之前要记得用 -Wall 编译选项重新编译一遍并去除编译中遇到的任何错误。这么做可以帮助你发现不少没有想到的错误。要是想更彻底的检查，那就用 -pedantic 选项再编译一遍。

如果是写Perl程序，可以用 perl -c 命令（或者 -T 选项）来检查代码中的错误。使用 perl -w 和“use strict”来做更严格的检查（请阅读Perl的文档获取更多的信息）。

5.5. 发布前要仔细的检查文档和Readmes文件

文档发布前最好用拼写检查工具查一遍。如果你看起来没有能力拼写正确，而且也不关心文档的错字、错词，那么其他人很自然的联想到你的代码是否也同样是乱七八糟和粗心大意呢？

6. 制作项目发布包的好经验

这一章节主要介绍你发布的项目应该具有什么样的形式，以方便其他人下载、检索和解压。

6.1. 确保tar包解压时会建一个独立的新目录

新手常犯的低级错误是制作了一个解压后把文件和目录直接解压在当前工作目录的tar包，这样做潜在地危险是会把原来已有的同名文件覆盖掉。千万记住，不要这么干。

正确的方法是，你的项目的所有档案都是存放在项目所在目录下的标准目录结构中，这样tar包就可以解压在一个特定的目录下而不是当前目录。

这里有一个Makefile文件的技巧示例展示了如何完成打包工作，这里假定你的项目所在目录名称为“foobar”，而SRC变量中是一个包含所有需要发布的文件列表：foobar-$(VERS).tar.gz:

@ls $(SRC) | sed s:^:foobar-$(VERS)/: >MANIFEST

@(cd ..; ln -s foobar foobar-$(VERS))

(cd ..; tar -czvf foobar/foobar-$(VERS).tar.gz `cat foobar/MANIFEST`)

@(cd ..; rm foobar-$(VERS))

6.2. 制作一个README文件

应该有一个名为README或者READ.ME的文件来说明整个源码的结构信息。古老的传统告诉我们，勇猛的探索者在解开你的压缩文件包后的第一件事情就是找出README文件来阅读。

README文件中最好应该包括如下信息：

整个项目的简介

项目的WWW站点所在的URL（如果有的话）

指出开发者编译整个项目所在的系统环境，并指出项目可能潜在地移植性问题

重要文件和子目录的结构信息

编译/安装步骤说明，或者指明这些信息所在的文件名（通常是INSTALL文件）

项目主持人和参与者的名单列表，或者指出这些信息所在的文件（通常是CREDITS文件）

最近关于本项目的一些进展情况和新闻，或者指出包含此信息的文件（通常是NEWS文件）

6.3. 遵照标准文件命名规则

“勇猛的探索者”要想阅读README文件，他们就必须首先浏览解压后项目档案所在的根目录下的文件名。这些文件名本身就在向读者传达许多信息。如果你遵照标准的命名规则就可以给那些探索者有价值得线索以便他们更好的理解你的意图。

这里列出了一些标准文件名称和他们的涵义。当然并不是所有项目发布时都必须包含所有这些文件。

README 或 READ.ME

整个项目的结构信息说明，第一个需要阅读的文件

INSTALL

配置、编译和安装该项目的说明信息

CREDITS

本项目所有贡献者的列表

NEWS

本项目最近的一些新闻和进展

HISTORY

本项目的历史发展演变记录

COPYING

指出本项目采用的许可证条款（通常采用GNU）

LICENSE

本项目的许可证条款文件

MANIFEST

本项目的所有文件列表

FAQ

关于本项目的纯文本格式的常见问题解答

TAGS

为Emacs或vi准备的标记文件

我们可以看出来，全部大写的文件名一般表示该文件是给人阅读的文档，而不是项目的一个组成部分。

编撰一个FAQ文件可以帮你很多忙。如果某个问题经常被其他人问起，就把这个问题列入FAQ文件；然后指导用户在向你发文或提交出错报告前首先阅读FAQ文件。一份好的FAQ文件可以给项目维护者减轻好几个数量级的负担。

另外在每次发布时都保留一个HISTORY文件和NEWS文件，并列明时间信息非常有好处。在所有其他文件中，这两个文件可以让你在遇到一些专利侵权法律问题时有所准备（虽然这种情况至今还没有发生过，不过最好还是有备无患）。

6.4. 为项目升级做好准备

只要你打算为你的项目发布新版本，项目就必定处在不断的变化之中。有些变化是不能向前兼容的。因此你必须认真思考安装程序设计上的问题，就是说让同一项目的不同版本的代码安装后可以共存在一个系统中。这个问题对库项目的发布尤为重要，因为你不能指望所有基于这个库的应用程序都会紧跟你的API接口规范的后尘。

Emacs、Python和Qt项目有一套对付这个问题的好办法，就是让目录名中包含版本号。这里有Qt库安装后的目录结构的例子（${ver}是代表版本号的变量）：

/usr/lib/qt

/usr/lib/qt-${ver}

/usr/lib/qt-${ver}/bin # Where you find moc

/usr/lib/qt-${ver}/lib # Where you find .so

/usr/lib/qt-${ver}/include # Where you find header files

这样组织目录结构可以让多个不同版本的档案共存。客户的程序可以根据需要选用具有特定版本号的库，因此为了不让这些接口影响客户程序，还是需要付出一些小小代价（制定版本号）的。

6.5. 提供RPM包

安装可执行文件包（二进制包）的事实标准就是使用RedHat包管理器将可执行文件打包成 rpm 包。许多流行的Linux发行版都是这么做的，同时也有许多发行版虽然主要不是rpm包格式但是也支持rpm包（除了Debian和Slackware以外，而且Debian还支持rpm的安装）。

因此一个好的项目除了有tar包的源代码以外，最好也提供直接可安装的rpm包的下载。

如果你能把你的源代码tar包和Makefile文件中用于生成rpm包的相关信息写入rpm的spec文件中就再好不过了。spec文件是有着\".spec\"后缀的文件，这就是带 -t 选项的 rpm 命令如何在 tar 包中寻找它的方法。

还有一个要点是，你可以用一个脚本程序自动的从Makefile或version.h文件中找出版本号，并用这个版本号来生成你的spec文件。

注：如果你还打算提供源码的rpm包，最好用BuildRoot工具来将程序编译到/tmp或者/var/tmp目录中。如果不这么做，在安装过程中执行 make install 命令时就会直接将那些源程序直接安装到最终的目录位置下。这样就会导致即使在发生文件覆盖冲突，或者你本意并不想装那个包的时候，安装动作依然被执行。因此安装完成后，文件是被装到了系统中，但是系统的RPM数据库却并没有记录这些信息。这种愚蠢的SRPM安装动作是非常危险的，理应避免。

7. 好的文档编写惯例

最重要的文档编写惯例就是多写一些！很多程序员都轻视这些事情。但是下面两个理由可以让你明白你必须去做文档工作：

文档可以指导你的设计。写文档的最佳时机在你一行代码还没有编写就应该开始，此时你需要想想你打算做点什么。你会发现用自然语言思考程序应该完成什么功能可以促使你从更高的层次考虑软件是什么样以及她该如何工作。这个思考可以节省许多以后的时间。

文档是代码的招牌。许多程序员为他们的程序只提供了少的可怜、内容匮乏、语言差劲的蹩脚文档，这实际上等于向其他人展示说，写这个文档的程序员对潜在用户的需求也同样会粗心大意、马马虎虎。相反，好的文档则会向其他人传达出文档背后的程序员是非常聪明、专业的人。如果有一些类似的项目正在与你的竞争，一定要写出好的文档来，至少不能让潜在用户瞥了两眼你的文档后就立即否定你的项目。

这份文档虽然着眼于文档编写实践，但并不是一份专门介绍如何写出好文档的详细讲义。因此下面我们将重点介绍文档格式和编写工具的选取。

虽然开源社区长期的传统就是拥有强大的文档格式化工具，但是为数众多的文档格式仍然使得整个系统的文档支离破碎，很难用一种统一的方法全局检索和阅读文档。下面我们将先介绍各种流行的文档格式的用途以及他们的优劣，然后再给出一些编写好文档的建议。

7.1. 现行的一些好的做法

这里将列出一些在开源软件开发群体中流行的一些文档格式。当我们文中提到“展示”标记，就是指那些控制文档显示的标记（如字体）。当我们提到“结构”标记，就是指那些描述文档结构的标记（如段落、强调标记）。当我们提到“线索化”，则是指从众多文档中萃取出可检索的关键字集合的过程，“线索化”可以帮助用户在整个文档中可靠的找出自己感兴趣的 资料。

man 手册页

这是最普通的文档格式，来源于UNIX系统，是一种原始的“展示”标记格式。man(1)命令提供了页显示和原始的搜索手段。这种格式不支持图象、超链接和“线索化”功能。不过这种格式转化成Postscript进行打印的效果还不错，就是转成 HTML格式不太方便（主要是纯文本）。man 的相关工具在各个Linux系统中几乎都有。

手册页格式做为命令用法解释或者短小的参考文档还是不错的，对一个有经验的用户这样做可以非常节省内存。那些有着复杂用户界面和很多选项的程序会让系统负载非常重，如果交叉链接太多的文档甚至会让整个系统不堪重负。（Man手册格式没有支持超级链接）

HTML 文档

自从1993－1994年互联网流行起来后，HTML标记格式开始流行，这种标记格式有一定的结构，也便于 “展示”，还可通过网络浏览器浏览，对图象和超级链接也有支持。不过自带的“线索化”功能很有限，因此搜索引擎技术得到了大力的发展。这种格式也可以很好的被打印出来，相关的制作工具数不胜数。

HTML标记非常灵活，非常适用于各种文档。实际上她太“灵活”了，甚至可以展示Man手册页格式的信息。不过问题在于她很难自动检索，因为这种格式中太多的标记被用于描述“展示”信息，而鲜有标记描述文档的结构。

Texinfo 信息

Texinfo格式是自由软件基金会推荐使用的格式。她是在强大的Tex格式引擎上建立的一套宏。拥有许多结构信息和部分表示信息。可以用Emacs浏览，或者用专门的info程序阅读。这个格式支持超级链接，但是不支持图象；无论是打印出来还是在线阅读都可以很好的“线索化”；如果你装了某个Texinfo格式的文档，该文档的信息就被整合到系统的全局目录表中。这种格式还可以很好的被转换为 Postscript格式和HTML格式，相关工具在大多数Linux系统中都是预先安装好的，当然你也可以从自由软件基金会的网站上下载(http: //www.gnu.org)。

Texinfo有着很好的设计，非常适合于完全字符编排的书籍和小的在线文档，但是和HTML格式一样，她也是一种两栖格式----既有表示“结构”的标记，又有表示“展示”的标记，“展示”标记给文档进一步处理带来了一些麻烦。

DocBook 格式

DocBook是一种强大且精巧的基于SGML（当前XML的前身）的标记格式。和前面几种文档结构不同，这个标记格式只包含“结构”信息，而没有“展示”信息。她可以很好的支持图片和超级链接；支持“线索化”；很易于转换成HTML格式和便于打印的 Postscript格式（而且随着工具功能的增强，打印效果还可进一步提高）。该格式的文档和相关工具可以从DocBook的网站下载(http: //www.docbook.org)。

DocBook在处理大而复杂的文档中表现出众；她被特意设计成可以支持各种技术文档并可以将他们用不同的输出格式“展示”出来。不过她的回溯功能非常复杂，工具也没有完全发展成熟（虽然进步很快），入门级的文档非常少而且常常写得很混乱。

7.2. 也许未来会有些更好的做法

2000年7月，世界一些重要的开放源码项目开发组（包括GNOME、KDE、自由软件基金会、Linux文档项目组、开源首创）在加州Monterey举行了高级首脑会议。该次会议的重要议题就是试图建立一套共同的工作惯例和共同的文档交流格式，以便为自由软件制作出更丰富、更统一的文档资源。

具体的来说，会议的目标就是要制定一种文档包的标准，使得当某文档被装入系统中后，文档包就立即被集成到整个系统的搜索数据库中，系统可以通过某种一致的手段查找、搜索各种文档。实际上GNOME和KDE组已经开始在朝这个方向努力了，大家都明白这并非是一种标记语言就可以解决的问题，而需要建立一套结构化的系统体系。

会议签署了一个意向文件，清晰的指出一些关键的开源项目正在着手或者已经采纳使用Docbook格式做为项目文档的首选格式。

与会者最后也决定了采用“Dublin core”元数据格式（一种根据库管理程序开发的与数字资料索引有关地国际标准）做为文档搜索的标准，这个标准的细节正在制定中，因此最终DocBook标记中会添加一些信息用于支持嵌入DocBook文档的Dublin Core元数据。

目标是明确的，基于索引标记和Dublin core元数据可以提高DocBook文档的自动搜索能力，从而使得DocBook的用途如虎添翼。虽然还有一些工作尚未完成，但是它们将会被不断填充进整个体系中。老的基于描述的标记语言文档所剩下的日子已经不多了。（本文档在2000年8月已经有了DocBook格式的版本）

因此新的开源项目应该注意这种动向，如果现在就采用DocBook格式的文档编写，这可以帮助他们省去以后将文档格式转档的麻烦。

8. 好的沟通方式

如果除了你自己之外没有人知道你辛苦开发出来的程序的话，就不会对这个世界带来太大的用途处。因此，在互联网上充分的展示你的项目可以帮助你获得用户的支持，还可以找到志同道合的开发人员的参与。下面是一些常用的与其他人沟通的做法。

8.1. 在c.o.l.a和Freshmeat上公布

在comp.os.linux.announce新闻组对你的项目发布公告。这个新闻组除了有大量的阅读群外，她也是许多其它站点，比如Freshmeat，公布新消息的地方。

8.2. 在相关主题新闻组中公布

在USENET中找到一个与你项目密切相关的讨论组，并在那里发布你的项目也是一个极好的方式。需要注意的是只能在与你项目相关的地方公布，并且不要灌水。

比如，当你用Perl写了一个查询IMAP服务器的程序，你可以在comp.mail.imap 新闻组公布。但如果这个程序并非是一个反映Perl最新技术的例子的话，就没有必要把这个消息公布在comp.lang.perl新闻组上了。

另外，你的帖子中应该包含你的项目网站所在的URL地址。

8.3. 建一个与项目相关的网站

如果你想围绕项目建立一个用户、开发者的网上社区的话，最好应该建一个网站。一个标准的项目网站一般包括如下内容：

项目的特点（为何要有这个项目，谁会对此项目感兴趣）

下载项目源代码的地方

指明如何加入项目相关的一个或多个邮件列表

一个常见问题解答

HTML格式的项目文档

与项目相关或媲美的其他项目或网站的链接

有的项目站点甚至还有指向源码结构树的匿名访问链接（便于跟踪项目进展）。

8.4. 维护一个项目相关邮件列表

维护一个项目开发专用的邮件列表几乎是必须的，透过这个邮件列表项目的合作开发者可以互相交流并讨论对程序补丁的建议。你最好再建立一个让其他人及时获知项目进展状况的公告邮件列表。

比如你的项目名称为“foo”，那么开发邮件列表就可以命名为 foo-dev 或者 foo-friends，公告邮件列表就可以命名为 foo-announce。

8.5. 在各大主要项目库站点中发布

在过去的几年中，Metalab(http://www.metalab.unc.edu/pub/Linux)成为 了Linux各种软件集散的最重要的站点。For the last several years, the Metalab archive has been the most important interchange location for Linux software.

SourceForge (http://www.sourceforge.net)从他1999年夏建立依赖也获得了爆炸性的发展。这个站点并非只是一个简单的资料与发行版的汇集之处，虽然很多人都认为就是那样。这个站点更是一个为自由软件项目提供一整套开发环境的虚拟主机，包括针对项目提供硬盘空间、网络访问服务、邮件列表服务、错误跟踪、聊天室、CVS管理等各种服务。

还有其他一些重要的网站是：

Python站点(http://www.python.org)（针对所有用Python写的程序）

CPAN(http://www.perl.com/CPAN)，综合Perl资料网。（针对所有用 Perl写的程序）


作者：Eric Raymond 来源：不详