.. -*- coding: utf-8 -*-


.. NOTE: These are new FAQ questions, the original FAQ.txt has not been
   split yet.
   
   Review needed
   =============

   To keep the FAQ decisive as possible, it would be nice to have a second
   set of eyes to review the answers, and also clarify if the rationale is
   backed by:

   A. reStructuredText specificaton
   B. Parser
      a.) wontfix - expected behavior
      b.) limitation, TODO
      c.) limitation, other (may not encourage reST form / not worth
          effort as this time)
          
    Don't feel a need to go into too much detail unless necessary, all FAQ
    here will be carefully linked back to original threads.

======================
 reStructuredText FAQ
======================

:Date: $Date: 2015-03-12 23:43:12 +0100 (Do, 12. Mär 2015) $
:Revision: $Revision: 7826 $
:Web site: http://docutils.sourceforge.net/
:Copyright: This document has been placed in the public domain.
            
.. contents::
.. sectnum::

This is a work in progress. 

How to escape adjacent characters in inline markup
--------------------------------------------------

Why is it that inline strings with adjacent characters such as::

    ``word``'s
      
creates ``word's``, with the "'s" in the markup?  

The above will also generate a docutils error **Inline literal 
start-string without end-string.**.

Some editors with reStructuredText highlighting may break if using
adjacent characters next to inline escapes. 
You can escape it with::

    ``word``\ 's

Source: [LIST-ESCAPE]_

.. [LIST-ESCAPE] http://thread.gmane.org/gmane.text.docutils.user/39/focus=40 
   15 Dec 02:09 2002.

.. _editors:
   
What are some good editors for reStructuredText?
------------------------------------------------

+-----------------+------------------------------------------------------+
| Editor          | Plug-ins                                             |
+=================+======================================================+
| `Eclipse`_      | `reST Editor`_ [EDT-ECLIPSE]_.                       |
+-----------------+------------------------------------------------------+
| `GNU Emacs`_    | [EDT-EMACS]_                                         |
+-----------------+------------------------------------------------------+
| `VIM`_          | `riv.vim`_                                           |
+-----------------+------------------------------------------------------+
| `Sublime Text`_ | `sublime-rst-completion`_,                           |
|                 | `reStructuredText Improved`_                         |
+-----------------+------------------------------------------------------+
| IntelliJ IDEA,  | `JetBrains ReStructuredText Support`_                |
| WebStorm,       |                                                      |
| RubyMine,       |                                                      |
| PHPStorm,       |                                                      |
| AppCode         |                                                      |
+-----------------+------------------------------------------------------+

For more, see the thread `Good ReStructuredText editors`_.

.. [EDT-ECLIPSE] http://article.gmane.org/gmane.text.docutils.user/7258
.. [EDT-EMACS] http://article.gmane.org/gmane.text.docutils.user/7257
.. _Good ReStructuredText editors:
   http://article.gmane.org/gmane.text.docutils.user/7256
.. _Eclipse: https://eclipse.org
.. _GNU Emacs: http://www.gnu.org/software/emacs/
.. _VIM: http://www.vim.org
.. _Sublime Text: http://www.sublimetext.com
.. _reST Editor: https://resteditor.sf.net
.. _riv.vim: https://github.com/Rykka/riv.vim
.. _sublime-rst-completion: https://github.com/mgaitan/sublime-rst-completion
.. _reStructuredText Improved:
   https://bitbucket.org/klorenz/sublimerestructuredtextimproved
.. _JetBrains ReStructuredText Support:
   https://plugins.jetbrains.com/plugin/7124?pr=
   
What is the optimal file extension for reStructuredText?
--------------------------------------------------------

It is up to you!

**.txt**:

* reStructuredText by design conveys a structured, consistent layout for
  ASCII documents.
* .txt is universal for text files, you are safer the end-user will open
  the file with a text editor without having to do anything special.
* docutils uses plain .txt files internally
    
**.rst**

* Many editors will automatically be familiar with this extension, and
  offer special highlighting / functionality.
* Repository viewers (such as SourceForge and GitHub) may show .rst files
  in HTML by piping .rst through docutils for you.

Source: [LIST-RST-TXT]_

How can I get my editor to handle files as reStructuredText?
------------------------------------------------------------

Your editor may have the ability to manually switch an option to handle a
file as reStructuredText. Often there are located somewhere in the menus.

You should research instructions for how you can select filetype / syntax
highlighting language for your editor. If you do not see reStructuredText,
see if your editor has a plug-in or extension for reStructuredText.

If not, you can use one of `these editors <editors_>`_ which have 
excellent support for reST.

Vim and GNU Emacs can open non-.rst files by appending a modeline to the 
end of a file.

GNU Emacs::
    
    ..
        Local variables:
        coding: utf-8
        mode: rst
        indent-tabs-mode: nil
        End:

Vim::

    .. vim: fileencoding=utf-8 filetype=rst 

Emacs + vim: emacs::

    ..
        Local variables:
        coding: utf-8
        mode: rst
        indent-tabs-mode: nil
        End:
        vim: fileencoding=utf-8 filetype=rst :


Source: [LIST-RST-TXT]_

.. [LIST-RST-TXT] **.rst vs. .txt file extension for docs/**. 2015-03-10.
   http://article.gmane.org/gmane.text.docutils.devel/7057

.. vim: fileencoding=utf-8 filetype=rst