Whodo Howto (版本号: 0.3.F-$Rev$)

hide

Whodo Howto

(版本号: 0.3.F-$Rev$)

hide
Whodo 是什么？
leaf
Whodo 不是 Solaris 上的 whodo 命令，而是一个中文开放文档计划。
leaf
Whodo 是“WorldHello Open Document Origin ”，即 “WorldHello 开放文档之源” 的缩写。

是使用 Freemind + DocBook + Wiki + SVN 进行技术文档撰写的开放平台，这里的所有文档遵从GNU 的自由文档许可证(Free Document License)的条款，人人皆可提交更改。
hide
WHODO = Freemind + DocBook + Wiki + Subversion
hide
FreeMind 特色
leaf
组织结构符合人的思维习惯；
leaf
便于信息的整理和重组；
hide
DocBook 特色
leaf
DocBook 的输出格式多样；
leaf
DocBook 用于详尽阐述，图文并茂；
hide
Whodo 文档的几种存在模式
leaf
FreeMind Only
leaf
DocBook Only
leaf
FreeMind + DocBook
hide
Whodo 文档的版本控制
leaf
一个主控文档： FreeMind/DocBook/Wiki 的代号分别为 F/D/W。
leaf
版本号格式为：  <主版本号>.<副版本号>.<主控文档标志>-<主控文档修订号>.<文档修订号>

1. 主控文档有 <主控文档修订号>没有 <文档修订号> ；

2. <主控文档标志> 可以为 F,D,W，分别代表 FreeMind, DocBook, Wiki；

3. 其他文档用 <文档修订号> 来版本控制。一旦将修改合并到主控文档，则归零；

4. 主控文档的版本号不小于其他附属文档的版本号。
hideksmiletris
Whodo 是”北京群英汇信息技术有限公司“支持的，是”群英汇“的知识管理系统的展示。
hideforward
北京群英汇信息技术有限公司：
leaf
http://www.ossxp.com User Link
leaf
http://www.OpenSourceXpress.com User Link
leaf
采用开放格式进行文档管理和知识管理系统搭建，请联系”群英汇“。
hide
Wiki 难道不够么？
leaf
Wiki 又作维客，是协同著作的伟大实践。Wiki 可以作为团队的知识库支撑系统，例如 WHODO 就用 Wiki 技术进行主页的搭建。
leaf
难道 Wiki 不够么，还要使用 DocBook、Freemind 么？简单的回答就是，Wiki 的文档，不能够本地修改和阅读，必须要在线才能浏览和编辑。
hide
在线编辑，受带宽限制。
leaf
慢
leaf
不可离线编辑
leaf
文档的本地拷贝，可以抗拒服务器断线以及消失的风险。 例如：

* wikipedia.com 网络大百科自 2006 以来惨遭封锁；

* worldhello.net 网站最早在 bluehost.com 托管，由于 bluehost.com 遭封锁而断线；
leaf
文档有了属主，个人更有成就感
leaf
举个例子，当你的网络出现故障，需要求助时：

一、你记得访问过某个 Wiki 网站，其中有关于网络故障如何诊断文章；

二、有一个 DocBook/FreeMind 撰写的网络故障诊断的电子书，并且就在硬盘中。

第一种情况显然是远水救不了近火，网络故障都上不了网，何谈访问 Wiki 页面。

