读过本系列第一篇的读者知道,我是 Gentoo Linux 的首席设计师,站点也归我管。那时它还有一堆毛病:看着挺漂亮,但除了几张可爱的图,它其实没真正服务到最主要的三类受众——Gentoo Linux 的开发者、现有用户和潜在用户。
上一回,我用「以用户为中心」的方法排出了优先级,并据此制定了重建 gentoo.org 的行动计划。清单最上方有两件事:一套新的开发者文件,以及一个用于向开发者同步 CVS 仓库变更的新邮件列表。后者听起来简单(事实上比我想象的麻烦一些),前者则是个需要大量规划的硬骨头。
我不仅要真正动手写文件(这件拖了很久的事),还得为它们选定一套正式的 XML 语法。要知道,就在几周前,我还在手写原始 HTML 文件。那真是灾难:内容(真正的信息)与呈现(各种显示用的 HTML 标记)搅成一团。后果就是——改一段文字很痛苦,改整站的样式更是噩梦。
这篇文章要展示的,就是那套灵活的新 XML 文件方案。在那之前,先花点篇幅说说添加 CVS 日志邮件列表的经过。
这个列表的目的很单纯:每当有人向 CVS 仓库提交改动,就自动通知开发者。既然我已经装了 Majordomo 邮件列表管理器,建个新列表应该只是几分钟的事——先建列表,再往 CVS 仓库里挂上合适的 hook,让它自动生成并发出描述源码变更的邮件。
我先去研究了仓库 CVSROOT 下那个叫 loginfo 的特殊文件。理论上,改这个文件就能让 CVS 在每次提交时执行一段脚本。于是我写了个 loginfo 脚本塞进现有仓库。它确实work:每次源码变动,都会往新的「gentoo-cvs」列表发邮件。
遗憾的是,效果完全不达预期。第一,它太啰嗦——每改动一个文件就发一封;第二,邮件内容含糊,有时甚至是空的。我很快撤掉了脚本,停用了 gentoo-cvs 列表。结论很清楚:CVS 的 loginfo hook 不适合我。我随后花了大把力气翻找与 loginfo 相关的文档,试图找出症结。
几周后我重新开始找替代方案。这回我干了件聪明事——去 freshmeat.net 逛了一圈,很快就找到了想要的东西:来自 red-bean.com 的 cvs2cl.pl,一个 Perl 脚本。
cvs2cl.pl 的思路完全不同:它不走 loginfo hook,而是直接调用「cvs log」连上仓库抽取相关日志;同时,它不把原始 CVS 日志那种含糊消息丢给你,而是重新整理成可读的 ChangeLog 格式(见清单 1):
清单 1:cvs2cl.pl 生成的输出
2001-04-09 20:58 drobbins
* app-doc/gentoo-web/files/xml/dev.XML: new fixes
2001-04-09 20:47 drobbins
* app-doc/gentoo-web/: gentoo-web-1.0.ebuild,
files/pyhtml/index.pyHtml, files/xml/gentoo-howto.XML: new
gentoo-howto fixes
2001-04-09 20:03 drobbins
* app-doc/gentoo-web/files/xml/dev.XML: typo fix
2001-04-09 20:02 drobbins
* app-doc/gentoo-web/files/pyhtml/index.pyHtml: little update
另外,cvs2cl.pl 也能输出 XML 格式。下一篇我会用上这个特性,把最新的 ChangeLog 嵌进站点新的开发者专区。
下面是我目前用来生成每日 ChangeLog 邮件的脚本。它先把工作目录切到已检出的 CVS 仓库位置,然后生成 $yesterday 和 $today 两个环境变量,值是对应的 RFC 822 格式日期——注意,两者的时间都被设成「00:00」,也就是午夜。接着用这两个变量拼出 $cvsdate,传给 cvs2cl.pl,从而把范围限定为「昨天午夜到今天午夜」。这样,$cvsdate 就成了一条日期规范,告诉 cvs2cl.pl 只记录昨天的改动。
我还准备了 $nicedate 变量用于邮件主题行,并用 mutt(以 mailx 兼容模式)把邮件发到 gentoo-cvs 列表(见清单 2):
清单 2:cvslog.sh
#!/bin/bash
cd /usr/portage
cvs -q update -dP
yesterday=`date -d "1 day ago 00:00" -R`
today=`date -d "00:00" -R`
cvsdate=-d\'${yesterday}<${today}\'
nicedate=`date -d yesterday +"%d %b %Y %Z (%z)"`
/home/drobbins/gentoo/cvs2cl.pl -f /home/drobbins/gentoo/cvslog.txt -l "${cvsdate}"
mutt -x gentoo-cvs -s "cvs log for $nicedate" < \
/home/drobbins/gentoo/cvslog.txt
再挂到 cron 上,每晚午夜自动跑一次。多亏了 cvs2cl.pl,开发者们现在每天都能收到准确、可读的 CVS 更新摘要。
接下来是重头戏:Gentoo Linux 的文件体系。它其实要同时伺候两拨人(甚至三拨):文件的作者需要一套不碍事的 XML 语法;读者根本不关心 XML,他们只想要功能完整、看着舒服的 HTML;而作为站长兼系统作者的我,是隐形的第三方——我得天天跟这套东西打交道,所以它必须可靠且灵活。难点就在于,怎么让一套系统同时讨好这三方。
要产出好读的文件,XML 标记必须给力。最基本的需求包括:能在正文里插入注释、重要提示和警告,并且让它们在生成的 HTML 中真正凸显出来;能嵌入代码块,并且最好能区分「用户输入」和「程序输出」,让读者一眼分清;甚至可以给源码注释上色,进一步提升代码块的可读性。
文件顶部要有目录(带指向各章的超链接)、摘要、修订日期、版本号和作者名单。每篇文件的最上方应有页眉,内含一枚小小的 Gentoo Linux 标识,点击可回到主站。最后但同样重要的是页脚:版权信息与联系邮箱。
需求一长串,而我决定先从最有意思的部分下手——出现在每篇文件左上角的新标识。我拿首页那个「gentoo」图形里的「g」做基础(原图是用免费又出色的 Blender 3D 软件做的),微调了挤压参数,加了一层镀铬环境映射,然后布好灯光和相机,渲染完成。导入 Xara X 并配上文字后,得到了这个结果:
新的 Gentoo Linux 标识

