Writing Tools Study

Persie

Persie 使用

前言

终于动手编写用户手册了!现在,persie 的开发已经进入到“文档驱动开发”阶段了。为了测试 persie,也为了发现潜在的问题,所以我开始编写用户手册。

开发 persie 的动机有很多。主要是因为我觉得 burr 局限性太多,我需要一个能适应更广泛要求的电子书生成工具。而且,随着我越来越深入的接触 Markdown 和外文书籍的翻译工作,越发觉得 Markdown 已经无法满足丰富的书籍排版样式要求了。以前开发 burr 时,我曾经考察过各种“文本书写语言”,包括 Markdown、AsciiDoc 和 reStructuredText 等。但当时的眼光比较短,没有想太多,直接选用了自己最为熟悉的 Markdown。虽然 Markdown 的语法很少,但通过扩展 kramdown,最终也满足了我的需求。自此,我便使用 burr 制作《Ruby on Rails 教程》的电子书。

但是,由于我的学识有限,burr 有太多的局限性。随着时间的推移,我越发看不上 burr。是的,我自己已经开始嫌弃它了。

心生厌恶之后,我又开始四处搜索,想找到一种真正适合图书排版的“文本书写语言”。因为没有时间压力,这一次我的研究更为深入一些,最终选择了 AsciiDoc。至于原因,我想有下面几点:

  • AsciiDoc 基本上算是为图书排版而生的;

  • 因为第一点,国外很多出版社都在使用 AsciiDoc,包括 O’Reilly。

第二点对我的决策影响最大,既然我所喜爱的 O’Reilly 都在使用,就证明 AsciiDoc 确实不错,而且算得上“企业级”。所以我便选定了 AsciiDoc。

说来也巧,我选定书写语言之后,O’Reilly 发布了 Atlas 服务。简单地说,Atlas 就是电子书出版的 PaaS(Platform as a Service,平台即服务),任何人、团体只要花钱都能使用。很可惜,Atlas 没有免费套餐,试用期满之后我不得不带着遗憾向它告别。

不过在使用 Atlas 的过程中我得知了 O’Reilly 正在制定的一项“标准”——HTMLBook。这个标准的目的是使用 HTML5 编写文稿,而且规范化图书中的各种语义化。又一个 O’Reilly 的产物,我毫不吝啬,决定在即将开发的新工具中使用这套标准。

至此,我已经大概制定好了新工具的工作流程:使用 AsciiDoc 写稿,使用 Asciidoctor 生成符合 HTMLBook 标准的 HTML 文件,然后再使用这个 HTML 文件生成各种格式的电子书。

开发 burr 时我已经积累了一些经验,所以我知道:由 HTML 文件生成 PDF 文件使用 PrinceXML;生成 ePub 文件使用 eeepub(最终使用的是 gepub);生成 mobi 文件使用 kindlegen

三大主流电子书格式都有着落了,剩下的就是编程了。啊,编程!

我多次说过,我不是程序员,我也没打算变成程序员,主要是因为我太笨,IT 技术日新月异,我跟不上步伐。目前为止我学的最为深入的编程语言是 Ruby,不过也只是入门级。如果把精通等级从低到高以十分制算,我应该能得 1-。是的,后面还有个减号。不过我还是决定使用 Ruby 来写这个项目,毕竟这是我最“精通”的语言,而且使用 Ruby 开发命令行工具太舒服了。

说写就写。本着大无畏的“死猪不怕开水烫”精神,几乎每一天我都会写上几行代码。日积月累的,时至今日,已经有了雏形了。你瞧,我都开始用它生成这份手册了。

哦,我似乎忘了说为什么这个工具叫“persie”。首先,我承认我是“伪球迷”。其次,我是荷兰队的“伪球迷”。最后,我是范佩西的“伪粉丝”。这个项目大概孕育在 2014 年巴西世界杯期间,具体在哪个凌晨我记不得了。“起名字什么是最痛苦的。”所以我就直接把范佩西的姓拿来用了。我不会告诉你,我还有一个私人项目叫做 flyman,对,小飞侠,罗本。果然很“伪”。

说了这么多废话,我想你看的也烦了。那咱们就进入正题吧。

第 1 章 安装

persie 的安装十分简单,但前提是你的系统中已经安装好了 Ruby,而且版本不低于 1.9.3。对系统的另一个要求是,不能使用 Windows,任何版本都不行。

persie 以 Ruby gem 的形式分发,安装过程十分简单,只需在命令行中执行以下命令即可:

  1. $ gem install persie

然后,执行以下命令确认是否正确安装:

  1. $ persie version
  2. persie 0.0.1

如果输出了版本号,说明安装成功。如果提示找不到 persie 命令,说明安装失败。

第 2 章 命令行界面

persie 是命令行工具,一切操作都在命令行中完成。当然写稿除外。

2.1. 检查依赖件

安装好 persie 之后,建议你先检查系统中是否安装了所需的依赖件。方法是,在命令行中运行下述命令:

  1. $ persie check
  2. === Check dependencies =================================================
  3. PrinceXML: installed
  4. epubcheck: installed
  5. kindlegen: installed
  6. ========================================================================

然后根据输出的检查报告安装尚未安装的依赖件。

2.2. 新建项目

