终于动手编写用户手册了！现在，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，对，小飞侠，罗本。果然很“伪”。
说了这么多废话，我想你看的也烦了。那咱们就进入正题吧。
persie 的安装十分简单，但前提是你的系统中已经安装好了 Ruby，而且版本不低于 1.9.3。对系统的另一个要求是，不能使用 Windows，任何版本都不行。
persie 以 Ruby gem 的形式分发，安装过程十分简单，只需在命令行中执行以下命令即可：
$ gem install persie
然后，执行以下命令确认是否正确安装：
$ persie version persie 0.0.1
如果输出了版本号，说明安装成功。如果提示找不到 persie 命令，说明安装失败。
persie 是命令行工具，一切操作都在命令行中完成。当然写稿除外。
安装好 persie 之后，建议你先检查系统中是否安装了所需的依赖件。方法是，在命令行中运行下述命令：
$ persie check === Check dependencies ================================================= PrinceXML: installed epubcheck: installed kindlegen: installed ========================================================================
然后根据输出的检查报告安装尚未安装的依赖件。
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
临时文件。
写好文稿之后，如果想生成 PDF 格式电子书，可以在项目所在目录中执行如下命令：
$ persie build pdf # 生成样章 $ persie build pdf -s
persie 使用 PrinceXML 生成 PDF 文件。所以在此之前要先安装 PrinceXML。PrinceXML 可以免费试用，试用版和授权版功能上没有任何差异，只是会在 PDF 的第一页加上 PrinceXML 的 LOGO（业界良心）。如果你觉得 LOGO 有违观瞻，可以把它删掉。删除的方法我想对于充满智慧的你应该不是问题。
生成的 PDF 文件保存在 ./build/pdf/ 文件夹中。
生成 PDF 文件的过程中，会在 ./tmp/pdf/ 文件夹中生成一个临时文件，PDF 文件就是由这个临时文件生成的。默认情况下不会删除这个临时文件，以便调试。
写好文稿之后，如果想生成 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。如果没有安装，直接跳过验证。
mobi 格式电子书使用 kindlegen 生成，在此之前要先生成 ePub 格式。
$ persie build mobi # 生成样章 $ persie build mobi -s
生成的 ePub 文件保存在 ./build/mobi/ 文件夹中。
persie 支持生成两种静态 HTML：单文件和多文件。单文件是整本书都在一个文件中显示，多文件一章一个文件。
# 生成多文件 $ persie build html # 生成多文件 $ persie build html -m
生成的单文件在 ./build/html/single/ 文件夹中。生成的多文件在 ./build/html/multiple/ 文件夹中。
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 文件中生成上面列出的所有设置。如果需要某项设置，可以自己添加。修改设置时要注意，头部不能含有空行。
各设置的作用详述如下。
设置项作用备注
:author:
作者姓名
选填
:email:
作者的电子邮件地址
选填
:translator:
译者姓名
选填
:translator-email:
译者的电子邮件地址
选填
:author-label:
titlepage 显示的作者信息格式
选填
:translator-label:
titlepage 显示的译者信息格式
选填
设置项作用备注
:revnumber:
版本号，或者修订历史版本号
选填
:revdate:
该版本的发布日期，使用 ISO8601 格式
选填，如果不指定，则使用当前日期
:version-label:
显示在版本号前的文字，例如“v”或“rev”
选填
这些设置项主要用于设置 HTML 的元信息。
设置项作用备注
:lang:
书写文稿的语言，用于设定 <html> 标签的 lang 属性，以及 ePub 文件的 dc:language 元信息
选填，默认值为 en
:description:
书籍内容简介，用于设定 description元标签，以及 ePub 文件的 dc:description 元信息
选填
:keywords:
书籍内容的关键词，用于设定 keywords 元标签，以及 ePub 文件的 dc:subject 元信息
选填
设置项作用备注
:toc:
是否显示目录
这是布尔值选项，没有值。如果需要真值，直接写 :toc:；需要假值，写成 :toc!:
:toclevels:
显示几级目录
选填，默认显示 2 级
:toc-title:
目录页的标题
选填，默认值是“Table of Contents”
自动编号涉及到章节、图片、代码清单和表格等。
设置项作用备注
:numbered:
开启所有自动排序
如要关闭，使用 :numbered!:
:sectnumlevels:
自动排序到哪一级小节
默认为第 3 级，例如“1.2.3 节”
设置项作用备注
:listing-caption:
代码清单标题的标签格式
:image-caption:
图片标题的标签格式
:table-caption:
表格标题的标签格式
:caption-append-space:
是否在标签后面加上空格
只对代码清单，图片和表格的标签有效
:chapter-caption:
章名的标签格式
:appendix-caption:
附录的标签格式
其中，前三项设置可以使用两种占位符：%NUM% 和 %SUBNUM%。前者表示所在章的编号，后者表示在这一章中的序号。
最后两项设置可以使用一种占位符：%NUM%，表示章或者附录的序号。章的序号使用阿拉伯数字，附录的序号使用大写英文字母。
这些设置是 ePub 格式专用的。
设置项作用备注
:uuid:
用于设置 ePub 文件的 dc:identifier元信息
创建项目时会自动生成
:isbn:
用于设置 ePub 文件的 dc:identifier元信息
选填
:epub-identifier-scheme
dc:identifier 元信息使用哪种机制
可选值：uuid 或 isbn