diff options
Diffstat (limited to 'docs/guides/onap-developer/how-to-use-docs/converting-formats.rst')
| -rw-r--r-- | docs/guides/onap-developer/how-to-use-docs/converting-formats.rst | 95 |
1 files changed, 95 insertions, 0 deletions
diff --git a/docs/guides/onap-developer/how-to-use-docs/converting-formats.rst b/docs/guides/onap-developer/how-to-use-docs/converting-formats.rst new file mode 100644 index 000000000..5321a18df --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/converting-formats.rst @@ -0,0 +1,95 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +.. _converting-to-rst: + +Converting to RST +================= + +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. + + + |