diff --git a/BUILD.md b/BUILD.md new file mode 100644 index 0000000..e5e9064 --- /dev/null +++ b/BUILD.md @@ -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) diff --git a/converters.png b/converters.png new file mode 100644 index 0000000..a6dd68f Binary files /dev/null and b/converters.png differ