Added epub.md, getting-started.md to docs.
These used to live in the website repo.
This commit is contained in:
John MacFarlane
parent
59f537c31f
commit
1c85a158f3
2 changed files with 470 additions and 0 deletions
156
doc/epub.md
Normal file
156
doc/epub.md
Normal file
|
|
@ -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
|
||||
|
||||
314
doc/getting-started.md
Normal file
314
doc/getting-started.md
Normal file
|
|
@ -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.
|
||||
|
||||
Loading…
Reference in a new issue