diff options
| -rw-r--r-- | doc/epub.md | 156 | ||||
| -rw-r--r-- | doc/getting-started.md | 314 |
2 files changed, 470 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 + diff --git a/doc/getting-started.md b/doc/getting-started.md new file mode 100644 index 000000000..4134a61a2 --- /dev/null +++ b/doc/getting-started.md @@ -0,0 +1,314 @@ +--- +title: Getting started with pandoc +author: John MacFarlane +--- + +This document is for people who are unfamiliar with command line +tools. Command-line experts can go straight to the [User's +Guide](README.html) or the pandoc man page. + +# Step 1: Install pandoc + +First, install pandoc, following the [instructions for +your platform](installing.html). + +# Step 2: Open a terminal + +Pandoc is a command-line tool. There is no graphic user interface. +So, to use it, you'll need to open a terminal window: + +- On OS X, the Terminal application can be found in + `/Applications/Utilities`. Open a Finder window and go to + `Applications`, then `Utilities`. Then double click on + `Terminal`. (Or, click the spotlight icon in the upper right + hand corner of your screen and type `Terminal` -- you should + see `Terminal` under `Applications`.) + +- On Windows, you can use either the classic command prompt or the + more modern PowerShell terminal. If you use Windows in desktop + mode, run the `cmd` or `powershell` command from the Start menu. + If you use the Windows 8 start screen instead, simply type + `cmd` or `powershell`, and then run either the "Command + Prompt" or "Windows Powershell" application. If you are using + `cmd`, type `chcp 65001` before using pandoc, to set the + encoding to UTF-8. + +- On Linux, there are many possible configurations, depending on + what desktop environment you're using: + + * In Unity, use the search function on the `Dash`, and search + for `Terminal`. Or, use the keyboard shortcut `Ctrl-Alt-T`. + * In Gnome, go to `Applications`, then `Accessories`, and + select `Terminal`, or use `Ctrl-Alt-T`. + * In XFCE, go to `Applications`, then `System`, then `Terminal`, + or use `Super-T`. + * In KDE, go to `KMenu`, then `System`, then `Terminal Program (Konsole)`. + +You should now see a rectangle with a "prompt" (possibly just a symbol +like `%`, but probably including more information, such as your +username and directory), and a blinking cursor. + +Let's verify that pandoc is installed. Type + + pandoc --version + +and hit enter. You should see a message telling you which version +of pandoc is installed, and giving you some additional information. + +# Step 3: Changing directories + +First, let's see where we are. Type + + pwd + +on linux or OSX, or + + echo %cd% + +on Windows, and hit enter. Your terminal should print your current +working directory. (Guess what `pwd` stands for?) This should be your +home directory. + +Let's navigate now to our `Documents` directory: type + + cd Documents + +and hit enter. Now type + + pwd + +(or `echo %cd%` on Windows) +again. You should be in the `Documents` subdirectory of your home +directory. To go back to your home directory, you could type + + cd .. + +The `..` means "one level up." + +Go back to your `Documents` directory if you're not there already. +Let's try creating a subdirectory called `pandoc-test`: + + mkdir pandoc-test + +Now change to the `pandoc-test` directory: + + cd pandoc-test + +If the prompt doesn't tell you what directory you're in, you can +confirm that you're there by doing + + pwd + +(or `echo %cd%`) again. + +OK, that's all you need to know for now about using the terminal. +But here's a secret that will save you a lot of typing. You can +always type the up-arrow key to go back through your history +of commands. So if you want to use a command you typed earlier, +you don't need to type it again: just use up-arrow until it comes +up. Try this. (You can use down-arrow as well, to go the other +direction.) Once you have the command, you can also use the +left and right arrows and the backspace/delete key to edit it. + +Most terminals also support tab completion of directories and +filenames. To try this, let's first go back up to our `Documents` +directory: + + cd .. + +Now, type + + cd pandoc- + +and hit the tab key instead of enter. Your terminal should fill +in the rest (`test`), and then you can hit enter. + +To review: + + - `pwd` (or `echo %cd%` on Windows) + to see what the current working directory is. + - `cd foo` to change to the `foo` subdirectory of your working + directory. + - `cd ..` to move up to the parent of the working directory. + - `mkdir foo` to create a subdirectory called `foo` in the + working directory. + - up-arrow to go back through your command history. + - tab to complete directories and file names. + +# Step 4: Using pandoc as a filter + +Type + + pandoc + +and hit enter. You should see the cursor just sitting there, waiting +for you to type something. Type this: + + Hello *pandoc*! + + - one + - two + +When you're finished (the cursor should be at the beginning of the line), +type `Ctrl-D` on OS X or Linux, or `Ctrl-Z` followed +by `Enter` on Windows. You should now see your text converted to HTML! + + <p>Hello <em>pandoc</em>!</p> + <ul> + <li>one</li> + <li>two</li> + </ul> + +What just happened? When pandoc is invoked without specifying any +input files, it operates as a "filter," taking input from the +terminal and sending its output back to the terminal. You can use +this feature to play around with pandoc. + +By default, input is interpreted as pandoc markdown, and output is +HTML. But we can change that. Let's try converting *from* HTML +*to* markdown: + + pandoc -f html -t markdown + +Now type: + + <p>Hello <em>pandoc</em>!</p> + +and hit `Ctrl-D` (or `Ctrl-Z` followed by `Enter` on Windows). +You should see: + + Hello *pandoc*! + +Now try converting something from markdown to LaTeX. What command +do you think you should use? + +# Step 5: Text editor basics + +You'll probably want to use pandoc to convert a file, not to read +text from the terminal. That's easy, but first we need to create +a text file in our `pandoc-test` subdirectory. + +**Important:** To create a text file, you'll need to use a text +editor, *not* a word processor like Microsoft Word. On Windows, you +can use Notepad (in `Accessories`). On OS X, you can use +`TextEdit` (in `Applications`). On Linux, different platforms come +with different text editors: Gnome has `GEdit`, and KDE has `Kate`. + +Start up your text editor. Type the following: + + # Test! + + This is a test of *pandoc*. + + - list one + - list two + +Now save your file as `test1.md` in the directory +`Documents/pandoc-test`. + +Note: If you use plain text a lot, you'll want a better editor than +`Notepad` or `TextEdit`. You might want to look at +[Sublime Text](http://www.sublimetext.com/) or (if you're willing +to put in some time learning an unfamiliar interface) +[Vim](http://www.vim.org) or [Emacs](http://www.gnu.org/software/emacs). + +# Step 6: Converting a file + +Go back to your terminal. We should still be in the +`Documents/pandoc-test` directory. Verify that with `pwd`. + +Now type + + ls + +(or `dir` if you're on Windows). +This will list the files in the current directory. You should see +the file you created, `test1.md`. + +To convert it to HTML, use this command: + + pandoc test1.md -f markdown -t html -s -o test1.html + +The filename `test1.md` tells pandoc which file to convert. +The `-s` option says to create a "standalone" file, with a header +and footer, not just a fragment. And the `-o test1.html` says +to put the output in the file `test1.html`. Note that we could +have omitted `-f markdown` and `-t html`, since the default +is to convert from markdown to HTML, but it doesn't hurt to +include them. + +Check that the file was created by typing `ls` again. You +should see `test1.html`. Now open this in a browser. On OS X, +you can type + + open test1.html + +On Windows, type + + .\test1.html + +You should see a browser window with your document. + +To create a LaTeX document, you just need to change the command +slightly: + + pandoc test1.md -f markdown -t latex -s -o test1.tex + +Try opening `test1.tex` in your text editor. + +Pandoc can often figure out the input and output formats from +the filename extensions. So, you could have just used: + + pandoc test1.md -s -o test1.tex + +Pandoc knows you're trying to create a LaTeX document, because of the +`.tex` extension. + +Now try creating a Word document (with extension `docx`). + +If you want to create a PDF, you'll need to have LaTeX installed. +(See [MacTeX](http://tug.org/mactex/) on OS X, +[MiKTeX](http://miktex.org) on Windows, or install the texlive +package in linux.) Then do + + pandoc test1.md -s -o test1.pdf + +# Step 7: Command-line options + +You now know the basics. Pandoc has a lot of options. At this point +you can start to learn more about them by reading the +[User's Guide](README.html). + +Here's an example. The `--mathml` option causes pandoc to +convert TeX math into MathML. Type + + pandoc --mathml + +then enter this text, followed by `Ctrl-D` (`Ctrl-Z` followed by +`Enter` on Windows): + + $x = y^2$ + +Now try the same thing without `--mathml`. See the difference +in output? + +If you forget an option, or forget which formats are supported, you +can always do + + pandoc --help + +to get a list of all the supported options. + +On OS X or Linux systems, you can also do + + man pandoc + +to get the pandoc manual page. All of this information is also +in the User's Guide. + +If you get stuck, you can always ask questions on the +[pandoc-discuss](http://groups.google.com/group/pandoc-discuss) +mailing list. But be sure to check the [FAQs](faqs.html) first, +and search through the mailing list to see if your question has +been answered before. + |