Yesterday I launched my new book, The Profitable Side Project Handbook. The launch went really well, I’ve already had some lovely feedback, and I’ll be writing about some of the things I learned while self-publishing and marketing my own book, over the next few weeks.

昨天我发布了我的新书， 《获利的项目合作手册》 。 发布会非常顺利，我已经收到了一些不错的反馈，并且在接下来的几周中，我将撰写一些关于在我自己出版和营销自己的书时学到的东西。

This post is about the baffling world of ebook formats, and what I learned while wrangling my book into shape. Partly so I remember next time I need to build a revision, but also because this stuff took me some time to figure out, and if it helps someone else that would be excellent. If you have also been through this, or know about converting from other formats, please add your advice in the comments.

这篇文章是关于令人困惑的电子书格式世界，以及我在整理书本时学到的知识。 在某种程度上，我记得下次需要构建一个修订版，也因为这东西花了我一些时间弄清楚，并且它是否对其他人很有帮助。 如果您也曾经经历过此操作，或者知道如何从其他格式转换，请在注释中添加您的建议。

写书 (Writing the book)

I wrote the first draft in Scrivener. I really like Scrivener, in particular for work like this that consists of lots of different sections. I could work on whichever section took my fancy each day. This is a great way to prevent any writer’s block or to save procrastination due to things that needed more research before writing. I made the decision to not get distracted by formatting issues while I was writing, and just to focus on the words.

我在Scrivener中写了初稿。 我真的很喜欢Scrivener，尤其是对于像这样的工作来说，它包含许多不同的部分。 我可以从事每天喜欢的任何部分的工作。 这是防止任何作者受阻或节省因编写之前需要更多研究而导致的拖延的好方法。 我决定不要在写作时因格式化问题而分心，而只是专注于文字。

Having created a first draft I used the compilation functionality in Scrivener to send a first draft to contributors and people who were reviewing the book, and then made any changes in Scrivener. It was at this point that all the fun started.

创建了初稿后，我使用了Scrivener中的编译功能将初稿发送给正在阅读本书的撰稿人和人员，然后对Scrivener进行了任何更改。 正是在这一点上，所有的乐趣开始了。

电子书的格式 (Formats for ebooks)

The formats that you would ideally create for ebooks are PDF, EPUB – used by devices such as the iPad, and MOBI – used by the Kindle. While it is possible to just read a PDF on various devices, it isn’t as a nice an experience than a proper ebook format. As my book is text heavy, I wanted to give people a good experience on each device.

您理想地为电子书创建的格式是PDF ， EPUB （由iPad等设备使用）和MOBI （由Kindle使用）。 尽管可以在各种设备上阅读PDF ，但它不是一种比适当的电子书格式更好的体验。 由于我的书内容繁重，因此我想给人们在每种设备上的良好体验。

格式化一次，到处发布 (Format once, publish everywhere)

Something that I see as a huge benefit of self-publishing in digital only format it the ability to make corrections. If I spot issues, or the landscape for something I mention in the book changes dramatically then I want to be able to create an update and send it out to purchasers – rather than maintaining an errata list as you would do with a physical book. I wanted to ensure that in creating multiple formats I didn’t make it impossible to easily rebuild an updated book.

我认为仅以数字格式自我发布的巨大好处是可以进行更正。 如果发现问题，或者书中提到的内容发生了很大变化，那么我希望能够创建一个更新并将其发送给购买者-而不是像使用实体书那样维护勘误表。 我想确保在创建多种格式时，我不会无法轻松地重建更新的书。

Scrivener can output to HTML, and the EPUB and MOBI formats are HTML, so it made sense to compile my book as an HTML document and work from there, finding a way to create all three formats out of the HTML. I could then keep my HTML copy in source control, make any changes as I needed to and rebuild the book formats when I felt an update was required.

代书可以输出到HTML和EPUB和MOBI格式是HTML，所以它是有意义的编译：我的书在那里的HTML文档和工作，寻找一种方法来创建所有三种格式了HTML的。 然后，我可以将HTML副本保留在源代码管理中，根据需要进行任何更改，并在需要更新时重建书籍格式。

前往EPUB (Getting to EPUB)