DocBook 和 FreeMind 技术能够撰写出可本地浏览，可打印的，有作者署名的电子文档，是 Wiki 不可替代的。
hide
不过 Whodo 中 Wiki 也是重要一环，因为 Wiki 用来构建文档的索引、链接、归类，便于搜索引擎的检索。
leaf
每一篇文章，都有一个 Wiki 页面与之对应；
hide
文档 对应的 Wiki 页面格式：
leaf
文章的作者、贡献者列表
hide
文档链接
leaf
可以用简单的 <whodo> 标签 来创建文档的链接
hide
文档的分类
leaf
用 Wiki 的 [[Category:***]] 语法为文档归类
leaf
所有文档均属于 [[Category:doc]] 分类
leaf
DocBook 格式文档，还要加上 [[Category:db]] 分类
leaf
FreeMind 格式文档，需要加上 [[Category:mm]] 分类
leaf
文档的概述
hide
Whodo 子系统
hide
账号管理子系统
leaf
WHODO 用户账号统一使用 LDAP 管理
leaf
账号管理URL： https://www.worldhello.net/members/ User Link
hide
维客
leaf
如前所述，用 Wiki 用来构建文档的索引、链接、归类，便于搜索引擎的检索。
leaf
地址：http://whodo.worldhello.net/wiki User Link
hide
论坛
leaf
Whodo 沟通系统
leaf
地址： http://whodo.worldhello.net/forum User Link
hide
问题追踪系统
leaf
地址： http://whodo.worldhello.net/bugs User Link
hide
Subversion 版本控制系统
leaf
SVN 版本控制系统，是 WHODO 作者修改和提交文章的支撑系统
leaf
新注册用户只有只读权限，作者/贡献者拥有 /trunk/doc 目录的完全权限
leaf
地址： http://svn.worldhello.net/ User Link
hide
FreeMind 编辑、编译系统
leaf
本网站的 FreeMind 文档使用增强版的 FreeMind 编辑的。原因参见 http://whodo.worldhello.net/wiki/FreeMind
leaf
FreeMind 的编译系统，指的是将 *.mm 文件转换为 *.html 文档
leaf
参见： http://whodo.worldhello.net/wiki/FreeMind User Link
hide
DocBook 编译系统
leaf
包括 Whodo 定制的 DocBook XSL
leaf
包括相应的编译脚本，将 DocBook *.xml 转换为 *.html, *.pdf, *.rtf, *.chm, *.txt 等
leaf
参见： http://whodo.worldhello.net/wiki/DocBook User Link
hide
邮件列表
leaf
之所以先提及邮件列表，是因为通过邮件列表，您可以更迅捷的获得 Whodo 的响应
leaf
地址： http://whodo.worldhello.net/list User Link
hide
Whodo 工作流程
leaf
hide
如何参与 Whodo？
leaf
WHODO 是人人皆可参与文档撰写平台。用户可以从读者身份做起，一步一步成为 WHODO 计划的贡献者。
hide
读者
leaf
作为读者，您可以从网站直接访问到 WHODO 文档，可以在线阅读，也可以下载到本地。
leaf
WHODO 文档基于 GPL 版权，您可以传播给任何人，您可以在您的文章中任意引用，只要您指明文档的出处以及保留作者的有关声明。
leaf
如果您读到对您有益的文章，如果您能够给作者发一封 Email，这将会鼓励作者写出更多、更好的文档。
hide
参与者
hide
通过 Wiki 反馈
leaf
Wiki 地址: http://whodo.worldhello.net/wiki
leaf
每一个 Wiki 页面都有一个对应的对话（talk）页，可以在上面发表对文章的评论。
leaf
每一个注册用户都有一个用户页（如 http://whodo.worldhello.net/wiki/User:Jiangxin）。当然有的作者还没有来得及编辑他的用户页。



用户页对应一个对话页。可以通过该用户的对话页给作者留言，作者会受到邮件通知。
leaf
通过邮件联系作者。 通过如下格式的 URL ，可以向作者发送邮件：

