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

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