Added epub.md, getting-started.md to docs.

These used to live in the website repo.

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
+
+    ![Juliet](images/sun.jpg)
+
+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:
+
+    ![Figure 1-1. Local version control diagram.](../figures/18333fig0101-tn.png)
+
+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.
+