> For the complete documentation index, see [llms.txt](https://freebsd-journal-cn.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://freebsd-journal-cn.bsdcn.org/2015-0910-cloudabi/this-month-in-freebsd.md).
# FreeBSD 本月动态
* 原文：[This Month in FreeBSD](https://freebsdfoundation.org/our-work/journal/browser-based-edition/cloudabi/)
* 作者：**Dru Lavigne**
FreeBSD 素以文档详尽著称。FreeBSD 项目提供了大量文档，包括 FreeBSD Handbook、Porter’s Handbook、Developer’s Handbook、Documentation Project Primer、内置与在线的 man 手册页、官方网站。维护并翻译如此庞大的文档自有其挑战。本月，我有机会采访 WARREN BLOCK。Warren 是资深的文档提交者，FreeBSD DocEng 团队成员，也是 igor（）的作者。
**问：** 请介绍一下你自己。你是如何开始接触 FreeBSD 的？你在 FreeBSD 项目中参与哪些工作？
**答：** 1998 年，我那座地下火山巢穴开始变热，爪牙们还想组建工会，说什么鲨鱼和大王乌贼的安全问题。事情全被夸大了；那道陷阱门有某种制造缺陷。Cletus 也不是最聪明的爪牙，显然并不真正理解锁定/挂牌系统。你若问过大王乌贼饲料的价格，便知那也是一笔侵蚀利润的开销。
在寻找一种廉价又不会把我当成盗贼的巢穴操作系统时，一位朋友向我介绍了 FreeBSD 4.0。
此后便一发不可收拾。我先在一台机器上装了 FreeBSD，接着又是几台，后来每月都要装几台。这样持续了好些年。FreeBSD 应用软件丰富，我统统用上。我也不讳言，有时甚至还为此收钱。
过了很久，我开始提交 bug 报告，有时一天两三个，多半关于文档问题。文档提交者是典型的书呆子，可能更甚，处理这些 bug 报告占去了他们原本在邮件列表上发表尖酸评论的时间。一度，Glen Barber 与 Benedict Reuschling 提名我拿文档提交权限。那不过是一张橡皮图章，写着“你大概可以直接向文档仓库提交而不至于搞得太糟，放手干吧”。
又过了一阵，我惹出的麻烦大多能轻易嫁祸他人。随后我被提名进入 Document Engineering 团队。如今只盼他们别发现我其实是套着人皮的三只浣熊。等等，别印出来。
**问：** FreeBSD 项目在维护与翻译文档方面面临哪些挑战？
**答：** 首先是体量。已有文档数量庞大，保持更新十分困难。系统与程序不断变化，我们曾同时有多达三个 FreeBSD 版本发布并维护。
另一个问题是标记语言。我们使用 DocBook，要花一番学习才能理解并有效运用。我们还用 mdoc 写 man 手册页，与 DocBook 截然不同。这对新用户而言都颇具威慑力。好在已有海量文档可作范例。难处在于让这些标记保持良好状态。人们似乎本能地挑最差的文档作范例，再复制那种糟糕的格式。
这些因素也让人难以审阅技术文档。我们最关心的其实是内容正确，但在 DocBook 标记的文件中只读内容颇为费力。这也是我们想做的一长串事情中的又一项：用某种标注系统让人无需在标记中跋涉便能在线阅读与校对文档。
**问：** 你最近发布了一则通知，征集测试人员为翻译者提供关于使用 PO/Gettext 进行文档翻译的反馈（）。为何选择这套工具链？它如何改变翻译者的工作流程？
**答：** 首先要明白，FreeBSD 早于 XML 这类现代技术。最初的翻译系统是多年前搭建的，运作方式与源码无异。翻译团队需关注英文文档的提交。然后查看改动，手动翻译成自己的语言。他们必须小心保留 XML 标记，甚至包括团队内部的缩进规则，因为这一切都需协调。
维持这些翻译更新所需的工作量与奉献精神令人惊叹。一些团队跟不上进度，于是我们失去了许多重要世界语言的翻译。
就连撰写英文文档的人也得格外小心。仅影响段落重新换行或制表符与空格的空白改动必须与内容改动分开，免得翻译者无谓地重译内容相同的段落。向新贡献者解释避免空白改动的重要性出奇地困难与令人困惑。“看到这些看不见的东西了吗？别动它们，即使它们无关紧要。”
与此同时，其他开源项目已开始用 gettext 的 PO 系统（）做翻译。这与程序员用于把程序用户界面翻译成其他语言的系统相同。对我们而言，这极大简化了翻译。翻译者无需再盯着英文版的提交。他们无需处理大量标记，也不必操心如何把改动并入既有翻译。PO 编辑器（）只显示哪些字符串待译。当英文版变动时，仅需重译变动的部分，PO 编辑器还能显示整份文档已译完的比例。
另一大优势是“翻译记忆”。某个字符串译过之后，PO 编辑器能记住它，并在该字符串出现于其他文档时自动套用。翻译者无需重译，工作量随之减少。
翻译团队成员之间可以共享翻译记忆。甚至有 Pootle（）这类应用，本质上是个在线 PO 编辑器。登录一个网站就能翻译文档。其他项目早已这么做，但对我们而言仍带着新车般的气息。
总体而言，PO 翻译系统让翻译者专注于翻译。
**问：** 对有意在自己的文档中使用 PO/Gettext 的读者来说，转换既有文档并把这种翻译方法集成到构建系统中的流程是怎样的？FreeBSD 既有文档集有多大？从文档转换、集成、内部测试到公开征集测试花了多长时间？
**答：** 若文档本身是 XML，又没有既有翻译，事情可能相当简单。有不少程序能把 XML 文件中的字符串提取到 PO 文件，也能反向生成，比如 itstool（）和 po4a（）。基本流程很简单：从 XML 文件提取字符串，用 PO 编辑器翻译，再用译好的字符串构建新的 XML 文件。当然，一路上可能遇到各种坑。
我们有大量既有翻译，英文源文档大约 87 MB，包括 FreeBSD.org 网站。最大的单篇文档是 FreeBSD Handbook 与 Porter’s Handbook。
我倒愿意说既有翻译已经转换完成。可惜尚未。用 PO 系统产出的翻译，要么是此前从未译过的文档，要么是全新的翻译。我们有些翻译已严重过时，重头译起未必比试图转换更费力。
一直有传言说存在能从既有翻译反向映射回 PO 文件的软件，但至今尚未找到。调查仍在进行，欢迎随时相助。
**问：** 向新翻译流程的过渡是否顺畅？过程中有什么意外？你收到翻译者哪类反馈？
**答：** 鉴于过渡才刚开始，目前还难下断言。最棒的一点是，当有人愿意帮忙翻译 FreeBSD 文档时，我们如今能接纳这份好意。他们无需通读理解整部 FreeBSD Documentation Project Primer 与 DocBook XML 及其他一切。
最好的反馈是：“我试了，能用！”
**问：** 展望未来，项目是否有进一步计划，降低有意为 FreeBSD 文档及其翻译贡献者的学习曲线与工作量？
**答：** 学习曲线是个难题，因为它由几部分构成。标记语言是其一，但我们还有风格与格式规则。有些事可以也应该自动化。我对让 DocBook 标记更好用有些想法。
切换到另一套标记系统也是可能的。有人建议我们全面改用 Markdown，或 mdoc，或 AsciiDoc（）。但当前系统依赖一套庞大工具链，充分利用了 DocBook 的诸多特性。正如重新实现任何遗留系统，事情没有初看上去那么简单。切换需要为许多功能寻找替代品，而一些更简单的标记系统是靠牺牲功能或表达力换来的简洁。
借助工具改善现有系统对最终用户的体验，是大有可为的。一个粗略的例子是 igor，这个程序只做一件事：通读文档，寻找问题。它检查从拼写到格式与风格的各种问题。这分担了用户的部分负担，正如编程中的 lint 检查器。当前实现聊胜于无，但这一领域大有改进空间。
倘若人们能用 LibreOffice 写文档，输出 DocBook，会怎样？从技术上讲，可以配置“样式”功能，使其拥有“filename”、“command”等样式。也许有更小的 GUI 编辑器能做同样的事。我才刚刚着手研究。眼下还只是个想法。
问题之一是 FreeBSD 的贡献者都不懒。我的意思是，我们的许多贡献者非常执着，宁愿亲手写 XML 标记也要尽快把事情修好。如此一来，贡献者的奉献反而可能害了我们。这些人能忍受那些可能吓跑新贡献者的不友好流程。
许多人愿意修复或更新文档的一小部分，我们需要为这些贡献铺路。
**问：** 你也是 DocEng 团队成员。这个团队在 FreeBSD 项目中扮演什么角色？
**答：** 主要是让文档工具正常运作、让文档运转良好。这包括文档涉及的各种工具与工具链的组合：DocBook、XML、mdoc、XSL、网站所需的一切。
这些系统之间交互的方式既精妙又引人入胜。偶尔也令人毛骨悚然。
**问：** 你最近参加了在俄亥俄州辛辛那提举办的 OpenHelp 会议（）。今年的会议有什么有趣的心得？文档撰写者与翻译者为何需要与其他开源项目交流？
**答：** 能与更广的社区互动十分好。我们在很大程度上面对相似的问题。这类会议提供了一个机会，看看其他团队如何解决问题，也让他们看看我们的方法效果如何。融入更大的开源社区十分有价值。
PO 翻译系统便是一例。FreeBSD 此前从未用过它，对其常见问题与解决方案一无所知。其他项目使用该系统多年，是宝贵的信息与援助来源。
今年，人们对 AsciiDoc 兴趣浓厚。这种简化的标记语言对许多用途已足够强大。与我们一样，其他项目也在为教贡献者使用自家标记系统而苦恼，于是问题变成了：他们产出的文档究竟需要多大复杂度。
与更大开源社区的互动，能帮助我们避免陷入某种死胡同式的路径依赖，也让我们留意新的可能。我们向他们学习，他们也向我们学习。共赢。除了 Cletus。至少那只大王乌贼挺开心。
**作者简介**
**Dru Lavigne** 是 FreeBSD 基金会董事，BSD 认证小组主席。
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://freebsd-journal-cn.bsdcn.org/2015-0910-cloudabi/this-month-in-freebsd.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.