git.iko.soy/typeable/pandoc
on master help sign in
Added epub.md, getting-started.md to docs.
1c85a15John MacFarlane
doc/epub.mdnew file+156
compare with master
unifiedsplit
@@ -0,0 +1,156 @@
1+---
2+title: Creating an ebook with pandoc
3+author: John MacFarlane
4+---
5+
6+Starting with version 1.6, pandoc can produce output in the [EPUB]
7+electronic book format. EPUB books can be viewed on iPads, Nooks, and
8+other electronic book readers, including many smart phones. (They can
9+also be converted to Kindle books using [KindleGen].)
10+
11+This means that it's now very easy to produce an electronic book!
12+Let's try it.
13+
14+# A toy example
15+
16+Use your text editor to create a file `mybook.txt`, with the following
17+contents:
18+
19+ % My Book
20+ % Sam Smith
21+
22+ This is my book!
23+
24+ # Chapter One
25+
26+ Chapter one is over.
27+
28+ # Chapter Two
29+
30+ Chapter two has just begun.
31+
32+To make this into an ebook takes only one command:
33+
34+ pandoc mybook.txt -o mybook.epub
35+
36+You can upload `mybook.epub` to your ebook reader and try it out.
37+
38+Note that if your markdown file contains links to local images, for
39+example
40+
41+ ![Juliet](images/sun.jpg)
42+
43+pandoc will automatically include the images in the generated
44+epub.
45+
46+# A real book
47+
48+To see what this would look like for a real book, let's convert Scott
49+Chacon's book [Pro Git], which he wrote using pandoc's markdown variant
50+and released under a [Creative Commons] license. (If you use the book,
51+please consider [buying a copy] to help support his excellent work.)
52+
53+You can find the markdown source for the book on its
54+[github site]. Let's get a copy of the whole repository:[^1]
55+
56+ git clone http://github.com/progit/progit.git
57+
58+[^1]: If you don't have [git], you can browse to the [github site] and
59+click "Download Source" to get the same files in a zip or tar archive.
60+
61+This command will create a working directory called `progit` on
62+your machine. The actual markdown sources for the English version
63+of the book are in the `en` subdirectory, so start by changing
64+to that directory:
65+
66+ cd progit/en
67+
68+As you can see, each chapter is a single text file in its own directory.
69+Chacon does some postprocessing on these files, for example, to insert images.
70+This is a placeholder for Figure 1-1, for example:
71+
72+ Insert 18333fig0101.png
73+ Figure 1-1. Local version control diagram.
74+
75+The actual image file is called `18333fig0101-tn.png` and lives in
76+the `figures` subdirectory of the repository, as you can verify.
77+
78+For demonstration purposes, we want pure markdown files, so let's
79+change this placeholder into a markdown image link. Pandoc will
80+treat a paragraph containing a single image as a figure with
81+a caption, which is what we want:
82+
83+ ![Figure 1-1. Local version control diagram.](../figures/18333fig0101-tn.png)
84+
85+We can make this change in all the files with a perl one-liner:
86+
87+ perl -i -0pe \
88+ 's/^Insert\s*(.*)\.png\s*\n([^\n]*)$/!\[\2](..\/figures\/\1-tn.png)/mg' \
89+ */*.markdown
90+
91+This will modify the files in place. (We won't worry about backing
92+them up; if we mess up, we can get the original files back with
93+`git reset --hard`.)
94+
95+OK! Now we're almost ready to make an ebook. We have the chapters,
96+each in its own file, but we still need a title. Create a file,
97+`title.txt`, with a pandoc YAML metadata block:
98+
99+```
100+---
101+title: Pro Git
102+author: Scott Chacon
103+rights: Creative Commons Non-Commercial Share Alike 3.0
104+language: en-US
105+...
106+```
107+
108+See the [User's Guide](MANUAL.html#epub-metadata) for more information
109+above these fields.
110+
111+Now run pandoc to make the ebook, using our title page and modified
112+chapter files as sources:
113+
114+ pandoc -S -o progit.epub title.txt \
115+ 01-introduction/01-chapter1.markdown \
116+ 02-git-basics/01-chapter2.markdown \
117+ 03-git-branching/01-chapter3.markdown \
118+ 04-git-server/01-chapter4.markdown \
119+ 05-distributed-git/01-chapter5.markdown \
120+ 06-git-tools/01-chapter6.markdown \
121+ 07-customizing-git/01-chapter7.markdown \
122+ 08-git-and-other-scms/01-chapter8.markdown \
123+ 09-git-internals/01-chapter9.markdown
124+
125+That's it! The ebook, `progit.epub`, is ready to be uploaded to your reader.
126+
127+## Changing the format
128+
129+You can use the `--css` option to specify a CSS file
130+for the book. The default CSS is minimal and can be found
131+[on GitHub](https://github.com/jgm/pandoc/blob/master/data/epub.css)
132+or in the `epub.css` file in your data directory
133+(see `--data-dir` in the [User's Guide]).
134+
135+You can even embed fonts in the EPUB if you want; see the [User's Guide]
136+under `--epub-embed-font` for instructions.
137+
138+## Math
139+
140+Pandoc has an EPUB3 writer. It renders LaTeX math into MathML, which
141+EPUB3 readers are supposed to support (but unfortunately few do).
142+
143+Of course, this isn't much help if you want EPUB2 output (`pandoc -t epub2`)
144+or target readers that don't support MathML. Then you should try using the
145+`--webtex` option, which will use a web service to convert the TeX to an image.
146+
147+[KindleGen]: http://www.amazon.com/gp/feature.html?ie=UTF8&docId=1000234621
148+[EPUB]: http://en.wikipedia.org/wiki/EPUB
149+[Pro Git]: http://progit.org/
150+[Creative Commons]: http://creativecommons.org/
151+[buying a copy]: http://progit.org/
152+[github site]: http://github.com/progit/progit
153+[git]: http://git-scm.com
154+[Dublin Core metadata elements]: http://dublincore.org/documents/dces/
155+[User's Guide]: MANUAL.html
156+
doc/getting-started.mdnew file+314
@@ -0,0 +1,314 @@
1+---
2+title: Getting started with pandoc
3+author: John MacFarlane
4+---
5+
6+This document is for people who are unfamiliar with command line
7+tools. Command-line experts can go straight to the [User's
8+Guide](README.html) or the pandoc man page.
9+
10+# Step 1: Install pandoc
11+
12+First, install pandoc, following the [instructions for
13+your platform](installing.html).
14+
15+# Step 2: Open a terminal
16+
17+Pandoc is a command-line tool. There is no graphic user interface.
18+So, to use it, you'll need to open a terminal window:
19+
20+- On OS X, the Terminal application can be found in
21+ `/Applications/Utilities`. Open a Finder window and go to
22+ `Applications`, then `Utilities`. Then double click on
23+ `Terminal`. (Or, click the spotlight icon in the upper right
24+ hand corner of your screen and type `Terminal` -- you should
25+ see `Terminal` under `Applications`.)
26+
27+- On Windows, you can use either the classic command prompt or the
28+ more modern PowerShell terminal. If you use Windows in desktop
29+ mode, run the `cmd` or `powershell` command from the Start menu.
30+ If you use the Windows 8 start screen instead, simply type
31+ `cmd` or `powershell`, and then run either the "Command
32+ Prompt" or "Windows Powershell" application. If you are using
33+ `cmd`, type `chcp 65001` before using pandoc, to set the
34+ encoding to UTF-8.
35+
36+- On Linux, there are many possible configurations, depending on
37+ what desktop environment you're using:
38+
39+ * In Unity, use the search function on the `Dash`, and search
40+ for `Terminal`. Or, use the keyboard shortcut `Ctrl-Alt-T`.
41+ * In Gnome, go to `Applications`, then `Accessories`, and
42+ select `Terminal`, or use `Ctrl-Alt-T`.
43+ * In XFCE, go to `Applications`, then `System`, then `Terminal`,
44+ or use `Super-T`.
45+ * In KDE, go to `KMenu`, then `System`, then `Terminal Program (Konsole)`.
46+
47+You should now see a rectangle with a "prompt" (possibly just a symbol
48+like `%`, but probably including more information, such as your
49+username and directory), and a blinking cursor.
50+
51+Let's verify that pandoc is installed. Type
52+
53+ pandoc --version
54+
55+and hit enter. You should see a message telling you which version
56+of pandoc is installed, and giving you some additional information.
57+
58+# Step 3: Changing directories
59+
60+First, let's see where we are. Type
61+
62+ pwd
63+
64+on linux or OSX, or
65+
66+ echo %cd%
67+
68+on Windows, and hit enter. Your terminal should print your current
69+working directory. (Guess what `pwd` stands for?) This should be your
70+home directory.
71+
72+Let's navigate now to our `Documents` directory: type
73+
74+ cd Documents
75+
76+and hit enter. Now type
77+
78+ pwd
79+
80+(or `echo %cd%` on Windows)
81+again. You should be in the `Documents` subdirectory of your home
82+directory. To go back to your home directory, you could type
83+
84+ cd ..
85+
86+The `..` means "one level up."
87+
88+Go back to your `Documents` directory if you're not there already.
89+Let's try creating a subdirectory called `pandoc-test`:
90+
91+ mkdir pandoc-test
92+
93+Now change to the `pandoc-test` directory:
94+
95+ cd pandoc-test
96+
97+If the prompt doesn't tell you what directory you're in, you can
98+confirm that you're there by doing
99+
100+ pwd
101+
102+(or `echo %cd%`) again.
103+
104+OK, that's all you need to know for now about using the terminal.
105+But here's a secret that will save you a lot of typing. You can
106+always type the up-arrow key to go back through your history
107+of commands. So if you want to use a command you typed earlier,
108+you don't need to type it again: just use up-arrow until it comes
109+up. Try this. (You can use down-arrow as well, to go the other
110+direction.) Once you have the command, you can also use the
111+left and right arrows and the backspace/delete key to edit it.
112+
113+Most terminals also support tab completion of directories and
114+filenames. To try this, let's first go back up to our `Documents`
115+directory:
116+
117+ cd ..
118+
119+Now, type
120+
121+ cd pandoc-
122+
123+and hit the tab key instead of enter. Your terminal should fill
124+in the rest (`test`), and then you can hit enter.
125+
126+To review:
127+
128+ - `pwd` (or `echo %cd%` on Windows)
129+ to see what the current working directory is.
130+ - `cd foo` to change to the `foo` subdirectory of your working
131+ directory.
132+ - `cd ..` to move up to the parent of the working directory.
133+ - `mkdir foo` to create a subdirectory called `foo` in the
134+ working directory.
135+ - up-arrow to go back through your command history.
136+ - tab to complete directories and file names.
137+
138+# Step 4: Using pandoc as a filter
139+
140+Type
141+
142+ pandoc
143+
144+and hit enter. You should see the cursor just sitting there, waiting
145+for you to type something. Type this:
146+
147+ Hello *pandoc*!
148+
149+ - one
150+ - two
151+
152+When you're finished (the cursor should be at the beginning of the line),
153+type `Ctrl-D` on OS X or Linux, or `Ctrl-Z` followed
154+by `Enter` on Windows. You should now see your text converted to HTML!
155+
156+ <p>Hello <em>pandoc</em>!</p>
157+ <ul>
158+ <li>one</li>
159+ <li>two</li>
160+ </ul>
161+
162+What just happened? When pandoc is invoked without specifying any
163+input files, it operates as a "filter," taking input from the
164+terminal and sending its output back to the terminal. You can use
165+this feature to play around with pandoc.
166+
167+By default, input is interpreted as pandoc markdown, and output is
168+HTML. But we can change that. Let's try converting *from* HTML
169+*to* markdown:
170+
171+ pandoc -f html -t markdown
172+
173+Now type:
174+
175+ <p>Hello <em>pandoc</em>!</p>
176+
177+and hit `Ctrl-D` (or `Ctrl-Z` followed by `Enter` on Windows).
178+You should see:
179+
180+ Hello *pandoc*!
181+
182+Now try converting something from markdown to LaTeX. What command
183+do you think you should use?
184+
185+# Step 5: Text editor basics
186+
187+You'll probably want to use pandoc to convert a file, not to read
188+text from the terminal. That's easy, but first we need to create
189+a text file in our `pandoc-test` subdirectory.
190+
191+**Important:** To create a text file, you'll need to use a text
192+editor, *not* a word processor like Microsoft Word. On Windows, you
193+can use Notepad (in `Accessories`). On OS X, you can use
194+`TextEdit` (in `Applications`). On Linux, different platforms come
195+with different text editors: Gnome has `GEdit`, and KDE has `Kate`.
196+
197+Start up your text editor. Type the following:
198+
199+ # Test!
200+
201+ This is a test of *pandoc*.
202+
203+ - list one
204+ - list two
205+
206+Now save your file as `test1.md` in the directory
207+`Documents/pandoc-test`.
208+
209+Note: If you use plain text a lot, you'll want a better editor than
210+`Notepad` or `TextEdit`. You might want to look at
211+[Sublime Text](http://www.sublimetext.com/) or (if you're willing
212+to put in some time learning an unfamiliar interface)
213+[Vim](http://www.vim.org) or [Emacs](http://www.gnu.org/software/emacs).
214+
215+# Step 6: Converting a file
216+
217+Go back to your terminal. We should still be in the
218+`Documents/pandoc-test` directory. Verify that with `pwd`.
219+
220+Now type
221+
222+ ls
223+
224+(or `dir` if you're on Windows).
225+This will list the files in the current directory. You should see
226+the file you created, `test1.md`.
227+
228+To convert it to HTML, use this command:
229+
230+ pandoc test1.md -f markdown -t html -s -o test1.html
231+
232+The filename `test1.md` tells pandoc which file to convert.
233+The `-s` option says to create a "standalone" file, with a header
234+and footer, not just a fragment. And the `-o test1.html` says
235+to put the output in the file `test1.html`. Note that we could
236+have omitted `-f markdown` and `-t html`, since the default
237+is to convert from markdown to HTML, but it doesn't hurt to
238+include them.
239+
240+Check that the file was created by typing `ls` again. You
241+should see `test1.html`. Now open this in a browser. On OS X,
242+you can type
243+
244+ open test1.html
245+
246+On Windows, type
247+
248+ .\test1.html
249+
250+You should see a browser window with your document.
251+
252+To create a LaTeX document, you just need to change the command
253+slightly:
254+
255+ pandoc test1.md -f markdown -t latex -s -o test1.tex
256+
257+Try opening `test1.tex` in your text editor.
258+
259+Pandoc can often figure out the input and output formats from
260+the filename extensions. So, you could have just used:
261+
262+ pandoc test1.md -s -o test1.tex
263+
264+Pandoc knows you're trying to create a LaTeX document, because of the
265+`.tex` extension.
266+
267+Now try creating a Word document (with extension `docx`).
268+
269+If you want to create a PDF, you'll need to have LaTeX installed.
270+(See [MacTeX](http://tug.org/mactex/) on OS X,
271+[MiKTeX](http://miktex.org) on Windows, or install the texlive
272+package in linux.) Then do
273+
274+ pandoc test1.md -s -o test1.pdf
275+
276+# Step 7: Command-line options
277+
278+You now know the basics. Pandoc has a lot of options. At this point
279+you can start to learn more about them by reading the
280+[User's Guide](README.html).
281+
282+Here's an example. The `--mathml` option causes pandoc to
283+convert TeX math into MathML. Type
284+
285+ pandoc --mathml
286+
287+then enter this text, followed by `Ctrl-D` (`Ctrl-Z` followed by
288+`Enter` on Windows):
289+
290+ $x = y^2$
291+
292+Now try the same thing without `--mathml`. See the difference
293+in output?
294+
295+If you forget an option, or forget which formats are supported, you
296+can always do
297+
298+ pandoc --help
299+
300+to get a list of all the supported options.
301+
302+On OS X or Linux systems, you can also do
303+
304+ man pandoc
305+
306+to get the pandoc manual page. All of this information is also
307+in the User's Guide.
308+
309+If you get stuck, you can always ask questions on the
310+[pandoc-discuss](http://groups.google.com/group/pandoc-discuss)
311+mailing list. But be sure to check the [FAQs](faqs.html) first,
312+and search through the mailing list to see if your question has
313+been answered before.
314+