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.   1. $ gem install persie

然后，执行以下命令确认是否正确安装：

  1.   1. $ persie version
  2.   2. persie 0.0.1

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

第 2 章 命令行界面

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

2.1. 检查依赖件

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

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

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

2.2. 新建项目

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

  1.   1. $ persie new project-name

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

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

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

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

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

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

文件/文件名作用

book.adoc

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

build

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

images

存放书稿中用到的插图。

manuscript

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

theme

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

tmp

临时文件。

2.3. 生成 PDF 格式电子书

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

  1.   1. $ persie build pdf
  2.   2.   3. # 生成样章
  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.   1. $ persie build epub
  2.   2.   3. # 生成样章
  3.   4. $ persie build epub -s

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

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

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

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

2.5. 生成 mobi 格式电子书

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

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

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

2.6. 生成静态 HTML

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

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

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

第 3 章 设置

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

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

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