基于Sphinx的图书协同

简要说明如果进行分布式的图书協同 ;-)

参考:

• 如何组织在线图书工程
• SphinxprojectHowto * pymotwcn * PyMOTW的中文翻译项目

简述

常常有人问俺:"我想搭建一个能够多人（10人以内，都是公司组内成员）协同编写，并且能够进行版本管理，而且进度能够给网上读者查阅，并能够进行评注的环境，你能给我介绍一下搭建环境的大概流程吗？"

好吧,集中快速回答一下:

其实,俺推荐的开放图书工程,协同流程是要参考社区发来的,也有专门文章: 经验分享:"如何组织在线图书工程"

• http://code.google.com/p/openbookproject/wiki/HowToBuildBookOnline
• 以及相关演讲:
• 幻灯: http://zoomquiet.org/res/s5/090913-lovpy/
• 录音: http://zoomquiet.org/res/m/r/wav4zoomq/070804-lvpy-book-creat/070804-cpugV004-obp-lovelypy.ogg

从宏观上说,创立图书团队很简单:

• 1. 确立主持人,以便集中讨论/启动/推动
• 2. 建立基础环境:
• 创建专用列表,推荐 googlegroups 服务
• github/bitbucket 创建仓库
• 初始化图书的 Sphinx 工程,章节目录
• 联接 http://readthedocs.org/ 自动化编译服务
• 手册: http://read-the-docs.readthedocs.org/en/latest/index.html
• 3. 加入成员,绑定仓库权限,开始码字
• 然后,根据需要,分阶段进行针对性的社区宣传,发起各种活动:
• 预览试阅
• 技术校对
• 挑錯,,,,

以便保持关注,吸收反馈,改进内容,,,

几个具体问题:

• 版本管理?
• 本身图书工程就在 Hg/Git 版本仓库中
• 使用正当的软件工程的版本管理方式就好
• 而且 readthedocs.org 本身支持图书多版本发布的
• 进度查询?
• 可以插入 changlog 章节,描述重大版本的进展
• 也可以在章节标题中加入完成度的描述
• 当然,更加cool 的是使用 github/bitbucket 的 commit mail 服务,直接将修訂提交信息自动发布到邮件列表
• 而邮件列表也有 rss 输出的,通过 planetplanet 之类抓取系統,就可以简单的将进展发布到相关网站或是自行订阅了
• 在线评注?
• 俺是同时使用 DISQUS 进行页面评注
• 以及使用定制的 Sphinx 模板,进行点評
• e.g.
• 代码: https://bitbucket.org/ZoomQuiet/the-art-of-community-zh/src/1dd5c4c7b05c/source/_static/j/comment.js
• 效果: http://readthedocs.org/docs/taoc-zh/en/latest/
• 那些左侧的气泡图标,点击后,自动跳到对应的 Issue 收集平台
• 当然,你也完全可以自行开发一个評論服务,通过 Ajax 注入到页面中

为毛?!

其实这方面早已发布过至少4个在线協同翻译平台, 但是都消亡了:

• Limodou :
• 使用Django 开发的平台 发布的: http://limodou.51boo.com/booklist/
• 早年使用 Zope 发布的: http://pyrecord.freezope.org/translation
• 留影: http://floss.zoomquiet.org/data/20080528101251/index.html
• vcc.163 使用 http://code.google.com/p/pydoc-zh/ 发布的
• http://fy.py3k.cn/ ; http://djangobook.py3k.cn/
• Young King <yanckin@gmail.com> frok django-doc 的
• 主页: http://djangobook-cn.appspot.com/
• 代码: http://bitbucket.org/youngking/djangobook-cn
• 又一个Pootle: Python 3 Docs Chinese Translation [简体中文]
• http://python-internal.net/pootle/zh_CN/python3-docs-zh_cn/

原因就在于:

• 翻译这种行为,不是标准的编程行为
• 是种文学式的再创作
• 即使有自动化翻译工具的帮助,依然无法替代人工的深度思考
• 而且翻译是要 信/达/雅 兼顾的整个章节通盘考虑,和调节的:
• 所以,基于过往句/词翻译 的自动化翻译辅助基本无用
• 而基于自然段或是逐句翻译的在线協同,其成果基本无法阅读
• 而原先的翻译辅助平台都是基于 i18N 时的 po 文件,将整个文章自动化打碎为词/句来进行翻译管理的
• 这直接导致翻译时没有上下文,完全是生译
• 而且翻译界面不论怎么对比调整也没有整篇在前,自由前后印证校译的感觉
• ...等等诸多不适应!
• 所以, Sphinx 一出现,俺就感觉这是最自然的图书協作基础格式了!
• 进而逐步解决管理/協同/追踪/自动化发布的环节
• 就形成了目前 O.B.P 工程使用的通用图书作译協作流程
• 基于各种免费服务,形成一个完备的顺畅的工作环境

