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.
10 RST format is used for documentation. Other file formats can be converted to
15 Always check the output text after conversion. For the most common errors,
16 see section Fixing the converted document.
21 Pandoc is a powerful document-transformation utility. We'll use it to
22 do simple conversions, but it is capable of much more. Visit
23 the `pandoc website <http://pandoc.org/installing.html>`_ for
24 installation instructions for your platform.
29 Using a terminal, navigate to the directory containing the documents
30 you wish to convert. Next, issue the following command for each file
31 you'd like to convert:
33 :code:`pandoc -s --toc -f <from format> -t rst myfile.<from format>`
35 :code:`-s` tells pandoc to produce a standalone document
37 :code:`--toc` tells pandoc to produce a table of contents (optional)
39 :code:`-t` tells pandoc to produce reStructuredText output
41 :code:`-f` tells pandoc the input format. It should be one of the following:
43 +--------------------+----------------------------------------------------+
44 | Format | Description |
45 +====================+====================================================+
46 |commonmark | Markdown variant |
47 +--------------------+----------------------------------------------------+
48 |docbook | XML-based markup |
49 +--------------------+----------------------------------------------------+
50 |docx | Microsoft Word |
51 +--------------------+----------------------------------------------------+
52 |epub | Ebook format |
53 +--------------------+----------------------------------------------------+
54 |haddock | Doc format produced by tool used on Haskell code |
55 +--------------------+----------------------------------------------------+
57 +--------------------+----------------------------------------------------+
58 |json | JSON pandoc AST |
59 +--------------------+----------------------------------------------------+
60 |latex | Older typesetting syntax |
61 +--------------------+----------------------------------------------------+
62 |markdown | Simple formatting syntax meant to produce HTML |
63 +--------------------+----------------------------------------------------+
64 |markdown_github | Github flavored markdown |
65 +--------------------+----------------------------------------------------+
66 |markdown_mmd | Multi-markdown flavored markdown |
67 +--------------------+----------------------------------------------------+
68 |markdown_phpextra | PHP flavored markdown |
69 +--------------------+----------------------------------------------------+
70 |markdown_strict | Markdown with no added pandoc features |
71 +--------------------+----------------------------------------------------+
72 |mediawiki | Popular wiki language |
73 +--------------------+----------------------------------------------------+
74 |native | Pandoc native Haskell |
75 +--------------------+----------------------------------------------------+
76 |odt | Open document text (used by LibreOffice) |
77 +--------------------+----------------------------------------------------+
78 |opml | Outline processor markup language |
79 +--------------------+----------------------------------------------------+
80 |org | Org mode for Emacs |
81 +--------------------+----------------------------------------------------+
82 |rst | reStructuredText |
83 +--------------------+----------------------------------------------------+
84 |t2t | Wiki-like formatting syntax |
85 +--------------------+----------------------------------------------------+
86 |textile | A formatting syntax similar to RST and markdown |
87 +--------------------+----------------------------------------------------+
88 |twiki | Popular wiki formatting syntax |
89 +--------------------+----------------------------------------------------+
91 Fixing the converted document
92 -----------------------------
94 How much you'll need to fix the converted document depends on which file
95 format you're converting from. Here are a couple of things to watch out
98 1. Multi-line titles need to be converted to single line
99 2. Standalone "**" characters
100 3. :code:`***bolded***` should be :code:`**bolded**`
109 `Online Sphinx editor <https://livesphinx.herokuapp.com/>`_ is a RST previewing