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