I tackled EPUB first, I had read a post on the Puppetlabs site about how they created the formats for their ebook. This led me to pandoc, an excellent document converter that can transform a number of formats into other formats.

我首先接触了EPUB ，我在Puppetlabs网站上阅读了一篇有关他们如何为电子书创建格式的文章。 这使我想到了pandoc ，这是一个出色的文档转换器，可以将多种格式转换为其他格式。

Pandoc is a commandline tool. It is very simple to use, download the package for your system and install it.

Pandoc是一个命令行工具。 使用非常简单，下载适合您系统的软件包并安装它。

Pandoc will use your HTML (or Markdown) heading levels to create the chapters and outline for your book. Level 1 headings will become chapters. Pandoc can then create you a table of contents for the epub, displaying your tree as deep as you like. This means that you need to make sure that your document is well structured in your HTML or Markdown.

Pandoc将使用您的HTML （或Markdown）标题级别来创建书籍的章节和大纲。 1级标题将成为各章。 然后Pandoc可以为您创建epub的目录，并根据需要显示您的树。 这意味着您需要确保文档在HTML或Markdown中的结构合理。

Inside the folder where your book HTML is you can also add a cover image, CSS to style the book and a metadata xml file, this file needs to include the following.

在您的书籍HTML所在的文件夹内，您还可以添加封面图像，用于对书籍进行样式设置的CSS和元数据xml文件，该文件需要包含以下内容。

<dc:title id="t1">The Profitable Side Project Handbook</dc:title><dc:language>en-GB</dc:language><dc:creator opf:file-as="Andrew, Rachel" opf:role="aut">Rachel Andrew</dc:creator><dc:publisher>Rachel Andrew</dc:publisher><dc:date opf:event="publication">2014-01-06</dc:date><dc:rights>Copyright ©2004 by Rachel Andrew</dc:rights>
<dc:title id="t1">The Profitable Side Project Handbook</dc:title><dc:language>en-GB</dc:language><dc:creator opf:file-as="Andrew, Rachel" opf:role="aut">Rachel Andrew</dc:creator><dc:publisher>Rachel Andrew</dc:publisher><dc:date opf:event="publication">2014-01-06</dc:date><dc:rights>Copyright ©2004 by Rachel Andrew</dc:rights>
 

You can then build your book by opening a terminal window, changing to your book directory and running the following command.

然后，您可以通过打开终端窗口，更改到书籍目录并运行以下命令来构建书籍。

pandoc -o book.epub book.html —epub-metadata=metadata.xml
—toc —toc-depth=2 —epub-stylesheet=book.css —epub-cover-image=cover.png

pandoc -o book.epub book.html —epub-metadata = metadata.xml
-toc -toc-depth = 2 -epub-stylesheet = book.css -epub-cover-image = cover.png

You should then end up with an EPUB that you can open up in iBooks or any other reader that supports this format. A couple of things to note.

然后，您应该获得一个EPUB ，可以在iBooks或任何其他支持此格式的阅读器中打开它。 需要注意的几件事。

I encountered a bug in pandoc where it did not read my custom CSS file, I found a discussion on this and it seems that this is a bug and if you run into it, adding your CSS file named epub.css into a hidden directory .pandoc in my home folder (I had to create this directory) fixes the issue.

我在pandoc中遇到了一个错误，该错误没有读取我的自定义CSS文件， 我对此进行了讨论 ，这似乎是一个错误，如果您遇到它，请将名为epub.css的CSS文件添加到隐藏目录中。我的主文件夹（我必须创建此目录）中的pandoc解决了该问题。

The second issue becomes a problem in the next stage, in that if you have a title in your HTML document as well as in the meta xml file, you get two titles and creating your MOBI will fail. I just removed the title from the HTML document.

第二个问题在下一阶段成为一个问题，因为如果您在HTML文档以及meta xml文件中都有标题，则会获得两个标题，并且创建MOBI将会失败。 我刚刚从HTML文档中删除了标题。

It is worth reading the full breakdown of commands on the Puppetlabs post as they do a great job of explaining everything.

值得阅读Puppetlabs帖子上的命令的完整分类，因为它们在解释所有内容方面做得很好。

