persie 使用手册

前言

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

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

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

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

第二点对我的决策影响最大,既然我所喜爱的 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 的形式分发,安装过程十分简单,只需在命令行中执行以下命令即可:

$ gem install persie

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

$ persie version
persie 0.0.1

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

第 2 章 命令行界面

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

2.1. 检查依赖件

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

$ persie check
=== Check dependencies =================================================
PrinceXML: installed
epubcheck: installed
kindlegen: installed
========================================================================

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

2.2. 新建项目

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

$ persie new project-name

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

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

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

├── book.adoc
├── build
├── images
├── manuscript
│   ├── chapter1.adoc
│   ├── chapter2.adoc
│   └── preface.adoc
├── theme
└── tmp

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

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

文件/文件名作用

book.adoc

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

build

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

images

存放书稿中用到的插图。

manuscript

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

theme

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

tmp

临时文件。

2.3. 生成 PDF 格式电子书

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

$ persie build pdf

# 生成样章
$ persie build pdf -s

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

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

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

2.4. 生成 ePub 格式电子书

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

$ persie build epub

# 生成样章
$ persie build epub -s

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

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

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

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

2.5. 生成 mobi 格式电子书

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

$ persie build mobi

# 生成样章
$ persie build mobi -s

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

2.6. 生成静态 HTML

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

# 生成多文件
$ persie build html

# 生成多文件
$ persie build html -m

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

第 3 章 设置

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

:author: Author Name
:email: your@email.com
:translator: Translator Name
:translator-email: translator@email.com
:author-label: Author: {author}
:translator-label: Translator: {translator}
:revnumber: 0.0.1
:revdate: 2014-09-05T21:44:41+08:00
:version-label: rev
:lang: en
:description: Tell me some information about your book.
:keywords: the, book, keywords
:toc:
:toclevels: 2
:toc-title: Table of Contents
:numbered:
:sectnumlevels: 3
:listing-caption: Listing %NUM%-%SUBNUM%.
:image-caption: Image %NUM%-%SUBNUM%.
:table-caption: Table %NUM%-%SUBNUM%.
:caption-append-space:
:chapter-caption: Chapter %NUM%.
:appendix-caption: Appendix %NUM%.
:imagesdir: images
:uuid: urn:uuid:3fc0a7e0-1730-0132-bf6e-482a140fb2a8
:isbn: 978-xxxx-xxxx
:epub-identifier-scheme: uuid

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

各设置的作用详述如下。

3.1. 作者信息

设置项作用备注

:author:

作者姓名

选填

:email:

作者的电子邮件地址

选填

:translator:

译者姓名

选填

:translator-email:

译者的电子邮件地址

选填

:author-label:

titlepage 显示的作者信息格式

选填

:translator-label:

titlepage 显示的译者信息格式

选填

3.2. 版本信息

设置项作用备注

:revnumber:

版本号,或者修订历史版本号

选填

:revdate:

该版本的发布日期,使用 ISO8601 格式

选填,如果不指定,则使用当前日期

:version-label:

显示在版本号前的文字,例如“v”或“rev”

选填

3.3. 元信息

这些设置项主要用于设置 HTML 的元信息。

设置项作用备注

:lang:

书写文稿的语言,用于设定 <html> 标签的 lang 属性,以及 ePub 文件的 dc:language 元信息

选填,默认值为 en

:description:

书籍内容简介,用于设定 description元标签,以及 ePub 文件的 dc:description 元信息

选填

:keywords:

书籍内容的关键词,用于设定 keywords 元标签,以及 ePub 文件的 dc:subject 元信息

选填

3.4. 目录信息

设置项作用备注

:toc:

是否显示目录

这是布尔值选项,没有值。如果需要真值,直接写 :toc:;需要假值,写成 :toc!:

:toclevels:

显示几级目录

选填,默认显示 2 级

:toc-title:

目录页的标题

选填,默认值是“Table of Contents”

3.5. 自动编号

自动编号涉及到章节、图片、代码清单和表格等。

设置项作用备注

:numbered:

开启所有自动排序

如要关闭,使用 :numbered!:

:sectnumlevels:

自动排序到哪一级小节

默认为第 3 级,例如“1.2.3 节”

3.6. 标签格式

设置项作用备注

:listing-caption:

代码清单标题的标签格式

:image-caption:

图片标题的标签格式

:table-caption:

表格标题的标签格式

:caption-append-space:

是否在标签后面加上空格

只对代码清单,图片和表格的标签有效

:chapter-caption:

章名的标签格式

:appendix-caption:

附录的标签格式

其中,前三项设置可以使用两种占位符:%NUM% 和 %SUBNUM%。前者表示所在章的编号,后者表示在这一章中的序号。

最后两项设置可以使用一种占位符:%NUM%,表示章或者附录的序号。章的序号使用阿拉伯数字,附录的序号使用大写英文字母。

3.7. ePub 格式专用设置

这些设置是 ePub 格式专用的。

设置项作用备注

:uuid:

用于设置 ePub 文件的 dc:identifier元信息

创建项目时会自动生成

:isbn:

用于设置 ePub 文件的 dc:identifier元信息

选填

:epub-identifier-scheme

dc:identifier 元信息使用哪种机制

可选值:uuid 或 isbn

  1. 具体有多少,取决于书中有多少章节。