diff options
author | 2020-06-26 12:58:00 +0200 | |
---|---|---|
committer | 2020-09-18 12:26:08 +0200 | |
commit | 31161eead9fe31dfe11d3ddf0b3dbd8bf0c78c93 (patch) | |
tree | 4b84c921f59d3e044ff1d1c677fae29ebfa5248a /docs/guides/onap-developer/how-to-use-docs/converting-formats.rst | |
parent | cf513de2c4f1e5a2d0368f73c0889bacd3a48ccc (diff) |
Renaming files in documentation guide
Renamed files containing introduction, setting up, and converting to RST chapters to reflect content.
Issue-ID: DOC-639
Change-Id: I5353fbf52dc635ee43464eb3284c13cedcaf6fa6
Signed-off-by: Andrea Visnyei <andrea.visnyei@nokia.com>
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 | 110 |
1 files changed, 0 insertions, 110 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 deleted file mode 100644 index 56449beb2..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/converting-formats.rst +++ /dev/null @@ -1,110 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 -.. International License. http://creativecommons.org/licenses/by/4.0 -.. Copyright 2017 AT&T Intellectual Property. All rights reserved. - -.. _converting-to-rst: - -Converting to RST -================= - -RST format is used for documentation. Other file formats can be converted to RST -with pandoc. - -.. caution:: - - Always check the output text after conversion. For the most common errors, - see section Fixing the converted document. - -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. |