If you are having issues or just want to poke around your EPUB, then it is simply an archive with .epub extension. I found that BetterZip on the Mac allowed me to open the archive and have a look at the contents. I have seen suggestions that some tools will require you to change the extension to .zip before they will open it.

如果您遇到问题或只是想在EPUB周围闲逛，那么它只是一个扩展名为.epub的存档。 我发现Mac上的BetterZip允许我打开存档并查看内容。 我已经看到建议，某些工具将要求您先将扩展名更改为.zip，然后再打开。

制作MOBI (Making a MOBI)

This next step is easy once you have your epub. Download the KindleGen tool from Amazon. It is another command line tool but you are there already, so you may as well continue.

拥有epub后，下一步很容易。 从亚马逊下载KindleGen工具 。 它是另一个命令行工具，但是您已经在那儿了，所以您最好继续。

I unpacked the archive and placed the KindleGen tool into /usr/local/bin on my Mac which should work for you if you are also on a Mac.

我解压缩了档案并将KindleGen工具放到Mac上的/ usr / local / bin中，如果您也在Mac上，它应该也可以使用。

Back on the command line, still in my folder run the KindleGen command:

返回命令行，仍然在我的文件夹中运行KindleGen命令：

kindlegen book.epub

kindlegen book.epub

As if by magic a MOBI file appears! The only issue I had was with my duplicate titles as mentioned above, however the error messaging from the KindleGen tool was pretty good and I was able to figure out the issue.

仿佛是魔术般出现了一个MOBI文件！ 我唯一遇到的问题是如上所述的重复标题，但是KindleGen工具发出的错误消息非常好，我能够找出问题所在。

If you are hitting up against errors then the first thing to check would be that your epub file is valid. I used a tool called FlightCrew which is basic, but does the job.

如果您遇到错误，那么首先要检查的是您的epub文件有效。 我使用了一个称为FlightCrew的工具，该工具很基本，但是可以完成工作。

I should note that the less you mess about with formatting for the Kindle the better. I eventually ended up using different stylesheets for the EPUB that I shipped and for the EPUB I used to create the MOBI. The Kindle does a pretty nice job of making readable books, the less we mess with it the better.

我应该注意，您对Kindle格式的了解越少越好。 最终，我最终为出厂的EPUB和用于创建MOBI的EPUB使用了不同的样式表。 Kindle在制作可读书籍方面做得非常好，越不喜欢它，就越好。

PDF文件 (The PDF)

I had thought that the previous two formats would be the difficult ones, however going from HTML into other HTML formats is not so tricky. My troubles really began when I tried to create a PDF.

我以为前面的两种格式会比较困难，但是从HTML转换为其他HTML格式并不是那么棘手。 当我尝试创建PDF时，我的麻烦才真正开始。

Pandoc can generate a PDF, however to style it you need to use LaTex which I really didn’t want to have to get into when I already had a nice looking HTML document styled with CSS.

Pandoc可以生成PDF ，但是要设置其样式，您需要使用LaTex，当我已经拥有使用CSS样式的漂亮HTML文档时，我真的不想进入。

I had read the article on How to write a book by Jonathan Snook on how he was using the commercial, and rather expensive, Prince software to generate his book. Prince looked like a great option but I saw in the comments there were other tools available. As my book was all text – no images or code to worry about – surely a basic tool could do the job.

我已经阅读了乔纳森·斯努克（Jonathan Snook） 撰写的有关如何写书的文章，内容涉及他如何使用商业的，相当昂贵的Prince软件来生成书。 Prince看起来是一个不错的选择，但我在评论中看到还有其他可用的工具。 由于我的书全是文本-不用担心图像或代码-肯定有一个基本工具可以完成这项工作。

I installed wkhtmltopdf a tool that uses webkit to convert HTML pages to PDF. The OS X version doesn’t use libraries that would enable the generation of page number or a table of contents so I ended up building my own TOC in HTML first (I actually opened up the EPUB, grabbed the one that had been generated and fixed the links).

我安装了wkhtmltopdf这个工具，该工具使用webkit将HTML页面转换为PDF 。 OS X版本不使用能够生成页码或目录表的库，因此我最终首先用HTML构建自己的目录 （我实际上打开了EPUB ，抓住了已生成并修复的EPUB ，链接）。