我索性让整套 HTML 配色都从这枚标识取灵感,因此整体走的是略带紫色的调子,字体属性和间距则大量交给 CSS 控制。等 HTML 原型像样了,我才把注意力转向文件的内核——新的 XML 语法。
我的原则是:语法越简单越好。所以我只定义了刚好够用的 XML 标记,用来把文件正确组织成段落、节、章,一个多余的都没有。然后开始用 XSLT 把 XML 转成目标 HTML。
经过多轮调整,再加上一位开发者提供的大量反馈,新的文件系统终于可用。我立刻动手写第一篇新文件——《The Gentoo Linux Documentation Guide》,它完整描述了新的 XML 格式。这一举两得:既让其他开发者有样可学,也 itself 成为新系统在实际场景下的优秀范例。建议每位开发者都通读这份指南,彻底吃透新的 XML 语法。
新文件引擎的其他组件包括:
如果你也在为自己的项目设计文件方案,DocBook XML/SGML 值得纳入考量。它非常适合大型文件与书籍类项目,极其灵活,功能多到(也许太多)用不完;而且现成工具一大堆,能把 DocBook XML/SGML 转成 man 页、texinfo、PostScript、PDF,当然还有 HTML。
我没选 DocBook,因为轻量级 XML 语法更契合 Gentoo 的需要。我们这套 guide 语法大约只有 20 个标记、10 个属性。标记集有限,带来两个直接好处:一是转成 HTML 等格式非常简单;二是整套文件在结构上高度一致,因为格式本身就约束着你。同时,语法是自己的,需要新能力时随时可以加标记——我喜欢这种掌控感。
在我看来,XML 的价值就在于让人以自己认为最实用的方式组织数据。定义自己的元素和属性,是 XML 最有价值的能力,不用就浪费了——毕竟这是 XML 的定义性特征。
当然,自建语法并非总是最优解,尤其当数据交换对你至关重要时。XML 的宣传里常被忽略一件事:不同 XML 格式之间的转换极其困难。多数情况下两种格式做不到 100% 兼容,你要么忍痛舍弃部分数据或元数据(避开某些元素与属性),要么造一个能同时容纳双方数据与元数据的「超级格式」。在文件领域,DocBook 就是理想的超级格式候选:它足够灵活,能轻松容纳来自各种源头的文件。
但 DocBook 的丰富与灵活也可能反过来成为负担。它可能有几百个你这辈子都用不上的标记,而要在 XSLT 里全部支持它们,会让「转出去」这件事变得更麻烦。所以结论是:作为转入其他格式文件的容器,DocBook 非常好用;而作为转出到多种格式的源头,你自己那套最简单的 XML 语法几乎总是更省事。
最重要的一条:评估任何方案时,都别把目标受众的真实需要放在一边。
新文件系统建好后,我把所有文件转换成新格式,并把新文件上线到现有站点,同时补上了 gentoo-cvs 邮件列表的订阅入口。这里的关键在于:这些改进都是叠加在现有站点上的,用户不必等待,立刻就能享受到收益。