Date: 2013-08-03 11:16:24 +0000 (Sat, 03 Aug 2013)
Revised tutorial to match ``rst.el`` V1.4.0.
--- trunk/docutils/docs/user/emacs.txt 2013-08-02 15:39:07 UTC (rev 7711)
+++ trunk/docutils/docs/user/emacs.txt 2013-08-03 11:16:24 UTC (rev 7712)
@@ -4,101 +4,146 @@
Emacs Support for reStructuredText
-:Author: Martin Blais <blais@...>
+:Authors: Stefan Merten <stefan@...>, Martin Blais
+:Version: ``rst.el`` V1.4.0
- High-level description of the existing emacs support for editing
- reStructuredText text documents. Suggested setup code and usage
+ High-level description of the existing Emacs_ support for editing
+ reStructuredText_ text documents. Suggested setup code and usage
instructions are provided.
- 1 Introduction
- 2 Installation
- 3 Section Decorations
- 3.1 Adjusting a Section Title
- 3.2 Promoting and Demoting Many Sections
- 3.3 Redoing All the Decorations to Your Taste
- 3.4 Customizations for Decorations
- 3.5 Viewing the Hierarchy of Section Decorations
- 4 Section Movement and Selection
- 5 Operating on Blocks of Text
- 5.1 Shifting Text Horizontally Intelligently
- 5.2 Bulleting and Enumerating Lists
- 5.2.1 Straightening Existing Bullet List Hierarchies
- 5.3 Creating and Removing Line Blocks
- 5.4 Commenting a Region of Text
- 6 Converting Documents from Emacs
- 7 Table-of-Contents Features
- 7.1 Inserting a Table of Contents
- 7.2 Maintaining the Table of Contents Up-to-date
- 8 Syntax Highlighting via Font-Lock
- 8.1 Face Customization
- 8.1.1 Default Fonts
- 9 Other Useful Settings
- 9.1 ``text-mode`` Settings
- 9.2 Editing Tables: Emacs table mode
- 9.3 Character Processing
- 10 Credits
- 10.1 Obsolete Files
- 11 Future Work
-reStructuredText_ is a series of conventions that allows a
-toolset--docutils--to extract generic document structure from simple
-text files. For people who use Emacs_, there is a package that adds a
-major mode that supports editing in the conventions of
-reStructuredText_: ``rst.el``. This document describes the features it
-provides, and how to setup your emacs to use them and how to invoke
+reStructuredText_ is a syntax for simple text files that allows a
+tool set - docutils_ - to extract generic document structure. For
+people who use Emacs_, there is a package that adds a major mode that
+supports editing the syntax of reStructuredText_: ``rst.el``. This
+document describes the features it provides, and how to setup your
+Emacs_ to use them and how to invoke them.
-Emacs support for reStructuredText is implemented as an Emacs major
-mode (``rst-mode``) provided by the ``rst.el`` emacs package.
+Emacs_ support for reStructuredText_ is implemented as an Emacs_ major
+mode (``rst-mode``) provided by the ``rst.el`` Emacs_ package.
-For recent versions of Emacs, there's no need to install anything to
-get reST support; ``rst-mode`` is already available. So::
+Emacs_ distributions contain ``rst.el`` since version V23.1. However,
+a significantly updated version of ``rst.el`` is contained in Emacs_
+V24.3. This document describes the version of ``rst.el`` contained in
+Emacs_ V24.3. This version of ``rst.el`` has the internal version
- M-x rst-mode
+If you have Emacs_ V24.3 or later you do not need to install anything
+to get reST support. If you have an Emacs_ between V23.1 and V24.2 you
+may use the included version of ``rst.el`` or install a more recent
+one locally_ (recommended). In other cases you need to install
+``rst.el`` locally_ to get reST support.
-will work out of the box. If this works for you, please skip to the
-For older versions of Emacs, ``rst.el`` can be found in the
-``tools/editors/emacs/`` directory of the Docutils snapshot or
-repository. `A copy can also be downloaded here.
+Here are some steps to check your situation:
-In order to use ``rst-mode``, you need to put the ``rst.el`` in a
-directory located in your emacs ``load-path`` (use ``C-h v load-path``
+#. In Emacs_ switch to an empty buffer and try ::
+ M-x rst-mode
+ If this works you have ``rst.el`` installed somewhere. You can see
+ that it works if you find a string ``ReST`` in Emacs' modeline of
+ the current buffer. If this doesn't work you need to install
+ ``rst.el`` yourself locally_.
-Load rst-mode with::
+#. In the buffer you just switched to ``rst-mode`` try ::
- (require 'rst)
+ C-h v rst-version
-To enable ``rst-mode``, simply type ``M-x rst-mode``. Alternatively,
-you can modify ``auto-mode-alist`` to automatically turn it on
-whenever you visit reStructuredText_ documents::
+ If this fails you have a version of ``rst.el`` older than
+ V1.1.0. Either you have an old ``rst.el`` locally or you are using
+ an Emacs_ between V23.1 and V24.2. In this case it is recommended
+ that you install a more recent version of ``rst.el`` locally_.
+ You may also try ::
+ C-h v emacs-version
+ to find out your Emacs_ version.
+#. Check the version of ``rst.el``
+ The content of ``rst-version`` gives you the internal version of
+ ``rst.el``. The version contained in Emacs_ V24.3 and described here
+ is V1.4.0. If you have an older version you may or may not install
+ a more recent version of ``rst.el`` locally.
+If you decided to install locally please follow these steps.
+#. Download ``rst.el``
+ Download the most recent published version of ``rst.el`` from
+#. Put ``rst.el`` to a directory in ``load-path``
+ Use ::
+ C-h v load-path
+ If in the resulting list you find a directory in your home
+ directory put ``rst.el`` in this directory.
+ Make sure the directory is one of the first entries in
+ ``load-path``. Otherwise a version of ``rst.el`` which came with
+ Emacs_ may be found before your local version.
+ In Emacs_ see the info node ``Init File Examples`` for more
+ information on how to set up your Emacs_ initialization
+ machinery. Try ::
+ C-h i
+ sInit File Examples<Return>
+#. Enable ``rst-mode``
+ Add the following to your Emacs_ initialization setup ::
+ (require 'rst)
+ After you restarted Emacs_ ``rst.el`` is loaded and ready to be
+Switching ``rst-mode`` on
+By default ``rst-mode`` is switched on for files ending in ``.rst`` or
+``.rest``. If in a buffer you want to switch ``rst-mode`` on manually
+ M-x rst-mode
+If you want to use ``rst-mode`` in files with other extensions modify
+``auto-mode-alist`` to automatically turn it on whenever you visit
- (append '(("\\.txt$" . rst-mode)
- ("\\.rst$" . rst-mode)
- ("\\.rest$" . rst-mode)) auto-mode-alist))
+ (append '(("\\.txt\\'" . rst-mode)
+ ("\\.rst\\'" . rst-mode)
+ ("\\.rest\\'" . rst-mode)) auto-mode-alist))
-If have local variables enabled (see ``enable-local-variables`` in the
-Emacs manual), you can also add the following at the top of your
+Put the extensions you want in the correct place in the example
+above. Add more lines if needed.
+If have local variables enabled (try ``C-h v enable-local-variables``
+to find out), you can also add the following at the top of your
documents to trigger rst-mode::
.. -*- mode: rst -*-
@@ -110,194 +155,272 @@
``rst-mode`` automatically binds several keys for invoking special
-handy functions for editing ReStructuredText. As is the custom for
-Emacs major modes, most keys are bound to ``C-c C-LETTER``.
+functions for editing reStructuredText_. Since ``rst-mode`` contains a
+lot of functionality most key bindings consist of three
-If you insert an inline table-of-contents at the top of the document,
-you may want to add a hook to automatically update it everytime you
-adjust a section title::
+Following the Emacs_ conventions for major modes the key bindings of
+``rst-mode`` start with ``C-c C-<letter>``. The second key stroke
+selects a group of key bindings:
- (add-hook 'rst-adjust-hook 'rst-toc-update)
+ Commands to adjust the section headers and work with the hierarchy
+ they build.
-Additional configuration variables can be customized and can be found
-by browsing the source code for ``rst.el``.
+ Commands to compile the current reStructuredText_ document to
+ various output formats.
+ Commands to work with lists of various kinds.
+ Commands to manipulate the current region.
-The rst package does not completely parse all the reStructuredText_
-constructs, but it contains the ability to recognize the section
-decorations and to build the hierarchy of the document. What we call
-section decorations or adornments are the underlines or under- and
-overlines used to mark a section title.
+ Commands to create and manipulate a table of contents.
+At any stage of typing you may use ``C-h`` to get help on the
+available key bindings. I.e. ``C-c C-h`` gives you help on all key
+bindings while ``C-c C-r C-h`` gives you help on the commands for
+regions. This is handy if you forgot a certain key binding.
+Additional key bindings which have a certain meaning in other Emacs_
+modes are reused in ``rst-mode`` so you don't have to learn a
+different set of key bindings for editing reStructuredText_.
+In ``rst-mode`` try ::
+ C-h m
+to list all mode specific key bindings. Most of the key bindings are
+described in this tutorial.
+.. note:: The key bindings have been completely revamped in ``rst.el``
+ V1.0.0. This was necessary to make room for new
+ functionality. Some of the old bindings still work but give
+ a warning to use the new binding. In the output of ``C-h m``
+ these bindings show up as ``??``. The old bindings may be
+ removed completely in a later version.
+``rst-mode`` recognizes the section adornments building the section
+hierarchy of the document. Section adornments are the underlines or
+under- and overlines used to mark a section title. There are a couple
+of commands to work with section adornments. These commands are bound
+to key bindings starting with ``C-c C-a``.
Adjusting a Section Title
There is a function that helps a great deal to maintain these
-decorations: ``rst-adjust`` (bound to ``C-c C-a``, or ``C-=`` by
-default). This function is a Swiss army knife that can be invoked
-repeatedly and whose behaviour depends on context:
+adornments: ``rst-adjust`` (bound to ``C-c C-a C-a``, ``C-c C-=``, and
+``C-=``). This function is a Swiss army knife that can be invoked
+repeatedly and whose behavior depends on context:
-#. If there is an incomplete underline, e.g.::
+#. If there is an incomplete adornment, e.g. ::
My Section Title
- Invocation will complete the section title. You can simply enter a
- few characters of the title and invoke the function to complete it.
- It can also be used to adjust the length of the existing decoration
- when you need to edit the title.
+ invocation will complete the adornment. It can also be used to
+ adjust the length of the existing adornment when you need to edit
+ the title.
-#. If there is no section decoration, a decoration one level under the
- last encountered section level is added;
+#. If there is no section adornment at all, an adornment of the same
+ level as the last encountered section level is added. You can
+ simply enter a few characters of the title and invoke the function
+ to create the section adornment.
-#. If there is already a section decoration, it is promoted to the
- next level. You can invoke it like this repeatedly to cycle the
- title through the hierarchy of existing decorations.
+#. If there is already a section adornment, it is promoted one level
+ up. You can invoke it like this repeatedly to cycle the title
+ through the hierarchy of existing adornments.
Invoking the function with a negative prefix argument, e.g. ``C--
-C-=``, will effectively reverse the direction of decoration cycling.
+C-=``, will effectively reverse the direction of adornment cycling.
To alternate between underline-only and over-and-under styles, you can
-use a regular prefix argument, e.g. ``C-u C-=``. See the
+use a regular prefix argument, e.g. ``C-u C-=``. See the
documentation of ``rst-adjust`` for more description of the prefix
-arguments to alter the behaviour of the function.
+arguments to alter the behavior of the function.
Promoting and Demoting Many Sections
When you are re-organizing the structure of a document, it can be
-useful to change the level of a number of section titles. The same
+useful to change the level of a number of section titles. The same
key binding can be used to do that: if the region is active when the
binding is invoked, all the section titles that are within the region
-are promoted accordingly (or demoted, with negative prefix arg).
+are promoted accordingly (or demoted, with negative prefix argument).
-Redoing All the Decorations to Your Taste
+Redoing All the Adornments to Your Taste
-If you open someone else's file and the decorations it contains are
+If you open someone else's file and the adornments it contains are
unfamiliar, you may want to readjust them to fit your own preferred
-hierarchy of decorations. This can be difficult to perform by hand.
+hierarchy of adornments. This can be difficult to perform by hand.
However, you can do this easily by invoking
-``rst-straighten-decorations`` (``C-c C-s``), which operates on the
+``rst-straighten-adornments`` (``C-c C-a C-s``), which operates on the
-Customizations for Decorations
+Customizations for Adornments
-You can set the variable ``rst-preferred-decorations`` to a list of
-the decorations that you like to use for documents. Everyone has
-their preference. ``rst-default-indent`` can be set to the number of
-indent spaces preferred for the over-and-under decoration style.
+You can customize the variable ``rst-preferred-adornments`` to a list
+of the adornments that you like to use for documents.
+``rst-default-indent`` can be set to the number of indent spaces
+preferred for the over-and-under adornment style.
-Viewing the Hierarchy of Section Decorations
+Viewing the Hierarchy of Section Adornments
-You can visualize the hierarchy of the section decorations in the
-current buffer by invoking ``rst-display-decorations-hierarchy``,
-bound on ``C-c C-h``. A temporary buffer will appear with fake
-section titles rendered in the style of the current document. This
-can be useful when editing other people's documents to find out which
-section decorations correspond to which levels.
+You can visualize the hierarchy of the section adornments in the
+current buffer by invoking ``rst-display-adornments-hierarchy``, bound
+on ``C-c C-a C-d``. A temporary buffer will appear with fake section
+titles rendered in the style of the current document. This can be
+useful when editing other people's documents to find out which section
+adornments correspond to which levels.
+Movement and Selection
-Section Movement and Selection
+Movement and Selection for Sections
You can move the cursor between the different section titles by using
-the ``rst-backward-section`` and ``rst-forward-section`` functions, by
-default bound to the ``C-c C-p`` and ``C-c C-n`` keys.
+the ``rst-backward-section`` (``C-M-a``) and ``rst-forward-section``
+(``C-M-e``). To mark the section that cursor lies in, use
-To mark the section that cursor lies in, use ``rst-mark-section``
+The key bindings are modeled after other modes with similar
+Movements and Selection for Text Blocks
+The understanding of reStructuredText_ of ``rst-mode`` is used to set
+all the variables influencing Emacs' understanding of paragraphs. Thus
+all operations on paragraphs work as usual. For instance
+``forward-paragraph`` (``M-}``) works as usual.
-Operating on Blocks of Text
+Indenting and Filling
-Shifting Text Horizontally Intelligently
+Indentation of text plays a major role in the syntax of
+reStructuredText_. It is tedious to maintain the indentation
+manually. ``rst-mode`` understands most of the structure of
+reStructuredText_ allowing for sophisticated indentation and filling
+support described in this section.
-Due to the nature of reStructuredText_, lists are indented by two or
-three characters, e.g. bulleted lists use two chars::
+Indenting Text Blocks
- - Fruits
+``rst-mode`` supports indentation of text blocks by the command
+``rst-shift-region`` (``C-c C-r TAB``). Mark a region and use ``C-c
+C-r TAB`` to indent all blocks one tab to the right. Use ``M-- C-c C-r
+TAB`` to indent the region one tab to the left.
- - Bananas
- - Apples
- - Oranges
+You may use arbitrary prefix arguments such as ``M-2`` or ``M-- 2`` to
+determine the number of tabs you want to indent. A prefix of ``M-0``
+removes all indentation in the active region.
- - Veggies
+A tab is an indentation making sense for the block at hand in
+reStructuredText_ syntax. In some cases the exact indentation depends
+on personal taste. You may customize a couple of variables ``M-x
+customize-group<RET> rst-indent<RET>`` to match your taste.
- - Zucchini
- - Chick Peas
+Indenting Lines While Typing
-while enumerated lists are indented by 3 or more characters ::
+In Emacs_ the ``TAB`` key is often used for indenting the current
+line. ``rst-mode`` implements this for the sophisticated indentation
+rules of reStructuredText_. Pressing ``TAB`` cycles through the
+possible tabs for the current line. In the same manner
+``newline-and-indent`` (``C-j``) indents the new line properly.
- 9. Apples
+This is very handy while writing lists. Consider this
+reStructuredText_ bullet list with the cursor at ``@``::
- Oranges are tasty.
+ * Level 1
- 10. Oranges
+ * Level 2@
- Oranges are zesty.
+Type ``C-j`` twice to get this::
-To this effect, when shifting text, it can be useful to have functions
-which understand which indent to use by using the context around the
-region. Those functions are ``rst-shift-region-right`` and
+ * Level 1
-You can use ``C-c C-r`` and ``C-c C-l`` to shift the active region.
-These bindings are similar to the ones provided by python-mode for
-editing python code and behave similarly. They automatically inspect
-the lines of text before the currently selected region to determine
-what the appropriate column positions are.
+ * Level 2
-Bulleting and Enumerating Lists
+Now you an enter text at this level, or start a new list item by
+typing another ``*``. Or you may type ``TAB`` to reduce the
-Sometimes it can be useful to insert bullet list markers enumeration
-number before a number of lines or paragraphs. You can do this easily
-by invoking ``rst-enumerate-region`` (``C-c C-e``), for example, the
+ * Level 1
+ * Level 2
+Typing another ``TAB`` gets you to the first level::
+ * Level 1
- 1. Apples
+ * Level 2
- 2. Oranges
- 3. Bananas
-``rst-listify-region`` (``C-c C-b``) does the same, but only adds
-bullet list markers, e.g.::
+``rst-mode`` understanding the indentation rules of reStructuredText_
+also supports filling paragraphs. Just use ``fill-paragraph``
+(``M-q``) as you do in other modes.
+Operating on Lists
+Lists are supported in various flavors in reStructuredText_.
+``rst-mode`` understands reStructuredText_ lists and offers some
+support for operating on lists. Key bindings for commands for
+operating on lists start with ``C-c C-l``.
+Bulleted and Enumerated Lists
+If you have a couple of plain lines you want to turn into an
+enumerated list you can invoke ``rst-enumerate-region`` (``C-c C-l
+C-e``). For example, the following region ::
- - Apples
+ 1. Apples
- - Oranges
+ 2. Oranges
- - Bananas
+ 3. Bananas
+``rst-bullet-list-region`` (``C-c C-l C-b``) does the same, but
+results in a bullet list ::
+ * Apples
+ * Oranges
+ * Bananas
By default, each paragraph starting on the leftmost line in the
highlighted region will be taken to be a single list or enumeration
item, for example, enumerating the following::
@@ -333,48 +456,59 @@
- - Apples
- - Oranges
- - Bananas
+ * Apples
+ * Oranges
+ * Bananas
Straightening Existing Bullet List Hierarchies
-If you invoke ``rst-straighten-bullets-region`` (C-c C-w), the
-existing bullets in the highlighted region will be replaced to reflect
-their respective level. This does not make a difference in the
-document structure that reStructuredText_ defines, but looks better in
-the input file, for example, if all of the top-level bullet items use
-the character ``-``, and all of the 2nd level items use ``*``, etc.
+If you invoke ``rst-straighten-bullets-region`` (``C-c C-l C-s``), the
+existing bullets in the active region will be replaced to reflect
+their respective level. This does not make a difference in the
+document structure that reStructuredText_ defines, but looks better
+in, for example, if all of the top-level bullet items use the
+character ``-``, and all of the 2nd level items use ``*``, etc.
+Inserting a List Item
+To start a new list you may invoke ``rst-insert-list`` (``C-c C-l
+C-i``). You may choose from an item style supported by
+You may also invoke ``rst-insert-list`` at the end of a list item. In
+this case it inserts a new line containing the markup for the a list
+item on the same level.
+Operating on Other Text Blocks
Creating and Removing Line Blocks
To create line blocks, first select the region to convert and invoke
-``rst-toggle-line-block`` with ``C-c C-d``, for example, the
+``rst-line-block-region`` ``C-c C-r C-l``. For example, the following
-This works even if the region is indented. To remove line blocks,
+This works even if the region is indented. To remove line blocks,
select a region and invoke with a prefix argument.
Commenting a Region of Text
-If you use the Emacs ``comment-region`` function (bound to ``C-c
-C-c``), the appropriate comment syntax will be added to the active
-block of text::
+``rst-mode`` understands reStructuredText_ comments. Use
+``comment-dwim`` (``M-;``) to work on comments as usual::
@@ -382,56 +516,93 @@
- .. Apples
- .. Oranges
- .. Bananas
+To remove a comment you have to tell this to ``comment-dwim``
+explicitly by using a prefix argument (``C-u M-;``).
+Please note that only indented comments are supported properly by the
+parts of ``comment-dwim`` working on regions.
Converting Documents from Emacs
-The major mode provides a number of functions for running documents
-being edited through the docutils tools.
+``rst-mode`` provides a number of functions for running documents
+being edited through the docutils tools. The key bindings for these
+commands start with ``C-c C-c``.
-The main generic function is ``rst-compile`` (``C-c 1``). This
-function basically creates a compilation command with the correct
-output name for the current buffer and then invokes Emacs' compile
-function. It also looks for the presence of a ``docutils.conf``
-configuration file in the parent directories and adds it to the
-cmdline options. There is also an alternative function in case you
-often need run your document in a second toolset (``C-c 2``).
+The main generic function is ``rst-compile`` (``C-c C-c C-c``). It
+invokes a compilation command with the correct output name for the
+current buffer and then invokes Emacs' compile function. It also looks
+for the presence of a ``docutils.conf`` configuration file in the
+parent directories and adds it to the command line options. There is also
+``rst-compile-alt-toolset`` (``C-c C-c C-a``) in case you often need
+run your document in a second toolset.
You can customize the commands being used by setting
``rst-compile-primary-toolset`` and ``rst-compile-secondary-toolset``.
Other commands are available for other formats:
-- ``rst-compile-pseudo-region`` (``C-c 3``): When crafting documents,
- it is often convenient to view which data structures docutils will
- parse them into. You can use to run the active region through
- ``rst2pseudoxml.py`` and have the output automatically be displayed
- in a new buffer.
+* ``rst-compile-pseudo-region`` (``C-c C-c C-x``)
+ When crafting documents, it is often convenient to view which data
+ structures docutils will parse them into. You can use to run the
+ active region through ``rst2pseudoxml.py`` and have the output
+ automatically be displayed in a new buffer.
-- ``rst-compile-pdf-preview`` (``C-c 4``): Convert the current
- document to PDF and launch a viewer on the results.
+* ``rst-compile-pdf-preview`` (``C-c C-c C-p``)
+ Convert the current document to PDF and launch a viewer on the
-- ``rst-compile-slides-preview`` (``C-c 5``): Convert the current
- document to S5 slides and view in a web browser.
+* ``rst-compile-slides-preview`` (``C-c C-c C-s``): Convert the
+ current document to S5 slides and view in a web browser.
+Emacs_ has a package called ``imenu``. ``rst-mode`` supports Imenu by
+adding a function to convert the structure of a reStructuredText_
+buffer to an Imenu index. Thus you can use invoke ``imenu`` (``M-x
+imenu``) to navigate through the section index or invoke
+``imenu-add-to-menubar`` (``M-x imenu-add-to-menubar``) to add an
+Imenu menu entry to Emacs' menu bar.
+Using which function
+As a side effect of Imenu support the ``which-func`` package is also
+supported. Invoke ``which-function-mode`` (``M-x
+which-function-mode``) to add the name of the current section to the
+mode line. This is especially useful if you navigate through documents
+with long sections which do not fit on a single screen.
+Using the Table of Contents
+The sections in a reStructuredText_ document can be used to form a
+table of contents. ``rst-mode`` can work with such a table of contents
+in various forms. Key bindings for these commands start with ``C-c
+Navigating Using the Table of Contents
When you are editing long documents, it can be a bit difficult to
-orient yourself in the structure of your text. To that effect, a
-function is provided that quickly parses the document and presents a
-hierarchically indented table of contents of the document in a
-temporary buffer, in which you can navigate and press ``Return`` to go
-to a specific section.
+orient yourself in the structure of your text. To that effect, a
+function is provided that presents a hierarchically indented table of
+contents of the document in a temporary buffer, in which you can
+navigate and press ``Return`` to go to a specific section.
-Invoke this function (``rst-toc``) with ``C-c C-t``. It should
-present a temporary buffer that looks something like this::
+Invoke ``rst-toc`` (``C-c C-t C-t``). It presents a temporary buffer
+that looks something like this::
Table of Contents:
@@ -450,27 +621,28 @@
-When you select a section title (press ``RET``), the temporary buffer
-disappears and you are left with the cursor positioned at the chosen
+When you move the cursor to a section title and press ``RET`` or
+``f``, the temporary buffer disappears and you are left with the
+cursor positioned at the chosen section. Use ``q`` in this buffer to
+just quit it without moving the cursor in the original document. Use
+``z`` to zap the buffer altogether.
Inserting a Table of Contents
Oftentimes in long text documents that are meant to be read directly,
-a Table of Contents is inserted at the beginning of the text. This is
-the case for most internet FAQs, for example. In reStructuredText_
-documents, since the table of contents is automatically generated by
-the parser with the ``.. contents::`` directive, people generally have
-not been adding a text table of contents to their source documents,
-and partly because it is too much trouble to edit and maintain.
+a table of contents is inserted at the beginning of the text. In
+reStructuredText_ documents, since the table of contents is
+automatically generated by the parser with the ``.. contents::``
+directive, people generally have not been adding an explicit table of
+contents to their source documents, and partly because it is too much
+trouble to edit and maintain.
-The emacs support for reStructuredText_ provides a function to insert
-such a table of contents in your document. Since it is not meant to
+The Emacs_ support for reStructuredText_ provides a function to insert
+such a table of contents in your document. Since it is not meant to
be part of the document text, you should place such a table of
-contents within a comment, so that it is ignored by the parser. This
-is the favoured usage::
+contents within a comment, so that it is ignored by the parser. This
+is the favored usage::
@@ -490,135 +662,159 @@
Just place the cursor at the top-left corner where you want to insert
-the TOC and invoke the function with ``C-c C-i``. The table of
-contents will display all the section titles that are under the
-location where the insertion occurs. This way you can insert local
-table of contents by placing them in the appropriate location.
+the TOC and invoke the function ``rst-toc-insert`` with ``C-c C-t
+C-i``. The table of contents will display all the section titles that
+are under the location where the insertion occurs. This way you can
+insert local table of contents by placing them in the appropriate
-If you have deep nesting of sections, you can use a numeric prefix
-argument to limit the depth of rendering of the TOC.
+You can use a numeric prefix argument to limit the depth of rendering
+of the TOC.
-You can also customize the look of the TOC by setting the values of
-the following variables:: ``rst-toc-indent``,
+You can customize the look of the TOC by setting the values of the
+following variables: ``rst-toc-indent``, ``rst-toc-insert-style``,
- The table-of-contents inserted by ``rst-mode`` has text properties
- added to it so that if you type ``C-c C-f`` while the cursor is on
- one of its entries, the cursor will jump to the corresponding
- section in the document.
Maintaining the Table of Contents Up-to-date
One issue is that you will probably want to maintain the inserted
-table of contents up-to-date. There is a function that will
-automatically look for the inserted TOC (``rst-toc-update``)
-and it can be added to a hook on the section decoration adjustment
-function, so that every time you adjust a section title, the TOC is
-updated. Add this functionality with the following emacs
+table of contents up-to-date. ``rst-toc-update`` (``C-c C-t C-u``)
+will automatically locate an inserted table of contents following a
+``.. contents::`` directive.
- (add-hook 'rst-adjust-hook 'rst-toc-update)
+Syntax Highlighting via Font-Lock
-You can invoke the update on the current buffer with ``C-c C-u``.
+``rst-mode`` provides syntax highlighting for nearly all to
+Use ``customize-group rst-faces`` to customize the faces used for
-Syntax Highlighting via Font-Lock
-``rst-mode`` also provides syntax highlighting to reStructuredText_
-constructs. (This mode was written by Stefan Merten.)
+Some aspects of ``rst-mode`` can be configured through the
+customization feature of Emacs_. Try ::
-Lazy syntax coloring is implemented for many of the constructs that
-reStructuredText_ prescribes. By default, the font-lock colouring is
-performed lazily. If you don't like this, you can turn this off by
-setting the value of ``rst-mode-lazy``. You can also change the
-various colours (see the source file for the whole list of
+ M-x customize-group<RETURN>rst
-``font-lock`` syntax highlighting is enabled by default. If you prefer
-to turn off syntax highlighting (on some machines it can slow down
-editing a little bit), you can use the following in your Emacs
+for all customizations or use the respective menu entry. Those
+customizations which are useful for many people are described in this
- (setq font-lock-global-modes '(not rst-mode))
+Customizing Section Title Formatting
+For a couple of things the reStructuredText_ syntax offers a choice of
+options on how to do things exactly. Some of these choices influence
+the operation of ``rst.el`` and thus can be configured. The
+customizations are contained in the ``rst-adjust`` group.
+Among these things is the exact layout of section adornments. In fact
+reStructuredText_ prescribes only the characters and how these
+characters must be used but the exact use of concrete adornments may
+be different in every source file. Using the customization option
+``rst-preferred-adornments`` you can tell ``rst-mode`` on the exact
+sequence of adornments you prefer to markup the different levels of
-The ``rst-faces`` group contains all necessary for customizing
-fonts. The default settings use standard ``font-lock-*-face`` so if
-you set these to your liking they are probably good in rst-mode also.
+The title text of over-and-under adornments may be indented.
+``rst-default-indent`` tells ``rst-mode`` how many positions a
+over-and-under adornment should be indented.
-The group is contained in the faces group as well as in the rst group.
+Finally if you create a completely new section adornment by
+``rst-adjust`` the question is on what level the new section adornment
+should be. ``rst-new-adornment-down`` can be used to create one level
+lower adornments than the previous section title. By default the new
+section title is on the same level as the previous one.
+Please note, that normally the given adornments of a buffer are
+preferred over your preferences, however. See `Redoing All the
+Adornments to Your Taste`_ for a method to change this for the whole
-The ``rst-faces-defaults`` group contains all necessary for
-customizing the default fonts used for section title faces.
+reStructuredText_ uses indentation a lot to signify a certain meaning.
+In some cases the exact amount of indentation is prescribed by the
+syntax while in some cases the exact indentation is not fixed. The
+customization group ``rst-indent`` allows to customize the amount of
+indentation in these cases.
-The general idea for section title faces is to have a non-default
-background but do not change the background. The section level is
-shown by the lightness of the background color. If you like this
-general idea of generating faces for section titles but do not like
-the details this group is the point where you can customize the
-details. If you do not like the general idea, however, you should
-customize the faces used in ``rst-adornment-faces-alist``.
+In field lists the content of a field needs to be indented relative to
+the field label. ``rst-indent-field`` tells ``rst-mode`` the amount of
+indentation to use for field content. A value of zero always indents
+according to the content after the field label.
-Note: If you are using a dark background please make sure the variable
-``frame-background-mode`` is set to the symbol dark. This triggers
-some default values which are probably right for you.
+The indentation of literal blocks is controlled by
+``rst-indent-literal-normal`` and ``rst-indent-literal-minimized``.
+The first is used when the leading literal tag (``::``) appears alone
+on a line. The second is used when the minimized style is used where
+the literal tag follows some text.
-The group is contained in the ``rst-faces`` group.
+The indentation of comments is controlled by ``rst-indent-comment``.
+Of course this makes only sense for the indented comments of
-All customizable features have a comment explaining their
-meaning. Refer to the customization of your Emacs (try ``M-x
+Customization option ``rst-indent-width`` gives the default
+indentation when there are no other hints on what amount of
+indentation to use.
+The faces used for font-locking can be defined in the ``rst-faces``
+customization group. The customization options ending in ``-face`` are
+only there for backward compatibility so please leave them as they
-Other Useful Settings
+reStructuredText_ sets no limit on the nesting of sections. By default
+there are six levels of fontification defined. Section titles deeper
+than six level have no special fontification - only the adornments are
+fontified. The exact mapping from a level to a face is done by by
+``rst-adornment-faces-alist``, however. So if you need fontification
+deeper than six levels you may want to customize this option. You may
+also want to customize it if you like the general idea of section
+title fontification in ``rst-mode`` but for instance prefer a reversed
-This section covers general emacs text-mode settings that are useful
-in the context of reStructuredText_ conventions. These are not
-provided by ``rst.el`` but you may find them useful specifically for
+This section covers some general aspects using Emacs_ for editing
+reStructuredText_ source. They are not directly related to
+``rst-mode`` but may enhance your experience.
-Consult the Emacs manual for more text-mode customizations. In
+Consult the Emacs_ manual for more ``text-mode`` customizations. In
particular, you may be interested in setting the following variables,
-functions and modes that pertain somewhat to text-mode:
+functions and modes that pertain somewhat to ``text-mode``:
Editing Tables: Emacs table mode
You may want to check out `Emacs table mode`_ to create an edit
-tables, it allows creating ascii tables compatible with
+tables, it allows creating ASCII tables compatible with
.. _Emacs table mode: http://table.sourceforge.net/
Since reStructuredText punts on the issue of character processing,
-here are some useful resources for Emacs users in the Unicode world:
+here are some useful resources for Emacs_ users in the Unicode world:
* `xmlunicode.el and unichars.el from Norman Walsh
@@ -626,7 +822,7 @@
* `An essay by Tim Bray, with example code
-* For Emacs users on Mac OS X, here are some useful useful additions
+* For Emacs_ users on Mac OS X, here are some useful useful additions
to your .emacs file.
- To get direct keyboard input of non-ASCII characters (like
@@ -645,7 +841,7 @@
- To enable the display of all characters in the Mac-Roman charset,
first create a fontset listing the fonts to use for each range of
- characters using charsets that Emacs understands::
+ characters using charsets that Emacs_ understands::
@@ -660,7 +856,7 @@
- - To enable cooperation between the system clipboard and the Emacs
+ - To enable cooperation between the system clipboard and the Emacs_
kill ring, add this line::
@@ -668,43 +864,32 @@
Other useful resources are in `Andrew Choi's Emacs 21 for Mac OS X
-No matter what platform (or editor) you're using, I recommend the
-ProFont__ programmer's font. It's monospaced, small but readable,
-similar characters are visually distinctive (like "I1l|", "0O", "ao",
-and ".,:;"), and free.
-- The automatic section adjustment and table of contents features were
- written by Martin Blais;
-- Syntax highlighting was implemented by Stefan Merten;
-- Various other functions were implemented by David Goodger.
+Part of the original code of ``rst.el`` has been written by Martin
+Blais and David Goodger and Wei-Wei Guo. The font-locking came from
+Most of the code has been modified, enhanced and extended by Stefan
+Merten who also is the current maintainer of ``rst.el``.
-On 2005-10-30, ``rst.el`` integrated and replaced the contents of the
.. _Emacs: http://www.gnu.org/software/emacs/emacs.html
.. _reStructuredText: http://docutils.sf.net/rst.html
+.. _Docutils: http://docutils.sf.net/
+.. LocalWords: reST utf Merten Blais rst el docutils modeline emacs
- sentence-end-double-space: t
+.. LocalWords: Init mEmacs sInit alist setq txt overlines RET nd py
+.. LocalWords: dwim conf toolset pseudoxml pdf Imenu imenu menubar
+.. LocalWords: func toc xmlunicode unichars eacute charset fontset
+.. LocalWords: kTextEncodingISOLatin charsets monaco ascii latin
+.. LocalWords: iso unicode Choi's Goodger Guo
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.