http://whodo.worldhello.net/wiki/Special:Emailuser/USERNAME
hide
通过论坛反馈
leaf
论坛地址: http://whodo.worldhello.net/forum
hide
通过问题追踪系统反馈
leaf
问题追踪系统网址: http://whodo.worldhello.net/bugs
leaf
当您发现文档中的纰漏或者不足，您可以到问题报告系统上来，提交一个针对该文档的问题报告。
leaf
或者您希望了解某方面内容，而文档中没有提及或不详细，您也可以通过问题报告系统提出您的需求，作者或者其它贡献者可能会很快加以完善。
leaf
问题报告系统是对所有用户公开的，您只要在 worldhello.net 网站注册一个账号即可。
hide
作者/贡献者
leaf
作者 或称作 贡献者，他们无私的让大家分享自己的研究成果、自己的所感所想。或者利用自己的业余时间，在自己擅长的领域和他人一起协同工作，撰写传世之作。
leaf
作者/贡献者 最重要的特征是：拥有 Subversion 版本控制系统的账号，可以修改 Whodo 的所有文章。
hide
如何获得 Subversion 版本控制系统的账号，成为 Whodo 的贡献者
hide
注册账号
leaf
http://www.worldhello.net/members/ User Link
hide
上传自己的文档，以下任何一种方式均可
hide
通过 Wiki 系统上传
leaf
通过 http://whodo.worldhello.net/wiki/Special:Upload 页面上传文档；
leaf
接受的上传文档格式有: *.mm, *.xml, *.gz, *.zip, *.rar 等；
leaf
通过 论坛 系统上传
hide
撰写一篇 Wiki 页面
leaf
每个文档对应一个 Wiki 页面，包含文档链接。
leaf
创建一个页面（页面名称最好为英文，简洁但不失文章主题）。如： http://whodo.worldhello.net/wiki/Curl_howto
leaf
新创建的页面中除了包含文档名称，提交者，提交时间等信息外，还包括如下内容：
hide
指向刚刚上传的文档链接，或外部文档链接。
leaf
通过 Wiki 上传的文档链接为 [[Media:上传文档名]]。如 [[Media:Curl.mm]]
hide
在页面最前面插入模板： {{草稿}}
leaf
模板{{草稿}}，会自动将文档归于 Doc 和草稿分类，并有醒目标识，提醒管理员注意有新用户提交新文档。
leaf
如： http://whodo.worldhello.net/wiki/Curl_howto User Link
hide
获取 SVN 提交账号
leaf
在 Whodo 网站注册，已经获得了 SVN 只读账号
hide
要想获取 SVN 提交账号，需要向管理员申请提升权限
leaf
http://whodo.worldhello.net/wiki/Special:Emailuser/admin
leaf
管理员受到邮件后，会阅读用户上传的文档，根据是否符合 whodo 文档精神，批准或否决账号申请
hide
用 subversion 账号提交文档
leaf
一旦 SVN 权限提升为可读写权限，就可以提交文档
leaf
Whodo 文档提交到 Whodo subversion 路径： http://svn.worldhello.net/svn/whodo/trunk/doc 的子目录下。
leaf
提交文档，要设定文件的 svn:mime-type 或者 svn:eol-style 属性，还要写 commit log，否则会触发 subversion hooks，导致提交被退回。具体参见附录关于 SVN 的说明
leaf
subversion 除了 /trunk/doc 外，其他目录暂时只读，如果需要修改其他目录，请和管理员联系
hide
提交文档文件名命名规范
hide
创建子目录
leaf
在 subversion 的 http://svn.worldhello.net/svn/whodo/trunk/doc 路径下创建子目录
leaf
子目录名称使用英文名称
leaf
提交文档位于该目录下
hide
docbook 文档
leaf
首页文档名为 index.xml
hide
freemind 文档
leaf
文件名和子目录名同名，扩展名为 .mm
hide
Whodo 管理员/robot 至少每天编译一次文档，并更新网站
leaf
网站更新后，文档才能够在网站中出现
hide
文档在网站的链接:
leaf
http://www.worldhello.net/doc
leaf
http://whodo.worldhello.net/doc
leaf
之所以有两份拷贝，主要是由于分属不同主机，以及用户可能需要在 Wiki 中嵌入 FreeMind 文档
hide
修改 Wiki 页面
leaf
之前建立的 Wiki 页面为草稿。在提交文档到版本控制系统之后，需要更新文档中的链接
leaf
文档的作者，提交时间等信息
hide
文档的分类
leaf
以下分类的组合
leaf
[[Category:doc]]
leaf
[[Category:db]]
leaf
[[Category:mm]]
hide
文档的链接
hide
使用 <whodo> 标签建立链接
hide
id 和 type 属性
leaf
如果提交文档的名称符合规范，可以采用 id, type 属性显示文档链接
Arrow Link
leaf
<whodo id="bcp" type="mm" />
leaf
<whodo id="email_howto" type="html"/>
leaf
<whodo id="docbook_howto" type="htmls"/>
leaf
<whodo id="bug_tracking" type="htmlz"/>
leaf
<whodo id="bcp" type="htmlsz"/>
leaf
<whodo id="bcp" type="chmz"/>
leaf
<whodo id="bcp" type="pdfz"/>
leaf
<whodo id="bcp" type="rtfz"/>
leaf
<whodo id="bcp" type="txtz"/>
leaf
<whodo id="bcp" type="xml"/>
leaf
<whodo id="bcp" type="svn" />
hide
file 属性
leaf
如果文档名不符规范，可以使用 file 属性，显示文档链接
leaf
<whodo file="docbook_howto/mindmap/docbook.mm" type="mm"/>
leaf
<whodo file="computer_exam/computer_exam_zyjs.mm" name="全国专业技术人员计算机应用能力考试" type="svn" text='yes'/>
leaf
使用 <mindmap> 属性在线显示 FreeMind 文档
leaf
具体参照其他文档的 Wiki 页面
hide
WHODO 文档列表
leaf
Wiki 的 doc 分类：http://whodo.worldhello.net/wiki/Category:Doc User Link
leaf
http://www.worldhello.net/doc/docs.html User Link
hide
WHODO 贡献者列表
leaf
Wiki 的 author 列表：http://whodo.worldhello.net/wiki/Category:Author User Link
hide
题外话： 关注 Whodo 的安全
hide
文档质量标准
leaf
适合多人协作的文档
leaf
文档内容不要违反法律、道德
leaf
莫谈国事
hide
禁止权限滥用
leaf
Whodo 的各个子系统都和邮件列表联动，能够使得垃圾数据的提交会被及早发现
leaf
一旦发现用户提交垃圾数据或者破坏他人文章的行为，管理员有权封锁直至删除该用户账号
hidepencil
附录
hide
WHODO 历史
leaf
http://www.worldhello.net 网站诞生于 2002 年底，最早是蒋鑫的个人网站，那时叫做 Johnson's Homepage
leaf
那个时候，已经有了一年多 DocBook 使用经验的我，迫不及待的想借用个人网站的形式加以推广。 WorldHello 就这么诞生了。以 DocBook 进行文档的撰写和个人的知识总结，是 WorldHello 的特色，但那个时候，往好听了说是独自耕耘，其实就是自言自语。
leaf
2004 年开始接触到 MindMap，直到后来发现了 Freemind 这个伟大的处理“思维导图”的开源软件，我的个人文档撰写和知识积累的习惯再一次被颠覆了。
leaf
2005年中开始筹建公司，主要方向是“开源软件”的商业支持。忽然发现仍然有很多网友关心着我渐已荒废的 文档。为什么不开源呢？一方面将我荒废的文档交由感兴趣的作者继续，另外一方面，推广 Freemind + DocBook + Wiki + SVN 的文档管理、知识管理平台呢？
hide
Freemind (WorldHello Edition)
leaf
UTF-8 以及更好的中文支持
leaf
版本控制优化
leaf
参见 jiangxin@Freemind
hide
DocBook (WorldHello XSL)
leaf
如何部署 DocBook 编译环境
leaf
如何编译 WHODO 文档
hide
如何访问 SVN 版本控制系统？
hide
Whodo Subversion 版本库访问
leaf
http://svn.worldhello.net/svn/whodo/
leaf
svn ls http://svn.worldhello.net/svn/whodo/
leaf
svn checkout http://svn.worldhello.net/svn/whodo/trunk localdir
hide
Whodo Subversion 版本库目录结构
hide
trunk/doc
leaf
Whodo 文档
leaf
Whodo 文档就提交到这里。要在该目录下创建子目录。
leaf
目前除了 /trunk/doc 外，其他目录暂时只读，如果需要修改其他目录，请和管理员联系
hide
trunk/includes
leaf
样式表、DocBook 文档有关的图标、图片，FreeMind Flash 有关文件
hide
trunk/tools
leaf
DocBook、FreeMind 格式转换的样式表
leaf
编辑脚本
hide
jiangxin.worldhello.net
leaf
一个 DocBook Website 站点示例
hide
新增文件的 svn:mime-type 和/或 svn:eol-stype 属性设置
leaf
Whodo SVN 的 Hooks 脚本会检查新增文件的属性，没有设置 svn:mime-type 和/或 svn:eol-style 属性，禁止提交
leaf
svn 客户端（命令行或者 TortoiseSVN），都可以通过修改配置文件启用自动属性的功能
hide
修改 config 文件
hide
配置文件的位置
hide
Unix
leaf
# site-wide configuration:

