diff options
| author |   Spencer Seidel <jsseidel@fastmail.com> | 2017-09-06 12:39:15 -0400 |
|---|---|---|
| committer |   Rich Bennett <rb2745@att.com> | 2017-09-06 17:48:29 +0000 |
| commit | f710065b4f9849d8f8b0e322e1c78be30c85b9ad (patch) | |
| tree | 7e0c903f659702bb7de7757bc4950a3251445048 /docs/guide/onap-developer/how-to-use-docs/converting-formats.rst | |
| parent | 2802a98edbdb6964f2cc32a08c09241fc615b870 (diff) | |
Added new sections
Added sections describing which documentation should be stored on wiki
vs rst, why the doc team chose rst/sphinx, and how to convert from
other formats, loosely based on Steven Wright's video. Updated
index.rst to account for the format-conversion section.
Change-Id: Iea9ec284fc273510177966d8325191ea39d049b2
Issue-Id: DOC-66
Signed-off-by: Spencer Seidel <jsseidel@fastmail.com>
Diffstat (limited to 'docs/guide/onap-developer/how-to-use-docs/converting-formats.rst')
| -rw-r--r-- | docs/guide/onap-developer/how-to-use-docs/converting-formats.rst | 91 |
1 files changed, 91 insertions, 0 deletions
diff --git a/docs/guide/onap-developer/how-to-use-docs/converting-formats.rst b/docs/guide/onap-developer/how-to-use-docs/converting-formats.rst new file mode 100644 index 000000000..96b5c82ad --- /dev/null +++ b/docs/guide/onap-developer/how-to-use-docs/converting-formats.rst @@ -0,0 +1,91 @@ +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. + + + |