persie 提供了一个项目骨架,可以为你生成整个项目的基本文件夹结构。在命令行中运行下述命令,记得要把project-name 换成你所需的文件夹名:

  1. $ persie new project-name

这个命令会在当前目录中新建 project-name 文件夹。

在此我要提醒一下,文件夹不要使用中文命名,路径也是一样。我不知道使用中文路径有什么后果,也不打算考虑支持中文路径。如果你使用中文名遇到了什么问题,千万别找我——不是我不想帮你,我是在引导你养成好的习惯。

新建项目后会生成以下文件夹结构:

  1. ├── book.adoc
  2. ├── build
  3. ├── images
  4. ├── manuscript
  5. │   ├── chapter1.adoc
  6. │   ├── chapter2.adoc
  7. │   └── preface.adoc
  8. ├── theme
  9. └── tmp

这些文件夹和文件的作用如表 2-1 所示:

表 2-1:项目内个文件/文件夹的作用

文件/文件名作用

book.adoc

入口文件。这个文件用于设置,以及引入其他文件。

build

生成的电子书都存放在这个文件夹中,各种格式放在各自的子文件夹中。

images

存放书稿中用到的插图。

manuscript

书稿,建议一章一个文件。

theme

各种格式电子书的主题,包括样式表、字体等。各种格式放在各自的子文件夹中。

tmp

临时文件。

2.3. 生成 PDF 格式电子书

写好文稿之后,如果想生成 PDF 格式电子书,可以在项目所在目录中执行如下命令:

  1. $ persie build pdf
  2.   3. # 生成样章
  4. $ persie build pdf -s

persie 使用 PrinceXML 生成 PDF 文件。所以在此之前要先安装 PrinceXML。PrinceXML 可以免费试用,试用版和授权版功能上没有任何差异,只是会在 PDF 的第一页加上 PrinceXML 的 LOGO(业界良心)。如果你觉得 LOGO 有违观瞻,可以把它删掉。删除的方法我想对于充满智慧的你应该不是问题。

生成的 PDF 文件保存在 ./build/pdf/ 文件夹中。

生成 PDF 文件的过程中,会在 ./tmp/pdf/ 文件夹中生成一个临时文件,PDF 文件就是由这个临时文件生成的。默认情况下不会删除这个临时文件,以便调试。

2.4. 生成 ePub 格式电子书

写好文稿之后,如果想生成 ePub 格式电子书,可以在项目所在目录中执行如下命令:

  1. $ persie build epub
  2.   3. # 生成样章
  4. $ persie build epub -s

生成的 ePub 文件保存在 ./build/epub/ 文件夹中。 生成 ePub 文件的过程中,会在 ./tmp/epub/ 文件夹中生成大量临时文件1,ePub 文件就是由这些临时文件生成的。默认情况下不会删除这些临时文件,以便调试。

如果希望生成 ePub 文件之后使用 epubcheck 验证,可以指定旗标 -c

  1. # 使用 epubcheck 验证
  2. $ persie build epub -c

在此之前,你要先在自己的系统中安装 epubcheck。如果没有安装,直接跳过验证。

2.5. 生成 mobi 格式电子书

mobi 格式电子书使用 kindlegen 生成,在此之前要先生成 ePub 格式。

  1. $ persie build mobi
  2.   3. # 生成样章
  4. $ persie build mobi -s

生成的 ePub 文件保存在 ./build/mobi/ 文件夹中。

2.6. 生成静态 HTML

persie 支持生成两种静态 HTML:单文件和多文件。单文件是整本书都在一个文件中显示,多文件一章一个文件。

  1. # 生成多文件
  2. $ persie build html
  3.   4. # 生成多文件
  5. $ persie build html -m

生成的单文件在 ./build/html/single/ 文件夹中。生成的多文件在 ./build/html/multiple/ 文件夹中。

第 3 章 设置

persie 的设置全在入口文件 book.adoc 的“头部”(AsciiDoc 中的 Header 区)。全部选项如下所示:

  1. :author: Author Name
  2. :email: your@email.com
  3. :translator: Translator Name
  4. :translator-email: translator@email.com
  5. :author-label: Author: {author}
  6. :translator-label: Translator: {translator}
  7. :revnumber: 0.0.1
  8. :revdate: 2014-09-05T21:44:41+08:00
  9. :version-label: rev
  10. :lang: en
  11. :description: Tell me some information about your book.
  12. :keywords: the, book, keywords
  13. :toc:
  14. :toclevels: 2
  15. :toc-title: Table of Contents
  16. :numbered:
  17. :sectnumlevels: 3
  18. :listing-caption: Listing %NUM%-%SUBNUM%.
  19. :image-caption: Image %NUM%-%SUBNUM%.
  20. :table-caption: Table %NUM%-%SUBNUM%.
  21. :caption-append-space:
  22. :chapter-caption: Chapter %NUM%.
  23. :appendix-caption: Appendix %NUM%.
  24. :imagesdir: images
  25. :uuid: urn:uuid:3fc0a7e0-1730-0132-bf6e-482a140fb2a8
  26. :isbn: 978-xxxx-xxxx
  27. :epub-identifier-scheme: uuid

执行 persie new 命令生成项目骨架时,不会在 book.adoc 文件中生成上面列出的所有设置。如果需要某项设置,可以自己添加。修改设置时要注意,头部不能含有空行。