/etc/subversion/config



# per-user configuration:

~/.subversion/config
hide
Windows
leaf
# site-wide configuration:

%ALLUSERSPROFILE%\Application Data\Subversion\config

REGISTRY:HKLM\Software\Tigris.org\Subversion\Config



# per-user configuration:

%APPDATA%\Subversion\config

REGISTRY:HKCU\Software\Tigris.org\Subversion\Config
hide
启用 auto-props
leaf
[miscellany]

global-ignores = *.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#* .DS_Store .cvsignore Thumbs.db CVS

use-commit-times = yes

enable-auto-props = yes
hide
auto-props 设置
leaf
### 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
leaf
启用“自动属性”之后，通过 svn add 添加文件后，可以通过 svn pl -v 文件名，查看新增文件的属性是否正确设置
hide
对 Commit Log 的检查
leaf
目前对 Commit log 的检查只是检查长度要大于 5 个字节，否则会触发 subversion hooks，导致提交被退回
hide
SVN 客户端
leaf
Windows 用户推荐使用 TortoiseSVN 。
leaf
Windows 安装 Cygwin，提供更强大命令行支持，不过最好使用官方发行的 Windows 平台下的 subversion命令行。
hide
版本控制
hide
0.3
leaf
添加版本控制
hide
0.2
leaf
补充 svn 说明，Wiki 上载文件以及创建文档草稿的说明。(2006/05/15)
hide
0.1
leaf
初稿。(2006/05/07)