diff options
Diffstat (limited to 'doc/epub.md')
| -rw-r--r-- | doc/epub.md | 156 |
1 files changed, 156 insertions, 0 deletions
diff --git a/doc/epub.md b/doc/epub.md new file mode 100644 index 000000000..c5993cd42 --- /dev/null +++ b/doc/epub.md @@ -0,0 +1,156 @@ +--- +title: Creating an ebook with pandoc +author: John MacFarlane +--- + +Starting with version 1.6, pandoc can produce output in the [EPUB] +electronic book format. EPUB books can be viewed on iPads, Nooks, and +other electronic book readers, including many smart phones. (They can +also be converted to Kindle books using [KindleGen].) + +This means that it's now very easy to produce an electronic book! +Let's try it. + +# A toy example + +Use your text editor to create a file `mybook.txt`, with the following +contents: + + % My Book + % Sam Smith + + This is my book! + + # Chapter One + + Chapter one is over. + + # Chapter Two + + Chapter two has just begun. + +To make this into an ebook takes only one command: + + pandoc mybook.txt -o mybook.epub + +You can upload `mybook.epub` to your ebook reader and try it out. + +Note that if your markdown file contains links to local images, for +example + +  + +pandoc will automatically include the images in the generated +epub. + +# A real book + +To see what this would look like for a real book, let's convert Scott +Chacon's book [Pro Git], which he wrote using pandoc's markdown variant +and released under a [Creative Commons] license. (If you use the book, +please consider [buying a copy] to help support his excellent work.) + +You can find the markdown source for the book on its +[github site]. Let's get a copy of the whole repository:[^1] + + git clone http://github.com/progit/progit.git + +[^1]: If you don't have [git], you can browse to the [github site] and +click "Download Source" to get the same files in a zip or tar archive. + +This command will create a working directory called `progit` on +your machine. The actual markdown sources for the English version +of the book are in the `en` subdirectory, so start by changing +to that directory: + + cd progit/en + +As you can see, each chapter is a single text file in its own directory. +Chacon does some postprocessing on these files, for example, to insert images. +This is a placeholder for Figure 1-1, for example: + + Insert 18333fig0101.png + Figure 1-1. Local version control diagram. + +The actual image file is called `18333fig0101-tn.png` and lives in +the `figures` subdirectory of the repository, as you can verify. + +For demonstration purposes, we want pure markdown files, so let's +change this placeholder into a markdown image link. Pandoc will +treat a paragraph containing a single image as a figure with +a caption, which is what we want: + +  + +We can make this change in all the files with a perl one-liner: + + perl -i -0pe \ + 's/^Insert\s*(.*)\.png\s*\n([^\n]*)$/!\[\2](..\/figures\/\1-tn.png)/mg' \ + */*.markdown + +This will modify the files in place. (We won't worry about backing +them up; if we mess up, we can get the original files back with +`git reset --hard`.) + +OK! Now we're almost ready to make an ebook. We have the chapters, +each in its own file, but we still need a title. Create a file, +`title.txt`, with a pandoc YAML metadata block: + +``` +--- +title: Pro Git +author: Scott Chacon +rights: Creative Commons Non-Commercial Share Alike 3.0 +language: en-US +... +``` + +See the [User's Guide](MANUAL.html#epub-metadata) for more information +above these fields. + +Now run pandoc to make the ebook, using our title page and modified +chapter files as sources: + + pandoc -S -o progit.epub title.txt \ + 01-introduction/01-chapter1.markdown \ + 02-git-basics/01-chapter2.markdown \ + 03-git-branching/01-chapter3.markdown \ + 04-git-server/01-chapter4.markdown \ + 05-distributed-git/01-chapter5.markdown \ + 06-git-tools/01-chapter6.markdown \ + 07-customizing-git/01-chapter7.markdown \ + 08-git-and-other-scms/01-chapter8.markdown \ + 09-git-internals/01-chapter9.markdown + +That's it! The ebook, `progit.epub`, is ready to be uploaded to your reader. + +## Changing the format + +You can use the `--css` option to specify a CSS file +for the book. The default CSS is minimal and can be found +[on GitHub](https://github.com/jgm/pandoc/blob/master/data/epub.css) +or in the `epub.css` file in your data directory +(see `--data-dir` in the [User's Guide]). + +You can even embed fonts in the EPUB if you want; see the [User's Guide] +under `--epub-embed-font` for instructions. + +## Math + +Pandoc has an EPUB3 writer. It renders LaTeX math into MathML, which +EPUB3 readers are supposed to support (but unfortunately few do). + +Of course, this isn't much help if you want EPUB2 output (`pandoc -t epub2`) +or target readers that don't support MathML. Then you should try using the +`--webtex` option, which will use a web service to convert the TeX to an image. + +[KindleGen]: http://www.amazon.com/gp/feature.html?ie=UTF8&docId=1000234621 +[EPUB]: http://en.wikipedia.org/wiki/EPUB +[Pro Git]: http://progit.org/ +[Creative Commons]: http://creativecommons.org/ +[buying a copy]: http://progit.org/ +[github site]: http://github.com/progit/progit +[git]: http://git-scm.com +[Dublin Core metadata elements]: http://dublincore.org/documents/dces/ +[User's Guide]: MANUAL.html + |