docs/guides/onap-developer/how-to-use-docs/converting-formats.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3 .. _converting-to-rst:
   4
   5 Converting to RST
   6 =================
   7
   8 Installing pandoc
   9 -----------------
  10
  11 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.
  12
  13 Converting
  14 ----------
  15
  16 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:
  17
  18 :code:`pandoc -s --toc -f <from format> -t rst myfile.<from format>`
  19
  20 :code:`-s` tells pandoc to produce a standalone document
  21
  22 :code:`--toc` tells pandoc to produce a table of contents (optional)
  23
  24 :code:`-t` tells pandoc to produce reStructuredText output
  25
  26 :code:`-f` tells pandoc the input format. It should be one of the following:
  27
  28 +--------------------+---------------------------------------------------------------+
  29 | Format             | Description                                                   |
  30 +====================+===============================================================+
  31 |commonmark          | Markdown variant                                              |
  32 +--------------------+---------------------------------------------------------------+
  33 |docbook             | XML-based markup                                              |
  34 +--------------------+---------------------------------------------------------------+
  35 |docx                | Microsoft Word                                                |
  36 +--------------------+---------------------------------------------------------------+
  37 |epub                | Ebook format                                                  |
  38 +--------------------+---------------------------------------------------------------+
  39 |haddock             | Doc format produced by tool used on Haskell code              |
  40 +--------------------+---------------------------------------------------------------+
  41 |html                | HTML                                                          |
  42 +--------------------+---------------------------------------------------------------+
  43 |json                | JSON pandoc AST                                               |
  44 +--------------------+---------------------------------------------------------------+
  45 |latex               | Older typesetting syntax                                      |
  46 +--------------------+---------------------------------------------------------------+
  47 |markdown            | Simple formatting syntax meant to produce HTML                |
  48 +--------------------+---------------------------------------------------------------+
  49 |markdown_github     | Github flavored markdown                                      |
  50 +--------------------+---------------------------------------------------------------+
  51 |markdown_mmd        | Multi-markdown flavored markdown                              |
  52 +--------------------+---------------------------------------------------------------+
  53 |markdown_phpextra   | PHP flavored markdown                                         |
  54 +--------------------+---------------------------------------------------------------+
  55 |markdown_strict     | Markdown with no added pandoc features                        |
  56 +--------------------+---------------------------------------------------------------+
  57 |mediawiki           | Popular wiki language                                         |
  58 +--------------------+---------------------------------------------------------------+
  59 |native              | Pandoc native Haskell                                         |
  60 +--------------------+---------------------------------------------------------------+
  61 |odt                 | Open document text (used by LibreOffice)                      |
  62 +--------------------+---------------------------------------------------------------+
  63 |opml                | Outline processor markup language                             |
  64 +--------------------+---------------------------------------------------------------+
  65 |org                 | Org mode for Emacs                                            |
  66 +--------------------+---------------------------------------------------------------+
  67 |rst                 | reStructuredText                                              |
  68 +--------------------+---------------------------------------------------------------+
  69 |t2t                 | Wiki-like formatting syntax                                   |
  70 +--------------------+---------------------------------------------------------------+
  71 |textile             | A formatting syntax similar to RST and markdown               |
  72 +--------------------+---------------------------------------------------------------+
  73 |twiki               | Popular wiki formatting syntax                                |
  74 +--------------------+---------------------------------------------------------------+
  75
  76 Fixing the converted document
  77 -----------------------------
  78
  79 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:
  80
  81 1. Multi-line titles need to be converted to single line
  82 2. Standalone "**" characters
  83 3. :code:`***bolded***` should be :code:`**bolded**`
  84 4. Mangled tables
  85
  86 Previewing edits
  87 ----------------
  88
  89 Web-based
  90 ~~~~~~~~~
  91
  92 `rst.ninjs.org <http://rst.ninjs.org>`_ has an excellent RST previewing tool that highlights RST errors with line numbers.
  93
  94
  95