| 修订历史 | ||
|---|---|---|
| 修订 0.1 | 2006/04/10 | 蒋鑫 |
| 创建。 | ||
摘要
IT 技术文档，几乎都源自英文。中文技术文档也多源自于翻译。可以预见两种可能，一、中文文献始终滞后于英文文献；二、干脆不再翻译，缴械投降，中文进一步被弱化。
Whodo 项目的宗旨是中文用户自己的开放文档计划。随着越来越多华人开发者对开源项目的参与甚至是华人主导的开源项目，华人开发者不应该沦为英译汉的配角，用我们自己的文字，书写我们署名的传世之作！
（版本号: 0.3.F-66.84，最后更新时间: 2008-09-11 00:59:11）
目录
Whodo 不是 Solaris 上的 whodo 命令，而是一个中文开放文档计划。
Whodo 是“WorldHello Open Document Origin ”，即 “WorldHello 开放文档之源” 的缩写。是使用 Freemind + DocBook + Wiki + SVN 进行技术文档撰写的开放平台，这里的所有文档遵从 GPL，人人皆可提交更改。
很多人都知道大名鼎鼎的 TLDP。就像 TLDP 项目采用 DocBook 作为协同著作的文本格式，Whodo 项目除了采用 DocBook 格式之外，还使用 FreeMind 的文档格式。即：Whodo = Freemind + DocBook + Wiki + Subversion.
-
Freemind + DocBook
含义是 Whodo 接受的源文档的格式为 Freemind 的 .mm 格式以及 DocBook 的 .xml 格式文档。
-
Wiki
Whodo 使用 Wiki 来作为系统的首页，还用来构建文档的索引、链接、和文档的归类，便于搜索引擎的检索。
-
Subversion （简称 SVN）
Subversion 版本控制系统，是 Whodo 数据交换的中心，是帮助实现协同著作的平台。
-
FreeMind Only
只维护 FreeMind 格式的文档；
-
DocBook Only
只维护 DocBook XML 格式的文档；
-
FreeMind + DocBook
FreeMind 和 DocBook 互为补充，FreeMind 作纲梳理结构，DocBook 完善内容和多种格式输出；
可以让不习惯 DocBook 的用户，和只用 DocBook 的用户，同样参与到文档撰写中来；
-
主控文档： FreeMind, DocBook, Wiki 其中一种格式的文档作为主控文档，其他文档的内容随主控文档更新。
要能够在版本号中体现出主控文档。我们要求在版本号中插入一个主控文档的代号。FreeMind/DocBook/Wiki 的代号分别为 F/D/W。
版本号格式为： <主版本号>.<副版本号>.<主控文档标志>-<主控文档修订号>.<本文档修订号>
Whodo 是 “北京群英汇信息技术有限公司” 支持的项目。也是“群英汇”的“知识管理系统”的展示平台。
如果您想要采用 WHODO 的平台架构来搭建公司的文档管理和知识管理平台，请联系“群英汇”，将 WHODO 搬回家。
Wiki 又作维客，是协同著作的伟大实践。可以作为团队的知识库支撑系统，例如 Whodo 就用 Wiki 技术进行网站的搭建。Wiki 中最著名的要数 维基百科，它号称要成为我们这个星球上最大的百科全书。（不过为了和谐社会，还是听政府的话，非礼勿视）
难道 Wiki 不够么，还要使用 DocBook、Freemind 么？简单的回答就是，Wiki 的文档，不能够本地修改和阅读，必须要在线才能浏览和编辑。
在线编辑，受带宽限制。响应慢，而且不可离线编辑。
-
文档的本地拷贝，可以抗拒服务器断线以及消失的风险。
在 Internet 上提供的 Wiki 服务，受网络通讯限制，政策限制。例如前面提到的网络大百科（WikiPedia.org）被政府管制,2006年起无法访问； BlueHost.com 是 本网站（WorldHello.net）曾经的托管商，在 2006 年底，也由于管制而断网。
本地局域网的 Wiki，也会由于企业没有完备的灾难恢复制度，造成数据丢失。
-
FreeMind/DocBook 格式的文档，让作者有了归属感，使得个人更有成就感。将个人知识管理和团队知识管理的有机整合，才是成功的知识管理平台。
Eric 在谈到程序员投入到开源软件动机的时候，提到“个人成就感”是非常重要一环。而撰写一篇署名的电子文档的成就感显然比没有署名的 Wiki 页面更有成就感。
-
Wiki 的文档，不能够本地修改和阅读，必须要在线才能浏览和编辑。
举个例子，当你的网络出现故障，需要求助时： 一、你记得访问过某个 Wiki 网站，其中有关于网络故障如何诊断文章； 二、有一个 DocBook/FreeMind 撰写的网络故障诊断的电子书，并且就在硬盘中。 第一种情况显然是远水救不了近火，网络故障都上不了网，何谈访问 Wiki 页面。 DocBook 和 FreeMind 技术能够撰写出可本地浏览，可打印的，有作者署名的电子文档，是 Wiki 不可替代的。
打印甚至出版的需要，使得 DocBook 更胜一筹，Single Sourcing，单一文档，多种输出格式，是多少人梦寐以求的啊。
-
FreeMiind 的提纲挈领，FreeMind 的知识和智力的双向转化，是任何其它格式替代不了的。
无论 Wiki 还是 DocBook 都存在着篇幅稍大，文章结构难以把握，而这正是 FreeMind 的强项。
-
Wiki 赖以成名的还有其易用的版本控制系统，但仅仅限于 Wiki 条目本身而已。Whodo 提供的 SVN 版本控制服务则对 Whodo 所有的文档和代码通通管理起来，虽然使用更复杂，但绝对值得交学费。
不过 Whodo 中 Wiki 也是重要一环，因为 Wiki 用来构建文档的索引、链接、归类，便于搜索引擎的检索。
Whodo 主要包括 账号管理子系统、邮件列表、维客、论坛、问题追踪系统、版本控制系统、FreeMind 编辑编译系统 和 DocBook 编译系统 等组成。
WHODO 用户账号统一使用 LDAP 管理，将 Wiki, 论坛, Bug Tracking， Subversion 账号整合在一起。
账号管理地址，参见： https://www.worldhello.net/members/。
基于 Mantis 的问题追踪系统，可以用于对 Whodo 系统以及文档的疏漏和建议进行汇总和追踪。
地址，参见： http://whodo.worldhello.net/bugs。
SVN 版本控制系统，是 WHODO 作者修改和提交文章的支撑系统。 新注册用户拥有只读权限，作者/贡献者拥有 /trunk/doc 目录的完全权限。
地址，参见： http://svn.worldhello.net/svn。
本网站的 FreeMind 文档使用增强版的 FreeMind 编辑的。原因参见 http://whodo.worldhello.net/wiki/FreeMind。
FreeMind 的编译系统，指的是将 *.mm 文件转换为 *.html 文档。
包括 Whodo 定制的 DocBook XSL。
包括相应的编译脚本，将 DocBook *.xml 转换为 *.html, *.pdf, *.rtf, *.chm, *.txt 等。
Whodo 是人人皆可参与文档撰写平台。用户可以从读者身份做起，一步一步成为 Whodo 计划的贡献者。简单的分成如下三类角色：
作为读者，您可以从网站直接访问到 WHODO 文档，可以在线阅读，也可以下载到本地。
如果您读到对您有益的文章，如果您能够给作者发一封 Email，这将会鼓励作者写出更多、更好的文档。
-
通过 Wiki 反馈
Wiki 地址: http://whodo.worldhello.net/wiki。
每一个 Wiki 页面都有一个对应的对话（talk）页，可以在上面发表对文章的评论。
每一个注册用户都有一个用户页（如 http://whodo.worldhello.net/wiki/User:Jiangxin）。当然有的作者还没有来得及编辑他的用户页。
-
通过论坛反馈
-
通过问题追踪系统反馈
Whodo Wiki 的 Bug Tracking 系统 的网址为: http://whodo.worldhello.net/bugs 。您可以在上面提交您的修改或者建议。
当您发现文档中的纰漏或者不足，您可以到问题报告系统上来，提交一个针对该文档的问题报告。
或者您希望了解某方面内容，而文档中没有提及或不详细，您也可以通过问题报告系统提出您的需求，作者或者其它贡献者可能会很快加以完善。
问题报告系统是对所有用户公开的，您只要到上面注册一个账号即可。
如何获得 Subversion 版本控制系统的账号，成为 Whodo 的贡献者？
-
注册账号
在用户管理中心：https://www.worldhello.net/members，注册和管理自己的账号。
-
上传自己的文档，以下任何一种方式均可：
-
通过 Wiki 系统上传
通过 http://whodo.worldhello.net/wiki/Special:Upload 页面上传文档；
接受的上传文档格式有: *.mm, *.xml, *.gz, *.zip, *.rar 等；
通过 论坛 系统上传
-
-
撰写一篇 Wiki 页面
每个文档对应一个 Wiki 页面，包含文档链接。
创建一个页面（页面名称最好为英文，简洁但不失文章主题）。
新创建的页面中除了包含文档名称，提交者，提交时间等信息外，还包括如下内容：
指向刚刚上传的文档链接，或外部文档链接。 通过 Wiki 上传的文档链接为 [[Media:上传文档名]]。如 [[Media:Curl.mm]]。
在页面最前面插入模板： {{草稿}}。模板{{草稿}}，会自动将文档归于 Doc 和草稿分类，并有醒目标识，提醒管理员注意有新用户提交新文档。如： http://whodo.worldhello.net/wiki/Curl_howto。
-
获取 SVN 提交账号
在 Whodo 网站注册，已经获得了 SVN 只读账号。
要想获取 SVN 提交账号，需要向管理员申请提升权限。可以在 Wiki 上通过 http://whodo.worldhello.net/wiki/Special:Emailuser/admin 给管理员发送邮件。管理员受到邮件后，会阅读用户上传的文档，根据是否符合 whodo 文档精神，批准或否决账号申请。
-
用 subversion 账号提交文档
一旦 SVN 权限提升为可读写权限，就可以提交文档。Whodo 文档提交到 Whodo subversion 路径： http://svn.worldhello.net/svn/whodo/trunk/doc 的子目录下。 DocBook 格式文档的首页文档名为 index.xml；FreeMind 文档的文件名和子目录名同名，扩展名为 .mm。
提交文档，要设定文件的 svn:mime-type 或者 svn:eol-style 属性，还要写 commit log，否则会触发 subversion hooks，导致提交被退回。具体参见附录关于 SVN 的说明。
subversion 除了 /trunk/doc 外，其他目录暂时只读，如果需要修改其他目录，请和管理员联系。
-
Whodo 管理员/robot 至少每天编译一次文档，并更新网站
网站更新后，文档才能够在网站中出现。
文档在网站的链接: http://www.worldhello.net/doc。同时 http://whodo.worldhello.net/doc 还存在一份拷贝， 主要是由于 Whodo Wiki 和 WorldHello.net 分属不同主机，用户如果在 Wiki 页面中中嵌入 FreeMind 文档，只能嵌入本地文档。
-
修改 Wiki 页面
之前建立的 Wiki 页面为草稿。在提交文档到版本控制系统之后，需要更新文档中的链接。
Wiki 页面中要包含 文档的作者，提交时间，文档的分类等信息。文档的分类可以是以下分类的组合：[[Category:doc]]，[[Category:db]]，[[Category:mm]]。
Wiki 页面中要嵌入文档链接（使用 <whodo> 标签建立链接）。例如：
id 和 type 属性 # 如果提交文档的名称符合规范，可以采用 id, type 属性显示文档链接 <whodo id="email_howto" type="html"/> <whodo id="docbook_howto" type="htmls"/> <whodo id="bug_tracking" type="htmlz"/> <whodo id="bcp" type="htmlsz"/> <whodo id="bcp" type="chmz"/> <whodo id="bcp" type="pdfz"/> <whodo id="bcp" type="rtfz"/> <whodo id="bcp" type="txtz"/> <whodo id="bcp" type="xml"/> <whodo id="bcp" type="svn" /> # 如果文档名不符规范，可以使用 file 属性，显示文档链接 <whodo file="docbook_howto/mindmap/docbook.mm" type="mm"/> <whodo file="计算机应用能力考试/index.mm" name="全国专业技术人员计算机应用能力考试" type="svn" text='yes'/>
![[注意]](/docbook/includes/images/docbook/note.png) |
|
下面的文档列表是手工收集而成，可能并不全面，也不能保证链接有效。Wiki 中的文档列表是自动创建的，因而更有参考价值。WHODO Wiki 中的文档列表请参见: Whodo Wiki 的文档目录。 |
 |