If you want to try wkhtmltopdf yourself then installation is straightforward and it is another commandline tool. On the Mac to run it, change into the wkhtmltopdf directory:

如果您想自己尝试wkhtmltopdf，那么安装非常简单，这是另一个命令行工具。 在Mac上运行它，进入wkhtmltopdf目录：

cd /Applications/wkhtmltopdf.app/Contents/MacOS/

cd /Applications/wkhtmltopdf.app/Contents/MacOS/

Then run it:

然后运行它：

./wkhtmltopdf -B 30mm -T 20mm /Users/rachel/path_to_book/book.html /Users/rachel/path_to_book/book.pdf

./wkhtmltopdf -B 30mm -T 20mm /Users/rachel/path_to_book/book.html /Users/rachel/path_to_book/book.pdf

You will get a PDF of your book. The user manual for wkhtmltopdf explains the options, such as the -B for margin-bottom and -T for margin-top as used in my command above.

您将获得书籍的PDF 。 wkhtmltopdf的用户手册说明了这些选项，例如上面我的命令中使用的-B表示margin-bottom，-T表示margin-top。

WTF ！ (WTF!)

This all seemed to be working nicely enough, until I realised that the PDF that was being generated was 180MB. I tried some options, tried to compress the PDF via various means, with no results. A quick Google confirmed I was not the only person with this issue.

在我意识到所生成的PDF为180MB之前，这一切似乎都工作得很好。 我尝试了一些选项，尝试通过各种方式压缩PDF ，但没有结果。 快速的Google确认我不是唯一遇到此问题的人。

The problem seemed unresolvable, it was Sunday night and I wanted to launch Monday morning. The book was ready and I was going to be held up by a PDF. Suddenly that expensive bit of software didn’t seem so bad! I downloaded the non-profit version that adds a logo just to check that Prince would solve the issue.

这个问题似乎无法解决，那是在周日晚上，我想在周一早上启动。 这本书已经准备好了，我将被PDF保留。 突然之间，昂贵的软件似乎还不错！ 我下载了添加徽标的非盈利版本，目的只是为了检查Prince是否可以解决该问题。

Prince is also a commandline tool on the Mac but is essentially a drop-in replacement for wkhtmltopdf. Download it, install it then run:

Prince也是Mac上的命令行工具，但实际上是wkhtmltopdf的直接替代品。 下载它，安装并运行：

prince book.html -o book.pdf

王子book.html -o book.pdf

A non-giant PDF will appear! Having confirmed it would work I then purchased a license, the site does not deliver licenses immediately so I was faced with a 48 hour delay. Knowing that Jonathan Snook had a copy I send him a begging email to see if he would generate my PDF for me, which he very kindly did.

非巨型PDF将会出现！ 确认可以使用后，我购买了许可证，但该站点无法立即交付许可证，因此我面临48小时的延迟。 我知道乔纳森·斯努克（Jonathan Snook）有副本，所以给他寄了一封乞讨电子邮件，看他是否会为我生成我的PDF ，他非常乐意这样做。

Jonathan also helped me out with a CSS snippet that would create numbering and improved page sizes in my PDF, as my license for Prince came through overnight I was able to quickly rebuild the PDF to take advantage of that before launching the book. I can recommend the A List Apart article Building Books with CSS if you are using Prince and want to take advantage of the Paged Media spec that Prince supports.

乔纳森（Jonathan）还提供了一个CSS代码段，该代码段可在我的PDF中创建编号并改善页面大小，因为我的Prince许可证一夜之间就得以实现，因此我能够快速重建PDF以利用它，然后再发行本书。 如果您正在使用Prince，并且想利用Prince支持的Paged Media规范，我可以推荐A List Apart文章“使用CSS构建书籍” 。

I hope that is all useful to anyone else searching for answers. Jonathan takes a slightly different approach in his 24 ways article, so that is another useful resource.

我希望这对其他寻求答案的人都是有用的。 乔纳森（Jonathan） 在其24种方式的文章中采用了略有不同的方法，因此这是另一种有用的资源。

If you have also worked through this issue let me know in the comments any useful tips you might have to share.

如果您还解决了此问题，请在评论中让我知道您可能需要分享的任何有用的提示。