sandbox/list-faq/docs/FAQ/reST.txt

   1 .. -*- coding: utf-8 -*-
   2
   3
   4 .. NOTE: These are new FAQ questions, the original FAQ.txt has not been
   5    split yet.
   6
   7    Review needed
   8    =============
   9
  10    To keep the FAQ decisive as possible, it would be nice to have a second
  11    set of eyes to review the answers, and also clarify if the rationale is
  12    backed by:
  13
  14    A. reStructuredText specificaton
  15    B. Parser
  16       a.) wontfix - expected behavior
  17       b.) limitation, TODO
  18       c.) limitation, other (may not encourage reST form / not worth
  19           effort as this time)
  20
  21     Don't feel a need to go into too much detail unless necessary, all FAQ
  22     here will be carefully linked back to original threads.
  23
  24 ======================
  25  reStructuredText FAQ
  26 ======================
  27
  28 :Date: $Date$
  29 :Revision: $Revision$
  30 :Web site: http://docutils.sourceforge.net/
  31 :Copyright: This document has been placed in the public domain.
  32
  33 .. contents::
  34 .. sectnum::
  35
  36 This is a work in progress.
  37
  38 How to escape adjacent characters in inline markup
  39 --------------------------------------------------
  40
  41 Why is it that inline strings with adjacent characters such as::
  42
  43     ``word``'s
  44
  45 creates ``word's``, with the "'s" in the markup?
  46
  47 The above will also generate a docutils error **Inline literal
  48 start-string without end-string.**.
  49
  50 Some editors with reStructuredText highlighting may break if using
  51 adjacent characters next to inline escapes.
  52 You can escape it with::
  53
  54     ``word``\ 's
  55
  56 Source: [LIST-ESCAPE]_
  57
  58 .. [LIST-ESCAPE] http://thread.gmane.org/gmane.text.docutils.user/39/focus=40
  59    15 Dec 02:09 2002.
  60
  61 .. _editors:
  62
  63 What are some good editors for reStructuredText?
  64 ------------------------------------------------
  65
  66 +-----------------+------------------------------------------------------+
  67 | Editor          | Plug-ins                                             |
  68 +=================+======================================================+
  69 | `Eclipse`_      | `reST Editor`_ [EDT-ECLIPSE]_.                       |
  70 +-----------------+------------------------------------------------------+
  71 | `GNU Emacs`_    | [EDT-EMACS]_                                         |
  72 +-----------------+------------------------------------------------------+
  73 | `VIM`_          | `riv.vim`_                                           |
  74 +-----------------+------------------------------------------------------+
  75 | `Sublime Text`_ | `sublime-rst-completion`_,                           |
  76 |                 | `reStructuredText Improved`_                         |
  77 +-----------------+------------------------------------------------------+
  78 | IntelliJ IDEA,  | `JetBrains ReStructuredText Support`_                |
  79 | WebStorm,       |                                                      |
  80 | RubyMine,       |                                                      |
  81 | PHPStorm,       |                                                      |
  82 | AppCode         |                                                      |
  83 +-----------------+------------------------------------------------------+
  84
  85 For more, see the thread `Good ReStructuredText editors`_.
  86
  87 .. [EDT-ECLIPSE] http://article.gmane.org/gmane.text.docutils.user/7258
  88 .. [EDT-EMACS] http://article.gmane.org/gmane.text.docutils.user/7257
  89 .. _Good ReStructuredText editors:
  90    http://article.gmane.org/gmane.text.docutils.user/7256
  91 .. _Eclipse: https://eclipse.org
  92 .. _GNU Emacs: http://www.gnu.org/software/emacs/
  93 .. _VIM: http://www.vim.org
  94 .. _Sublime Text: http://www.sublimetext.com
  95 .. _reST Editor: https://resteditor.sf.net
  96 .. _riv.vim: https://github.com/Rykka/riv.vim
  97 .. _sublime-rst-completion: https://github.com/mgaitan/sublime-rst-completion
  98 .. _reStructuredText Improved:
  99    https://bitbucket.org/klorenz/sublimerestructuredtextimproved
 100 .. _JetBrains ReStructuredText Support:
 101    https://plugins.jetbrains.com/plugin/7124?pr=
 102
 103 What is the optimal file extension for reStructuredText?
 104 --------------------------------------------------------
 105
 106 It is up to you!
 107
 108 **.txt**:
 109
 110 * reStructuredText by design conveys a structured, consistent layout for
 111   ASCII documents.
 112 * .txt is universal for text files, you are safer the end-user will open
 113   the file with a text editor without having to do anything special.
 114 * docutils uses plain .txt files internally
 115
 116 **.rst**
 117
 118 * Many editors will automatically be familiar with this extension, and
 119   offer special highlighting / functionality.
 120 * Repository viewers (such as SourceForge and GitHub) may show .rst files
 121   in HTML by piping .rst through docutils for you.
 122
 123 Source: [LIST-RST-TXT]_
 124
 125 How can I get my editor to handle files as reStructuredText?
 126 ------------------------------------------------------------
 127
 128 Your editor may have the ability to manually switch an option to handle a
 129 file as reStructuredText. Often there are located somewhere in the menus.
 130
 131 You should research instructions for how you can select filetype / syntax
 132 highlighting language for your editor. If you do not see reStructuredText,
 133 see if your editor has a plug-in or extension for reStructuredText.
 134
 135 If not, you can use one of `these editors <editors_>`_ which have
 136 excellent support for reST.
 137
 138 Vim and GNU Emacs can open non-.rst files by adding this code to their
 139 file.
 140
 141 GNU Emacs::
 142
 143     ..
 144         Local variables:
 145         coding: utf-8
 146         mode: rst
 147         indent-tabs-mode: nil
 148         End:
 149
 150 Vim::
 151
 152     .. vim: fileencoding=utf-8 filetype=rst
 153
 154 Emacs + vim: emacs::
 155
 156     ..
 157         Local variables:
 158         coding: utf-8
 159         mode: rst
 160         indent-tabs-mode: nil
 161         End:
 162         vim: fileencoding=utf-8 filetype=rst :
 163
 164
 165 Source: [LIST-RST-TXT]_
 166
 167 .. [LIST-RST-TXT] **.rst vs. .txt file extension for docs/**. 2015-03-10.
 168    http://article.gmane.org/gmane.text.docutils.devel/7057
 169
 170 .. vim: fileencoding=utf-8 filetype=rst