1 .. -*- coding: utf-8 -*-
3 ========================================
4 Emacs Support for reStructuredText
5 ========================================
7 :Author: Martin Blais <blais@furius.ca>
11 High-level description of the existing emacs support for editing
12 reStructuredText text documents. Suggested setup code and usage
13 instructions are provided.
20 3.1 Adjusting a Section Title
21 3.2 Promoting and Demoting Many Sections
22 3.3 Redoing All the Decorations to Your Taste
23 3.4 Customizations for Decorations
24 3.5 Viewing the Hierarchy of Section Decorations
25 4 Section Movement and Selection
26 5 Operating on Blocks of Text
27 5.1 Shifting Text Horizontally Intelligently
28 5.2 Bulleting and Enumerating Lists
29 5.2.1 Straightening Existing Bullet List Hierarchies
30 5.3 Creating and Removing Line Blocks
31 5.4 Commenting a Region of Text
32 6 Converting Documents from Emacs
33 7 Table-of-Contents Features
34 7.1 Inserting a Table of Contents
35 7.2 Maintaining the Table of Contents Up-to-date
36 8 Syntax Highlighting via Font-Lock
37 8.1 Face Customization
39 9 Other Useful Settings
40 9.1 ``text-mode`` Settings
41 9.2 Editing Tables: Emacs table mode
42 9.3 Character Processing
51 reStructuredText_ is a series of conventions that allows a
52 toolset--docutils--to extract generic document structure from simple
53 text files. For people who use Emacs_, there is a package that adds a
54 major mode that supports editing in the conventions of
55 reStructuredText_: ``rst.el``. This document describes the features it
56 provides, and how to setup your emacs to use them and how to invoke
63 Emacs support for reStructuredText is implemented as an Emacs major
64 mode (``rst-mode``) provided by the ``rst.el`` emacs package.
66 For recent versions of Emacs, there's no need to install anything to
67 get reST support; ``rst-mode`` is already available. So::
71 will work out of the box. If this works for you, please skip to the
74 For older versions of Emacs, ``rst.el`` can be found in the
75 ``tools/editors/emacs/`` directory of the Docutils snapshot or
76 repository. `A copy can also be downloaded here.
77 <http://docutils.sourceforge.net/tools/editors/emacs/rst.el>`__
79 In order to use ``rst-mode``, you need to put the ``rst.el`` in a
80 directory located in your emacs ``load-path`` (use ``C-h v load-path``
91 To enable ``rst-mode``, simply type ``M-x rst-mode``. Alternatively,
92 you can modify ``auto-mode-alist`` to automatically turn it on
93 whenever you visit reStructuredText_ documents::
96 (append '(("\\.txt$" . rst-mode)
97 ("\\.rst$" . rst-mode)
98 ("\\.rest$" . rst-mode)) auto-mode-alist))
100 If have local variables enabled (see ``enable-local-variables`` in the
101 Emacs manual), you can also add the following at the top of your
102 documents to trigger rst-mode::
106 Or this at the end of your documents::
113 ``rst-mode`` automatically binds several keys for invoking special
114 handy functions for editing ReStructuredText. As is the custom for
115 Emacs major modes, most keys are bound to ``C-c C-LETTER``.
117 If you insert an inline table-of-contents at the top of the document,
118 you may want to add a hook to automatically update it everytime you
119 adjust a section title::
121 (add-hook 'rst-adjust-hook 'rst-toc-update)
123 Additional configuration variables can be customized and can be found
124 by browsing the source code for ``rst.el``.
130 The rst package does not completely parse all the reStructuredText_
131 constructs, but it contains the ability to recognize the section
132 decorations and to build the hierarchy of the document. What we call
133 section decorations or adornments are the underlines or under- and
134 overlines used to mark a section title.
137 Adjusting a Section Title
138 -------------------------
140 There is a function that helps a great deal to maintain these
141 decorations: ``rst-adjust`` (bound to ``C-c C-a``, or ``C-=`` by
142 default). This function is a Swiss army knife that can be invoked
143 repeatedly and whose behaviour depends on context:
145 #. If there is an incomplete underline, e.g.::
150 Invocation will complete the section title. You can simply enter a
151 few characters of the title and invoke the function to complete it.
152 It can also be used to adjust the length of the existing decoration
153 when you need to edit the title.
155 #. If there is no section decoration, a decoration one level under the
156 last encountered section level is added;
158 #. If there is already a section decoration, it is promoted to the
159 next level. You can invoke it like this repeatedly to cycle the
160 title through the hierarchy of existing decorations.
162 Invoking the function with a negative prefix argument, e.g. ``C--
163 C-=``, will effectively reverse the direction of decoration cycling.
164 To alternate between underline-only and over-and-under styles, you can
165 use a regular prefix argument, e.g. ``C-u C-=``. See the
166 documentation of ``rst-adjust`` for more description of the prefix
167 arguments to alter the behaviour of the function.
169 Promoting and Demoting Many Sections
170 ------------------------------------
172 When you are re-organizing the structure of a document, it can be
173 useful to change the level of a number of section titles. The same
174 key binding can be used to do that: if the region is active when the
175 binding is invoked, all the section titles that are within the region
176 are promoted accordingly (or demoted, with negative prefix arg).
178 Redoing All the Decorations to Your Taste
179 -----------------------------------------
181 If you open someone else's file and the decorations it contains are
182 unfamiliar, you may want to readjust them to fit your own preferred
183 hierarchy of decorations. This can be difficult to perform by hand.
184 However, you can do this easily by invoking
185 ``rst-straighten-decorations`` (``C-c C-s``), which operates on the
188 Customizations for Decorations
189 ------------------------------
191 You can set the variable ``rst-preferred-decorations`` to a list of
192 the decorations that you like to use for documents. Everyone has
193 their preference. ``rst-default-indent`` can be set to the number of
194 indent spaces preferred for the over-and-under decoration style.
196 Viewing the Hierarchy of Section Decorations
197 --------------------------------------------
199 You can visualize the hierarchy of the section decorations in the
200 current buffer by invoking ``rst-display-decorations-hierarchy``,
201 bound on ``C-c C-h``. A temporary buffer will appear with fake
202 section titles rendered in the style of the current document. This
203 can be useful when editing other people's documents to find out which
204 section decorations correspond to which levels.
207 Section Movement and Selection
208 ==============================
210 You can move the cursor between the different section titles by using
211 the ``rst-backward-section`` and ``rst-forward-section`` functions, by
212 default bound to the ``C-c C-p`` and ``C-c C-n`` keys.
214 To mark the section that cursor lies in, use ``rst-mark-section``
219 Operating on Blocks of Text
220 ===========================
222 Shifting Text Horizontally Intelligently
223 ----------------------------------------
225 Due to the nature of reStructuredText_, lists are indented by two or
226 three characters, e.g. bulleted lists use two chars::
239 while enumerated lists are indented by 3 or more characters ::
249 To this effect, when shifting text, it can be useful to have functions
250 which understand which indent to use by using the context around the
251 region. Those functions are ``rst-shift-region-right`` and
252 ``rst-shift-region-left``.
254 You can use ``C-c C-r`` and ``C-c C-l`` to shift the active region.
255 These bindings are similar to the ones provided by python-mode for
256 editing python code and behave similarly. They automatically inspect
257 the lines of text before the currently selected region to determine
258 what the appropriate column positions are.
261 Bulleting and Enumerating Lists
262 -------------------------------
264 Sometimes it can be useful to insert bullet list markers enumeration
265 number before a number of lines or paragraphs. You can do this easily
266 by invoking ``rst-enumerate-region`` (``C-c C-e``), for example, the
283 ``rst-listify-region`` (``C-c C-b``) does the same, but only adds
284 bullet list markers, e.g.::
301 By default, each paragraph starting on the leftmost line in the
302 highlighted region will be taken to be a single list or enumeration
303 item, for example, enumerating the following::
306 keeps the doctor away.
309 are tastier than apples.
311 If you preferred bananas
318 keeps the doctor away.
321 are tastier than apples.
323 3. If you preferred bananas
327 If you would like to enumerate each of the lines, use a prefix
328 argument on the preceding commands, e.g.::
340 Straightening Existing Bullet List Hierarchies
341 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
343 If you invoke ``rst-straighten-bullets-region`` (C-c C-w), the
344 existing bullets in the highlighted region will be replaced to reflect
345 their respective level. This does not make a difference in the
346 document structure that reStructuredText_ defines, but looks better in
347 the input file, for example, if all of the top-level bullet items use
348 the character ``-``, and all of the 2nd level items use ``*``, etc.
351 Creating and Removing Line Blocks
352 ---------------------------------
354 To create line blocks, first select the region to convert and invoke
355 ``rst-toggle-line-block`` with ``C-c C-d``, for example, the
368 This works even if the region is indented. To remove line blocks,
369 select a region and invoke with a prefix argument.
372 Commenting a Region of Text
373 ---------------------------
375 If you use the Emacs ``comment-region`` function (bound to ``C-c
376 C-c``), the appropriate comment syntax will be added to the active
391 Converting Documents from Emacs
392 ===============================
394 The major mode provides a number of functions for running documents
395 being edited through the docutils tools.
397 The main generic function is ``rst-compile`` (``C-c 1``). This
398 function basically creates a compilation command with the correct
399 output name for the current buffer and then invokes Emacs' compile
400 function. It also looks for the presence of a ``docutils.conf``
401 configuration file in the parent directories and adds it to the
402 cmdline options. There is also an alternative function in case you
403 often need run your document in a second toolset (``C-c 2``).
405 You can customize the commands being used by setting
406 ``rst-compile-primary-toolset`` and ``rst-compile-secondary-toolset``.
408 Other commands are available for other formats:
410 - ``rst-compile-pseudo-region`` (``C-c 3``): When crafting documents,
411 it is often convenient to view which data structures docutils will
412 parse them into. You can use to run the active region through
413 ``rst2pseudoxml.py`` and have the output automatically be displayed
416 - ``rst-compile-pdf-preview`` (``C-c 4``): Convert the current
417 document to PDF and launch a viewer on the results.
419 - ``rst-compile-slides-preview`` (``C-c 5``): Convert the current
420 document to S5 slides and view in a web browser.
423 Table-of-Contents Features
424 ==========================
426 When you are editing long documents, it can be a bit difficult to
427 orient yourself in the structure of your text. To that effect, a
428 function is provided that quickly parses the document and presents a
429 hierarchically indented table of contents of the document in a
430 temporary buffer, in which you can navigate and press ``Return`` to go
431 to a specific section.
433 Invoke this function (``rst-toc``) with ``C-c C-t``. It should
434 present a temporary buffer that looks something like this::
437 Debugging Meta-Techniques
439 Debugging Solution Patterns
440 Recognize That a Bug Exists
441 Subdivide and Isolate
442 Identify and Verify Assumptions
443 Use a Tool for Introspection
444 Change one thing at a time
445 Learn about the System
447 The Basic Steps in Debugging
453 When you select a section title (press ``RET``), the temporary buffer
454 disappears and you are left with the cursor positioned at the chosen
458 Inserting a Table of Contents
459 -----------------------------
461 Oftentimes in long text documents that are meant to be read directly,
462 a Table of Contents is inserted at the beginning of the text. This is
463 the case for most internet FAQs, for example. In reStructuredText_
464 documents, since the table of contents is automatically generated by
465 the parser with the ``.. contents::`` directive, people generally have
466 not been adding a text table of contents to their source documents,
467 and partly because it is too much trouble to edit and maintain.
469 The emacs support for reStructuredText_ provides a function to insert
470 such a table of contents in your document. Since it is not meant to
471 be part of the document text, you should place such a table of
472 contents within a comment, so that it is ignored by the parser. This
473 is the favoured usage::
478 2 Debugging Solution Patterns
479 2.1 Recognize That a Bug Exists
480 2.2 Subdivide and Isolate
481 2.3 Identify and Verify Assumptions
482 2.4 Use a Tool for Introspection
483 2.5 Change one thing at a time
484 2.6 Learn about the System
485 3 Understanding a bug
486 4 The Basic Steps in Debugging
492 Just place the cursor at the top-left corner where you want to insert
493 the TOC and invoke the function with ``C-c C-i``. The table of
494 contents will display all the section titles that are under the
495 location where the insertion occurs. This way you can insert local
496 table of contents by placing them in the appropriate location.
498 If you have deep nesting of sections, you can use a numeric prefix
499 argument to limit the depth of rendering of the TOC.
501 You can also customize the look of the TOC by setting the values of
502 the following variables:: ``rst-toc-indent``,
503 ``rst-toc-insert-style``, ``rst-toc-insert-max-level``.
507 The table-of-contents inserted by ``rst-mode`` has text properties
508 added to it so that if you type ``C-c C-f`` while the cursor is on
509 one of its entries, the cursor will jump to the corresponding
510 section in the document.
513 Maintaining the Table of Contents Up-to-date
514 --------------------------------------------
516 One issue is that you will probably want to maintain the inserted
517 table of contents up-to-date. There is a function that will
518 automatically look for the inserted TOC (``rst-toc-update``)
519 and it can be added to a hook on the section decoration adjustment
520 function, so that every time you adjust a section title, the TOC is
521 updated. Add this functionality with the following emacs
524 (add-hook 'rst-adjust-hook 'rst-toc-update)
526 You can invoke the update on the current buffer with ``C-c C-u``.
529 Syntax Highlighting via Font-Lock
530 =================================
532 ``rst-mode`` also provides syntax highlighting to reStructuredText_
533 constructs. (This mode was written by Stefan Merten.)
535 Lazy syntax coloring is implemented for many of the constructs that
536 reStructuredText_ prescribes. By default, the font-lock colouring is
537 performed lazily. If you don't like this, you can turn this off by
538 setting the value of ``rst-mode-lazy``. You can also change the
539 various colours (see the source file for the whole list of
542 ``font-lock`` syntax highlighting is enabled by default. If you prefer
543 to turn off syntax highlighting (on some machines it can slow down
544 editing a little bit), you can use the following in your Emacs
547 (setq font-lock-global-modes '(not rst-mode))
553 The ``rst-faces`` group contains all necessary for customizing
554 fonts. The default settings use standard ``font-lock-*-face`` so if
555 you set these to your liking they are probably good in rst-mode also.
557 The group is contained in the faces group as well as in the rst group.
563 The ``rst-faces-defaults`` group contains all necessary for
564 customizing the default fonts used for section title faces.
566 The general idea for section title faces is to have a non-default
567 background but do not change the background. The section level is
568 shown by the lightness of the background color. If you like this
569 general idea of generating faces for section titles but do not like
570 the details this group is the point where you can customize the
571 details. If you do not like the general idea, however, you should
572 customize the faces used in ``rst-adornment-faces-alist``.
574 Note: If you are using a dark background please make sure the variable
575 ``frame-background-mode`` is set to the symbol dark. This triggers
576 some default values which are probably right for you.
578 The group is contained in the ``rst-faces`` group.
580 All customizable features have a comment explaining their
581 meaning. Refer to the customization of your Emacs (try ``M-x
586 Other Useful Settings
587 =====================
589 This section covers general emacs text-mode settings that are useful
590 in the context of reStructuredText_ conventions. These are not
591 provided by ``rst.el`` but you may find them useful specifically for
592 reStructuredText_ documents.
594 ``text-mode`` Settings
595 ----------------------
597 Consult the Emacs manual for more text-mode customizations. In
598 particular, you may be interested in setting the following variables,
599 functions and modes that pertain somewhat to text-mode:
607 Editing Tables: Emacs table mode
608 --------------------------------
610 You may want to check out `Emacs table mode`_ to create an edit
611 tables, it allows creating ascii tables compatible with
614 .. _Emacs table mode: http://table.sourceforge.net/
620 Since reStructuredText punts on the issue of character processing,
621 here are some useful resources for Emacs users in the Unicode world:
623 * `xmlunicode.el and unichars.el from Norman Walsh
624 <http://nwalsh.com/emacs/xmlchars/index.html>`__
626 * `An essay by Tim Bray, with example code
627 <http://www.tbray.org/ongoing/When/200x/2003/09/27/UniEmacs>`__
629 * For Emacs users on Mac OS X, here are some useful useful additions
632 - To get direct keyboard input of non-ASCII characters (like
633 "option-e e" resulting in "é" [eacute]), first enable the option
634 key by setting the command key as your meta key::
636 (setq mac-command-key-is-meta t) ;; nil for option key
638 Next, use one of these lines::
640 (set-keyboard-coding-system 'mac-roman)
641 (setq mac-keyboard-text-encoding kTextEncodingISOLatin1)
643 I prefer the first line, because it enables non-Latin-1 characters
644 as well (em-dash, curly quotes, etc.).
646 - To enable the display of all characters in the Mac-Roman charset,
647 first create a fontset listing the fonts to use for each range of
648 characters using charsets that Emacs understands::
650 (create-fontset-from-fontset-spec
651 "-apple-monaco-medium-r-normal--10-*-*-*-*-*-fontset-monaco,
652 ascii:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman,
653 latin-iso8859-1:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman,
654 mule-unicode-0100-24ff:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman")
656 Latin-1 doesn't cover characters like em-dash and curly quotes, so
657 "mule-unicode-0100-24ff" is needed.
659 Next, use that fontset::
661 (set-frame-font "fontset-monaco")
663 - To enable cooperation between the system clipboard and the Emacs
664 kill ring, add this line::
666 (set-clipboard-coding-system 'mac-roman)
668 Other useful resources are in `Andrew Choi's Emacs 21 for Mac OS X
669 FAQ <http://members.shaw.ca/akochoi-emacs/stories/faq.html>`__.
671 No matter what platform (or editor) you're using, I recommend the
672 ProFont__ programmer's font. It's monospaced, small but readable,
673 similar characters are visually distinctive (like "I1l|", "0O", "ao",
674 and ".,:;"), and free.
676 __ http://www.tobias-jung.de/seekingprofont/
683 - The automatic section adjustment and table of contents features were
684 written by Martin Blais;
685 - Syntax highlighting was implemented by Stefan Merten;
686 - Various other functions were implemented by David Goodger.
691 On 2005-10-30, ``rst.el`` integrated and replaced the contents of the
694 - ``restructuredtext.el``
700 .. _Emacs: http://www.gnu.org/software/emacs/emacs.html
701 .. _reStructuredText: http://docutils.sf.net/rst.html
707 indent-tabs-mode: nil
708 sentence-end-double-space: t