2008/07/20 - 2008-09-12 23:20:13 | 敏捷Python开发实战 —— pySvnManager (v92) |            |
|
2002/10/26 - 2007-06-19 17:40:06 | 业务连续性的保证 —— BCP (v65) |  |
|
2002/02/26 - 2007-06-19 17:40:06 | 缺陷追踪系统（Bug Tracking）HOWTO (v65) | |
|
2002/01/08 - 2007-06-19 17:40:06 | 版本控制：CVS vs. Starteam (v65) | |
|
2003/01/22 - 2007-06-19 17:40:06 | DNS Howto (v65) | |
|
2002/09/18 - 2007-06-19 17:40:06 | 文档的技术革命 —— DocBook (v65) | |
|
2006/05/03 - 2007-06-19 17:40:06 | 全国专业技术人员计算机应用能力考试 (v65) | |
|
2003/02/11 - 2007-07-31 19:21:18 | 有效沟通和知识管理 —— Email (v69) | |
|
2006/04/17 - 2008-08-02 00:20:39 | FreeMind Hacking Howto (v79) | |
|
2003/01/29 - 2007-06-19 17:40:06 | 摘抄：健康指南 (v65) | |
|
2002/10/14 - 2007-07-31 19:21:18 | 有效沟通和知识管理 —— News (v69) | |
|
2003/02/22 - 2007-06-19 17:40:06 | 有效沟通和知识管理 —— Maillist (v65) | |
|
2006/04/26 - 2007-06-19 17:40:06 | Makefile Howto (v65) | |
|
2002/03/20 - 2007-06-19 17:40:06 | 持续集成 —— 每晚构建/Nightly Build (v65) | |
|
2002/10/30 - 2007-06-19 17:40:06 | 信息安全 —— 个人防火墙 (v65) | |
|
2002/02/20 - 2007-06-19 17:40:06 | PGP/GPG HOWTO (v65) | |
|
2002/01/11 - 2007-06-19 17:40:06 | C 语言开发规范参考 (v65) | |
|
2006/04/25 - 2008-04-24 07:27:41 | Python 学习笔记 (v73) | |
|
2003/06/08 - 2007-06-19 17:40:06 | 有效沟通和知识管理 —— 搜索引擎 (v65) | |
|
2006/04/27 - 2007-06-19 17:40:06 | Subversion Hooks (v65) | |
|
2002/11/15 - 2007-06-19 17:40:06 | 网站管理 Howto (v65) | |
|
2006/04/10 - 2008-09-11 00:59:11 | Whodo 计划 Howto (v84) | |
|
2003/07/08 - 2007-06-19 17:40:06 | 有效沟通和知识管理 —— Wiki (v65) | |
参见 这里。
安全永远不是题外话，不过一部分这里所指的安全，是有中国特色的。
http://www.worldhello.net 网站诞生于 2002 年底，最早是我的个人网站。 那个时候，已经有了一年多 DocBook 使用经验的我，迫不及待的想借用个人网站的形式对 DocBook 加以推广，WorldHello 就这么诞生了。 以 DocBook 进行文档的撰写和个人的知识总结，是 WorldHello 的特色，但那个时候，往好听了说是独自耕耘，其实就是自言自语。
2004 年开始接触到 MindMap，直到后来发现了 Freemind 这个伟大的处理“思维导图”的开源软件，我的个人文档撰写和知识积累的习惯再一次被颠覆了。
2005年中开始筹建公司，主要方向是“开源软件”的商业支持。忽然发现仍然有很多网友关心着我渐已荒废的文档。为什么不开源呢？一方面将我荒废的文档交由感兴趣的作者继续维护，另外一方面，将 WorldHello 网站由一个个性展示的平台真正向本网站的初衷：“推广 Freemind + DocBook + CVS/SVN 的文档撰写模式，开创中文开放文档之源”迈进。
如果您想看看 Whodo 计划之前的 WorldHello.net，一个用 DocBook Website 构建的网站，还可以在这里找到 http://jiangxin.worldhello.net。
关于 FreeMind，可以参照：
《FreeMiind Hacking Howto》 （FreeMind 格式）；
提交到 Whodo 的 Freemind 文档，需要使用 WorldHello 改进过的 Freemind。我们对 Freemind 的改进主要是便于对 Freemind 文档进行版本控制，以及更好的中文支持。
改进如下：
-
改进的中文支持
Freemind 0.8.0 的思维导图如果输入中文，存储的 .mm 文件中所有的中文都换码，类似这样 탖쓎 的存储方式。看过 Freemind 的代码，知道凡是 ASSCII 码大于 126 或者 0-32 的字符全部如此方式换码。这对于比较前后两个更改的思维导图的差异，实在是太困难了！
Freemind 0.8.0 对于 Unicode 支持也不好，存储的 .mm 文件的编码方式是和平台相关的，对于中文，可能是 big5, gb2312 也许是 utf-8，而且 .mm 文件又没有包含字符集的 XML 声明。
-
版本控制友好格式
如果您用过版本控制系统来维护 .mm 文件的变更，您应该会和我一样感到不便。就是没有做任何改动，只是浏览了一下思维导图，展开或者关闭了某个分支，当关闭 .mm 文件时，Freemind 就会提示您保存文件。而版本控制系统也会提示您文件修改了，需要重新 Checkin。
这是因为 Freemind 把节点的展开或者收拢都记录在 .mm 文件中。这对于 Whodo 计划要将 Freemind 格式文档作为可提交的源文档的最大的挑战。
我本人并非 Java 专家，只是由于 Freemind 的这些小缺点搔到了我的痒处，使得我不得不率先做了修改 Freemind 的尝试。我对 Freemind 的修改已经提交到 Freemind 的 Wiki 页面上了，参见: http://freemind.sourceforge.net/wiki/index.php/User:Jiangxin。
Whodo 增强版的 FreeMind 可以从 群英汇升级网站（演示）下载。有 Debian Linux 的版本，也有 Windows 的版本。
Whodo Subversion 版本库地址: http://svn.worldhello.net/svn/whodo，目录格局如下：
-
trunk/doc
Whodo 文档就提交到这里。要在该目录下创建子目录。
目前除了 /trunk/doc 外，其他目录暂时只读，如果需要修改其他目录，请和管理员联系
-
trunk/includes
样式表、DocBook 文档有关的图标、图片，FreeMind Flash 有关文件
注：如果安装了“群英汇”的 ossxp-docbook 软件包，则使用该软件包中的包含文件。
-
trunk/tools
DocBook、FreeMind 格式转换的样式表，编译脚本等。
-
jiangxin.worldhello.net
一个 DocBook Website 站点示例。
Whodo SVN 的 Hooks 脚本会检查新增文件的属性，没有设置 svn:mime-type 和/或 svn:eol-style 属性，禁止提交。
但是每次添加文件后，还要执行类似“svn ps svn:eol-style ...”的命令，实在太繁琐了！ 不过幸好，SVN 客户端（命令行或者 TortoiseSVN），支持自动属性的功能。即会为新增文件自动添加属性。
启用和设置自动属性，是在 config 配置文件中完成的。 config 配置文件的位置：
-
Unix 平台
全局的配置文件位置为：/etc/subversion/config；
每个用户主目录还有配置文件覆盖全局配置文件的设置：~/.subversion/config；
-
Windows 平台
注册表中可能包含相应的设置：HKLM\Software\Tigris.org\Subversion\Config，以及 HKCU\Software\Tigris.org\Subversion\Config。
不过文件的优先级更高。全局配置文件：%ALLUSERSPROFILE%\Application Data\Subversion\config，用户个人配置文件：%APPDATA%\Subversion\config
修改 config 配置文件，启用 auto-props：
[miscellany] enable-auto-props = yes
自动属性的设置，是根据文件名来匹配的。修改 config 文件，增添新的配置，如下：
### Section for configuring automatic properties. [auto-props] ### The format of the entries is: ### file-name-pattern = propname[=value][;propname[=value]...] ### The file-name-pattern can contain wildcards (such as '*' and ### '?'). All entries which match will be applied to the file. ### Note that auto-props functionality must be enabled, which ### is typically done by setting the 'enable-auto-props' option. ################################################## ### Binary files ################################################## *.bmp = svn:mime-type=image/bmp *.gif = svn:mime-type=image/gif *.gz = svn:mime-type=application/x-gzip *.ico = svn:mime-type=image/x-icon *.jar = svn:mime-type=application/zip *.jpg = svn:mime-type=image/jpeg *.pdf = svn:mime-type=application/pdf *.png = svn:mime-type=image/png *.ps = svn:mime-type=application/postscript *.tif = svn:mime-type=image/tiff *.vsd = svn:mime-type=application/octet-stream *.zip = svn:mime-type=application/zip ################################################## ### Text files, OS dependent eol-style ################################################## *.dsp = svn:eol-style=CRLF *.dsw = svn:eol-style=CRLF *.mm = svn:eol-style=LF;svn:mime-type=text/xml *.sh = svn:eol-style=LF;svn:executable Makefile = svn:eol-style=LF ################################################## ### Text files, eol-style is native ################################################## *.c = svn:eol-style=native;svn:mime-type=text/plain *.cpp = svn:eol-style=native;svn:mime-type=text/plain *.css = svn:eol-style=native;svn:mime-type=text/css *.diff = svn:eol-style=native;svn:mime-type=text/plain *.dsl = svn:eol-style=native;svn:mime-type=text/sgml *.dtd = svn:eol-style=native;svn:mime-type=text/plain *.ent = svn:eol-style=native;svn:mime-type=text/plain *.gml = svn:eol-style=native;svn:mime-type=text/sgml *.h = svn:eol-style=native;svn:mime-type=text/plain *.htm = svn:eol-style=native;svn:mime-type=text/html *.html = svn:eol-style=native;svn:mime-type=text/html *.java = svn:eol-style=native;svn:mime-type=text/plain *.js = svn:eol-style=native;svn:mime-type=text/plain *.mod = svn:eol-style=native;svn:mime-type=text/plain *.patch = svn:eol-style=native;svn:mime-type=text/plain *.php = svn:eol-style=native *.pl = svn:eol-style=native *.py = svn:eol-style=native *.sgm = svn:eol-style=native;svn:mime-type=text/sgml *.sgml = svn:eol-style=native;svn:mime-type=text/sgml *.svg = svn:eol-style=native;svn:mime-type=text/xml *.txt = svn:mime-type=text/plain *.xml = svn:eol-style=native;svn:mime-type=text/xml *.xsl = svn:eol-style=native;svn:mime-type=text/xml *.xslt = svn:eol-style=native;svn:mime-type=text/xml README = svn:eol-style=native # 下面的语句有风险，只有用 “群英汇-开源速递” 提供的 Subversion 客户端才可以使用。 # * = svn:eol-style=native
文件添加后，在提交之前，可以通过如下命令查看新增文件的属性：
$ svn proplist -v *
Whodo SVN 要求提交对书写 Commit Log。目前的检查，仅仅限于长度检查。Commit Log 的长度要大于 5 个字节，否则会触发 subversion hooks，导致提交被退回。