Enhancement and additions for webinar

[doc.git] / docs / guides / onap-developer / how-to-use-docs / converting-formats.rst

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 (file)
index 0000000..5321a18
--- /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.
+
+
+