参考: 翻译的错觉 逐句翻译。 这要比“逐词翻译”好一些，但实际上段落才是文意的基本单位。译者翻译一个段落可能需要左思右想花些时间，但读者阅读段落的速度是很快的。...

以下简述目前,综合使用在线免费资源,可以集成的 基于Sphinx的图书协同翻译环境

资源配置

涉及的资源::

• 交流: 配合各个图书，或是统一的O.B.P列表
• 工程: 配合各个图书，或是统一的项目托管:
• 进行 知识(Wiki)/任务/问题(Issue) 管理
• 版本: 配合各个图书的专用 版本仓库
• 所有O.B.P发起的一般主仓库是 https://bitbucket.org/ZoomQuiet/obp.***
• 游览: 使用 http://readthedocs.org/ 服务，配合 http://bitbucket.org 的POST服务，可以完成自动同步和编译以及发布
• 进一步的:
• 通过定制 Sphnix 模板,在输出的HTML 页面中包含了 JQuery 支持的可点击评论点;
• 点击后重定向到 code.google 对应工程中的提案仓库,以便收集所有建议,进行统一修订!
• 而且，也可以嵌入 http://disqus.com/ 的评注服务，在每一页的尾部提供在线注释的支持!
• http://readthedocs.org/ 已经追加了对 epub 的自动化编译支持!
• 还有个重要特性:
• http://read-the-docs.readthedocs.org/en/latest/alternate_domains.html
• readthedocs.org 支持域名的多样性配置; 默认是将翻译中的图书发布在 http://*.readthedocs.org 或是用精简域名: http://*.rtfd.org
• 正式版本的图书可以经过DNS配置,发布成 taoc.TEDtoChina.org 或是 TEDtoChina.org/taoc 等等自己的域名中!

其中::

• http://code.google.com/p/openbookproject/wiki 也可通过 Hg 仓库进行操作!
• 克隆 hg clone https://wiki.openbookproject.googlecode.com/hg/ openbookproject-wiki

运用

简述基于以上资源配合时,图书工程实际如何开展的,分主要角色叙述用户故事...

读/编

1. 游览: http://***.readthedocs.org/ 图书实时编译发布环境
2. 随时进行反馈:
1. 点击页面左侧的反馈点,到跳到工程主页反馈 ^{使用 code.google 的Issue服务}
2. 在页面底部直接进行评论 ^{使用http://disqus.com/服务}
3. 进一步的,可以根据首页信息,订阅邮件列表加入团队,跟进翻译

作/译

1. 注册 https://bitbucket.org
2. 将目标图书工程进行分支克隆
3. 本地安装必要工具: Python

#   安装 Hg
$ pip install mercurial 
#   安装 Sphinx
$ pip install sphinx

4. 从bitbucket.org获得 源文本, e.g.

hg clone https://bitbucket.org/ZoomQuiet/obp.rwiwpyzh RWIwPyZh

5. 本地编译/改进/检入仓库

RWIwPyZh> make html

6. 及时推送到个人克隆仓库

hg ci -m "+*.*H ch** 修订日志"
          |       |     +- * 增补版本简述
          |       +- * 涉及章节编号
          +- * 本次增补用时记录
...
hg push
...

7. 阶段性的提交合并申请
8. 多次提交后,图书主持创译团队,认可了你的能力, 就将直接受你成为正式成员,以后就可以直接 push 变更到主仓库,而不用每次等待团队评审,人工合并进来了...

实际上,作为译者,唯二要知道的事儿就是::

1. rST 的基本语法,可以从 PDF 的文字翻译成 .rst 格式的纯文本
2. 使用 Hg 怎么记录版本,并推送成果到仓库

唯一要坚持作的事儿,就是:

1. 每天坚持通过列表,向所有人吼出你的当日进度

流程

简要的说::

1. 一般是先有出版社编辑动议,明确出版意向后才开始召集团队
2. 根据图书内部的领域分布,从相应技术社区召集译/作者后,结成团队
3. 对应创建基于 Sphnix 的图书工程后,检入相应专用仓库
4. 由核心主创人员,通过版本仓库远程协同推进 ~ ^{允许进一步分解任务协同其它成员创作,但是,都应该通过版本仓库}
5. 定期/自动 编译出在线图书,开放给编辑/校对等团队同步查阅
6. 在统一的提案追踪系统中收集意见,及时修订
7. 最终交付编辑完整的内容^注意!不包含排版,由出版社,找专业团队进行排版

靠谱分析

依照: The Joel Test: 12 Steps to Better Code 核查图书协同流程的靠谱度::

参考

• 简要 Hg 使用
• 如何Python?
• Quick reStructuredText
• 如何使用StructuredText * 中国Zope/Plone用户组
• reStructuredText Tutorial: PyCon 2003
• Sphinx快速开始 * pymotwcn

• 基于Sphinx的图书协同
• 简述
• 为毛?!
• 资源配置
• 运用
• 读/编
• 作/译
• 流程
• 靠谱分析
• 参考