1 .. This work is licensed under a Creative Commons Attribution 4.0
2 .. International License. http://creativecommons.org/licenses/by/4.0
3 .. Copyright 2017 AT&T Intellectual Property. All rights reserved.
13 Pandoc is a powerful document-transformation utility. We'll use it to
14 do simple conversions, but it is capable of much more. Visit
15 the `pandoc website <http://pandoc.org/installing.html>`_ for
16 installation instructions for your platform.
21 Using a terminal, navigate to the directory containing the documents
22 you wish to convert. Next, issue the following command for each file
23 you'd like to convert:
25 :code:`pandoc -s --toc -f <from format> -t rst myfile.<from format>`
27 :code:`-s` tells pandoc to produce a standalone document
29 :code:`--toc` tells pandoc to produce a table of contents (optional)
31 :code:`-t` tells pandoc to produce reStructuredText output
33 :code:`-f` tells pandoc the input format. It should be one of the following:
35 +--------------------+---------------------------------------------------------------+
36 | Format | Description |
37 +====================+===============================================================+
38 |commonmark | Markdown variant |
39 +--------------------+---------------------------------------------------------------+
40 |docbook | XML-based markup |
41 +--------------------+---------------------------------------------------------------+
42 |docx | Microsoft Word |
43 +--------------------+---------------------------------------------------------------+
44 |epub | Ebook format |
45 +--------------------+---------------------------------------------------------------+
46 |haddock | Doc format produced by tool used on Haskell code |
47 +--------------------+---------------------------------------------------------------+
49 +--------------------+---------------------------------------------------------------+
50 |json | JSON pandoc AST |
51 +--------------------+---------------------------------------------------------------+
52 |latex | Older typesetting syntax |
53 +--------------------+---------------------------------------------------------------+
54 |markdown | Simple formatting syntax meant to produce HTML |
55 +--------------------+---------------------------------------------------------------+
56 |markdown_github | Github flavored markdown |
57 +--------------------+---------------------------------------------------------------+
58 |markdown_mmd | Multi-markdown flavored markdown |
59 +--------------------+---------------------------------------------------------------+
60 |markdown_phpextra | PHP flavored markdown |
61 +--------------------+---------------------------------------------------------------+
62 |markdown_strict | Markdown with no added pandoc features |
63 +--------------------+---------------------------------------------------------------+
64 |mediawiki | Popular wiki language |
65 +--------------------+---------------------------------------------------------------+
66 |native | Pandoc native Haskell |
67 +--------------------+---------------------------------------------------------------+
68 |odt | Open document text (used by LibreOffice) |
69 +--------------------+---------------------------------------------------------------+
70 |opml | Outline processor markup language |
71 +--------------------+---------------------------------------------------------------+
72 |org | Org mode for Emacs |
73 +--------------------+---------------------------------------------------------------+
74 |rst | reStructuredText |
75 +--------------------+---------------------------------------------------------------+
76 |t2t | Wiki-like formatting syntax |
77 +--------------------+---------------------------------------------------------------+
78 |textile | A formatting syntax similar to RST and markdown |
79 +--------------------+---------------------------------------------------------------+
80 |twiki | Popular wiki formatting syntax |
81 +--------------------+---------------------------------------------------------------+
83 Fixing the converted document
84 -----------------------------
86 How much you'll need to fix the converted document depends on which file
87 format you're converting from. Here are a couple of things to watch out
90 1. Multi-line titles need to be converted to single line
91 2. Standalone "**" characters
92 3. :code:`***bolded***` should be :code:`**bolded**`
101 `rst.ninjs.org <http://rst.ninjs.org>`_ has an excellent RST previewing
102 tool that highlights RST errors with line numbers.