Skip to content

Commit

Permalink
Tidy BUILD.md
Browse files Browse the repository at this point in the history
  • Loading branch information
davorg committed Oct 3, 2015
1 parent 0670124 commit 1229d34
Showing 1 changed file with 59 additions and 44 deletions.
103 changes: 59 additions & 44 deletions BUILD.md
@@ -1,90 +1,105 @@
# How to turn these files into a book

In this repostitory, you will find the chapters written in
[Markdown](https://daringfireball.net/projects/markdown/). Markdown files are pretty readable, but
you may well want to convert the source files into other formats. There is a Makefile that you
can use you do thay, but you will need various other tools installed. This file explains which
tools are required, what they are required for and how o get them.
[Markdown](https://daringfireball.net/projects/markdown/). Markdown files are
pretty readable, but you may well want to convert the source files into other
formats. There is a Makefile that you can use you do thay, but you will need
various other tools installed. This file explains which tools are required,
what they are required for and how o 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.
[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
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 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.
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:
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.
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 an 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
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:
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.
**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.
[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.
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 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.
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:
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.
**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 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
Expand Down

0 comments on commit 1229d34

Please sign in to comment.