Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Added BUILD.md and a picture of the process.
- Loading branch information
Dave Cross
committed
Jan 7, 2016
1 parent
d4964d9
commit dfc0909
Showing
2 changed files
with
113 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,113 @@ | ||
# How to turn these files into a book | ||
|
||
This repostitory contains a Makefile which you can use to turn a set of | ||
chapters written in [Markdown](https://daringfireball.net/projects/markdown/) | ||
into various other formats. | ||
|
||
In order to do that you will need various other tools installed. This file | ||
explains which tools are required, what they are required for and how to get | ||
them. | ||
|
||
## Make | ||
|
||
[Make](https://en.wikipedia.org/wiki/Make_%28software%29) is the standard Unix | ||
tool for controlling how to build files from other files. If you're using a | ||
system based on Unix (that includes Linux, BSD and OSX) then you will almost | ||
certainly alread have Make installed. If you're using Windows, then I think | ||
that Microsoft have a similar tool called `nmake` which you can almost | ||
certainly download from one of their many web sites. | ||
|
||
## Pandoc | ||
|
||
The first file that we need to generate is the | ||
[EPUB](https://en.wikipedia.org/wiki/EPUB) version of the book. And for that | ||
we use a tool called [Pandoc](http://pandoc.org/). This almost certainly | ||
won't already be installed on your system. | ||
|
||
For Linux users, Pandoc will be available in your system's package repository. | ||
If you're using a RedHat/Fedora/Centos system you can install it with `sudo | ||
install pandoc`. For a Debian/Ubuntu system, the equivalent command is `sudo | ||
apt-get install pandoc`. If you're using any other kind of Linux then I'm sure | ||
you're clever enough to work out the equivalent command. | ||
|
||
For OSX and Windows users, there are installable packages of the latest | ||
version of Pandoc available from their | ||
[Github repository](https://github.com/jgm/pandoc/releases/latest). Simply | ||
download the correct file and double-click it. | ||
|
||
Once you have Make and Pandoc installed, you can build an EPUB of the book by | ||
opening a terminal, changing to the directory where you have checked out a | ||
copy of this repository and typing: | ||
|
||
make epub | ||
|
||
Or, even, just: | ||
|
||
make | ||
|
||
You will end up with a file called perlwebbook.epub which can be used in many | ||
ebook systems. | ||
|
||
## Kindlegen | ||
|
||
If you want to generate a copy of the book which you can read on an Amazon | ||
Kindle, then you need to go a step further and generate a | ||
[MOBI](https://en.wikipedia.org/wiki/Mobipocket) version of the file. We do | ||
this using a program called Kindlegen which Amazon makes available for many | ||
different platforms. You can download the program | ||
[from their web site](http://www.amazon.com/gp/feature.html?docId=1000765211). | ||
|
||
Once you have installed Kindlegen, you can generate your MOBI file by opening | ||
a terminal, changing to the directory where you have checked out a copy of | ||
this repository and typing: | ||
|
||
make mobi | ||
|
||
**Note:** The MOBI is generated by converting the EPUB. So running `make mobi` | ||
will automatically run `make epub` first, which means that you will also need | ||
to install Pandoc as described above. | ||
|
||
## Calibre | ||
|
||
Sometimes you don't want a real ebook version of the book. Sometimes just a | ||
[PDF](https://en.wikipedia.org/wiki/Portable_Document_Format) is enough. So | ||
our Make system supports building a PDF too. | ||
|
||
Building a PDF uses another tool called [Calibre](http://calibre-ebook.com/) | ||
which you will need to install if you want to make a PDF. | ||
|
||
For Linux users, Calibre will be available in your system's package repository. | ||
If you're using a RedHat/Fedora/Centos system you can install it with `sudo | ||
install calibre`. For a Debian/Ubuntu system, the equivalent command is `sudo | ||
apt-get install calibre`. If you're using any other kind of Linux then I'm | ||
sure you're clever enough to work out the equivalent command, | ||
|
||
For OSX and Windows users, there are installable packages of the latest | ||
version of Calibre available from their | ||
[web site](http://calibre-ebook.com/download). Simply download the correct | ||
file and double-click it. | ||
|
||
Once you have Calibre installed, you can build a PDF of the book by opening | ||
a terminal, changing to the directory where you have checked out a copy of | ||
this repository and typing: | ||
|
||
make pdf | ||
|
||
**Note:** The PDF is generated by converting the EPUB. So running `make mobi` | ||
will automatically run `make epub` first, which means that you will also need | ||
to install Pandoc as described above. | ||
|
||
## Conversion Process | ||
|
||
This section summarises the software needed to convert the input files into | ||
various output files. | ||
|
||
* This repository contains the book's sources in Markdown format. | ||
* An EPUB is created from the Markdown using Pandoc | ||
* A MOBI is created from the EPUB using Kindlegen | ||
* A PDF is created from the EPUB using Calibre | ||
|
||
Putting it all together, it looks like this (ebook_convert is the command | ||
line program that we use from the Calibre package): | ||
|
||
![Conversion Process](https://raw.githubusercontent.com/davorg/perlwebbook/master/converters.png) |
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.