Merged trunk r5043:5619 to adjacent-citations branch.

git-svn-id: http://svn.code.sf.net/p/docutils/code/branches/adjacent-citations@5621 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

1 files changed, 327 insertions, 302 deletions

diff --git a/docs/user/emacs.txt b/docs/user/emacs.txt
index e9e403c3f..c61d781c6 100644
--- a/docs/user/emacs.txt
+++ b/docs/user/emacs.txt
@@ -5,7 +5,7 @@
 ========================================
 
 :Author: Martin Blais <blais@furius.ca>
-:Date: $Date$
+:Date: 2007-12-03
 :Abstract:
 
     High-level description of the existing emacs support for editing
@@ -15,30 +15,34 @@
 .. contents::
 ..
     1   Introduction
-    2   Basic Setup
-    3   Section Decoration Adjustment
-      3.1  Promoting and Demoting Many Sections
-      3.2  Redoing All the Decorations to Your Taste
-      3.3  Customizations
-    4   Viewing the Hierarchy of Section Decorations
-    5   Table of Contents
-      5.1  Inserting a Table of Contents
-      5.2  Maintaining the Table of Contents Up-to-date
-    6   Navigating Between the Section Titles
-    7   Shifting Bullet List Levels
-    8   Bulleting and Enumerating Lists
-      8.1  Straightening Existing Bullet List Hierarchies
-    9   Creating and Remove Line Blocks
-    10  Major Mode for Editing reStructuredText Documents
-    11  Converting Documents from Emacs
-    12  Other / External Useful Emacs Settings
-      12.1  Settings for Filling Lists
-      12.2  ``text-mode`` Settings
-      12.3  Editing Tables: Emacs table mode
-      12.4  Character Processing
-    13  Credits
-    14  Obsolete Files
-    15  Future Work
+    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
 
 
 Introduction
@@ -46,49 +50,75 @@ Introduction
 
 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
-some support for the conventions that reStructuredText_ specifies:
-``rst.el``.
+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
+them.
 
-This document describes the most important features that it provides,
-how to setup your emacs to use them and how to invoke them.
 
+Installation
+============
 
-Basic Setup
-===========
+The emacs support is implemented as an Emacs major mode (``rst-mode``)
+provided by the ``rst.el`` emacs package. In order to use
+``rst-mode``, you need to put the ``rst.el`` in a directory located in
+your emacs ``load-path``, and to load it with::
 
-The emacs support is completely provided by the ``rst.el`` emacs
-package.  In order to use these features, you need to put the file in
-your emacs load-path, and to load it with::
+  (require 'rst)
 
-  (require 'rst)  ;; or (load "rst")
+To enable ``rst-mode``, simple type ``M-x rst-mode``. Alternatively,
+you can modify ``auto-mode-alist`` to automatically turn it on
+whenever you visit reStructuredText_ documents::
 
-Additional configuration variables can be customized and can be found
-by browsing the source code for ``rst.el``.
+   (setq auto-mode-alist
+         (append '(("\\.txt$" . rst-mode)
+                   ("\\.rst$" . rst-mode)
+                   ("\\.rest$" . rst-mode)) auto-mode-alist))
 
-Then you will want to bind keys to the most common commands it
-provides.  A standard text-mode hook function is maintained and
-provided by the package for this use, set it up like this::
+If have local variables enabled (see ``enable-local-variables`` in the
+Emacs manual), you can also add the following at the top of your
+documents to trigger rst-mode::
 
-  (add-hook 'text-mode-hook 'rst-text-mode-bindings)
+   .. -*- mode: rst -*-
 
-A prefix map is defined for all the ``rst.el`` commands.  By default,
-it is bound to the mode-specific-map and ``p``, e.g. ``C-c p ...``.
+Or this at the end of your documents::
 
+   ..
+      Local Variables:
+      mode: rst
+      End:
+
+``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``.
+
+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::
+
+  (add-hook 'rst-adjust-hook 'rst-toc-update)
+
+Additional configuration variables can be customized and can be found
+by browsing the source code for ``rst.el``.
 
-Section Decoration Adjustment
-=============================
+
+Section Decorations
+===================
 
 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
+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.
 
+Adjusting a Section Title
+-------------------------
+
 There is a function that helps a great deal to maintain these
-decorations: ``rst-adjust`` (bound on ``C-c p a``, ``C-c p =`` or
-``C-=`` by default).  This function is a Swiss army knife that can be
-invoked repeatedly and whose behaviour depends on context:
+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:
 
 #. If there is an incomplete underline, e.g.::
 
@@ -114,7 +144,6 @@ 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.
 
-
 Promoting and Demoting Many Sections
 ------------------------------------
 
@@ -124,150 +153,55 @@ 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).
 
-
 Redoing All the Decorations to Your Taste
 -----------------------------------------
 
 If you open someone else's file and the decorations 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.
-However, you can do this easily by invokeing
-``rst-straighten-decorations`` (C-c p s), which operates on the entire
-buffer.
+hierarchy of decorations. 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
+entire buffer.
 
-
-Customizations
---------------
+Customizations for Decorations
+------------------------------
 
 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.
 
-
 Viewing the Hierarchy of Section Decorations
-============================================
+--------------------------------------------
 
 You can visualize the hierarchy of the section decorations in the
 current buffer by invoking ``rst-display-decorations-hierarchy``,
-bound on ``C-c p h``.  A temporary buffer will appear with fake
+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.
 
 
-Table of Contents
-=================
+Section Movement and Selection
+==============================
 
-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.
+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.
 
-Invoke this function (``rst-toc``) with ``C-c p t``.  It should
-present a temporary buffer that looks something like this::
-
-  Table of Contents: 
-  Debugging Meta-Techniques
-    Introduction
-    Debugging Solution Patterns
-      Recognize That a Bug Exists
-      Subdivide and Isolate
-      Identify and Verify Assumptions
-      Use a Tool for Introspection
-      Change one thing at a time
-      Learn about the System
-    Understanding a bug
-    The Basic Steps in Debugging
-    Attitude
-      Bad Feelings
-      Good Feelings
-    References
-
-When you select a section title, the temporary buffer disappears and
-you are left with the cursor positioned at the chosen section.
+To mark the section that cursor lies in, use ``rst-mark-section``
+(``C-c C-m``).
 
 
-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.
-
-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::
-  .. 
-      1  Introduction
-      2  Debugging Solution Patterns
-        2.1  Recognize That a Bug Exists
-        2.2  Subdivide and Isolate
-        2.3  Identify and Verify Assumptions
-        2.4  Use a Tool for Introspection
-        2.5  Change one thing at a time
-        2.6  Learn about the System
-      3  Understanding a bug
-      4  The Basic Steps in Debugging
-      5  Attitude
-        5.1  Bad Feelings
-        5.2  Good Feelings
-      6  References
-
-Just place the cursor at the top-left corner where you want to insert
-the TOC and invoke the function with ``C-c p 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.
-
-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 also customize the look of the TOC by setting the values of
-the following variables:: ``rst-toc-indent``,
-``rst-toc-insert-style``, ``rst-toc-insert-max-level``.
-
-
-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-insert-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
-configuration::
-
-  (add-hook 'rst-adjust-hook 'rst-toc-insert-update)
-
-You can invoke the update on the current buffer with ``C-c p u``.
-
-
-Navigating Between the Section Titles
-=====================================
-
-You can move the cursor between the different sections by using the
-``rst-backward-section`` and ``rst-forward-section`` functions, by
-default bound to the ``C-c p p`` and ``C-c p n`` keys (also ``C-c
-C-p`` and ``C-c C-n``).
-
-
-Shifting Bullet List Levels
+Operating on Blocks of Text
 ===========================
 
-Due to the nature of reStructuredText_, bulleted lists are indented by
-two characters (unless they are part of a blockquote), e.g. ::
+Shifting Text Horizontally Intelligently
+----------------------------------------
+
+Due to the nature of reStructuredText_, lists are indented by two or
+three characters, e.g. bulleted lists use two chars::
 
    - Fruits
 
@@ -280,7 +214,7 @@ two characters (unless they are part of a blockquote), e.g. ::
      - Zucchini
      - Chick Peas
 
-Enumerated lists, however, as indented by 3 or more characters ::
+while enumerated lists are indented by 3 or more characters ::
 
    9. Apples
 
@@ -290,25 +224,24 @@ Enumerated lists, however, as indented by 3 or more characters ::
 
        Oranges are zesty.
 
+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
+``rst-shift-region-left``.
 
-To this effect, when re-organizing bullet lists, it can be useful to
-have functions to shift regions of text by appropriate indents, which
-are figured out automatically by emacs.  
-
-You can use ``C-c C-r`` and ``C-c C-l`` to shift the current region
-(``rst-shift-region-right`` and ``rst-shift-region-left``).  These
-bindings are similar to the ones provided by python-mode for editing
-python code and behave similarly.   They inspect the lines of text
-before the currently selected region to determine what the appropriate
-column positions are.
+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.
 
 
 Bulleting and Enumerating Lists
-===============================
+-------------------------------
 
 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 p e``), for example, the
+by invoking ``rst-enumerate-region`` (``C-c C-e``), for example, the
 following::
 
   Apples
@@ -325,7 +258,7 @@ becomes::
 
   3. Bananas
 
-``rst-listify-region`` (``C-c p b``) does the same, but only adds
+``rst-listify-region`` (``C-c C-b``) does the same, but only adds
 bullet list markers, e.g.::
 
   Apples
@@ -337,9 +270,9 @@ bullet list markers, e.g.::
 becomes::
 
   - Apples
-  
+
   - Oranges
-  
+
   - Bananas
 
 
@@ -347,24 +280,24 @@ 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::
 
-   An apple a day 
+   An apple a day
    keeps the doctor away.
-   
-   But oranges 
+
+   But oranges
    are tastier than apples.
-   
+
    If you preferred bananas
    you may be
    a monkey.
 
 Will result in::
 
-   1. An apple a day 
+   1. An apple a day
       keeps the doctor away.
-      
-   2. But oranges 
+
+   2. But oranges
       are tastier than apples.
-      
+
    3. If you preferred bananas
       you may be
       a monkey.
@@ -382,12 +315,10 @@ becomes::
   - Oranges
   - Bananas
 
-
-
 Straightening Existing Bullet List Hierarchies
-----------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you invoke ``rst-straighten-bullets-region`` (C-c p w), the
+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
@@ -395,11 +326,11 @@ 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.
 
 
-Creating and Remove Line 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 p B``, for example, the
+``rst-toggle-line-block`` with ``C-c C-d``, for example, the
 following::
 
   Apples
@@ -416,112 +347,227 @@ This works even if the region is indented.  To remove line blocks,
 select a region and invoke with a prefix argument.
 
 
-Major Mode for Editing reStructuredText Documents
-=================================================
-
-The great majority of the functionality for supporting
-reStructuredText_ can be invoked directly from Emacs' vanilla
-text-mode.
-
-However, there is also a major mode that adds syntax highlighting to
-reStructuredText_ constructs.  This mode was written by Stefan Merten
-[#]_.  It mostly provides lazy syntax coloring for many of the
-constructs that reStructuredText_ prescribes.
-
-To enable this mode, type ``M-x rst-mode`` or you can set up an
-``auto-mode-alist`` to automatically turn it on whenever you visit
-reStructuredText_ documents::
+Commenting a Region of Text
+---------------------------
 
-   (add-to-list 'auto-mode-alist '("\\.rst$" . rst-mode) )
+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::
 
-If have local variables enabled (see ``enable-local-variables`` in the
-Emacs manual), you can also add the following at the top of your
-documents to trigger rst-mode::
-
-   .. -*- mode: rst -*-
-
-Or add this at the end of your documents::
+  Apples
+  Oranges
+  Bananas
 
-   ..
-      Local Variables:
-      mode: rst
-      End:
+becomes::
 
-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 customizable faces).
+  .. Apples
+  .. Oranges
+  .. Bananas
 
-.. [#] This mode used to be provided by the file ``rst-mode.el`` and
-   has now been integrated with the rest of the emacs code.
 
 
 Converting Documents from Emacs
 ===============================
 
-We provide a function (``rst-compile``) for invoking the document
-converters from within emacs.  It is bound on ``C-c p c``.
+The major mode provides a number of functions for running documents
+being edited through the docutils tools.
 
-This function basically creates a compilation command with the correct
+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.  You can customize which tool is used to perform the
-conversion and some standard options to always be added as well.
+cmdline options. There is also an alternative function in case you
+often need run your document in a second toolset (``C-c 2``).
+
+You can customize the commands being used by setting
+``rst-compile-primary-toolset`` and ``rst-compile-secondary-toolset``.
 
-Invocation uses the toolset indicated by
-``rst-compile-primary-toolset`` (default is ``'html``).  Invocation
-with a prefix argument uses ``rst-compile-secondary-toolset`` (default
-is ``'latex``).
+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-pdf-preview`` (``C-c 4``): Convert the current
+  document to PDF and launch a viewer on the results.
+  
+- ``rst-compile-slides-preview`` (``C-c 5``): Convert the current
+  document to S5 slides and view in a web browser.
+
+
+Table-of-Contents Features
+==========================
+
+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.
+
+Invoke this function (``rst-toc``) with ``C-c C-t``.  It should
+present a temporary buffer that looks something like this::
+
+  Table of Contents:
+  Debugging Meta-Techniques
+    Introduction
+    Debugging Solution Patterns
+      Recognize That a Bug Exists
+      Subdivide and Isolate
+      Identify and Verify Assumptions
+      Use a Tool for Introspection
+      Change one thing at a time
+      Learn about the System
+    Understanding a bug
+    The Basic Steps in Debugging
+    Attitude
+      Bad Feelings
+      Good Feelings
+    References
+
+When you select a section title (press ``RET``), the temporary buffer
+disappears and you are left with the cursor positioned at the chosen
+section.
+
+
+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.
+
+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::
+  ..
+      1  Introduction
+      2  Debugging Solution Patterns
+        2.1  Recognize That a Bug Exists
+        2.2  Subdivide and Isolate
+        2.3  Identify and Verify Assumptions
+        2.4  Use a Tool for Introspection
+        2.5  Change one thing at a time
+        2.6  Learn about the System
+      3  Understanding a bug
+      4  The Basic Steps in Debugging
+      5  Attitude
+        5.1  Bad Feelings
+        5.2  Good Feelings
+      6  References
+
+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.
+
+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 also customize the look of the TOC by setting the values of
+the following variables:: ``rst-toc-indent``,
+``rst-toc-insert-style``, ``rst-toc-insert-max-level``.
 
 .. note:: 
 
-   In general it is preferred to use a Makefile to automate the
-   conversion of many documents or a hierarchy of documents.  The
-   functionality presented above is meant to be convenient for use on
-   single files.
+   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
+configuration::
 
+  (add-hook 'rst-adjust-hook 'rst-toc-update)
 
-Other / External Useful Emacs Settings
-======================================
+You can invoke the update on the current buffer with ``C-c C-u``.
 
-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
-reStructuredText_ documents.
+
+Syntax Highlighting via Font-Lock
+=================================
+
+``rst-mode`` also provides syntax highlighting to reStructuredText_
+constructs. (This mode was written by Stefan Merten.)
+
+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
+customizable faces).
+
+``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
+configuration::
+
+  (setq font-lock-global-modes '(not rst-mode))
 
 
-Settings for Filling Lists
---------------------------
+Face Customization
+------------------
 
-One problem with the default text-mode settings is that *filling* long
-lines in bullet and enumerated lists that do not have an empty line
-between them merges them together, e.g.::
+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.
 
-     - Bananas;
-     - One Apple a day keeps the doctor away, and eating more keeps the pirates at bay;
-     - Oranges;
+The group is contained in the faces group as well as in the rst group.
 
-Becomes::
 
-     - Bananas; One Apple a day keeps the doctor away, and eating more
-     - keeps the pirates at bay; Oranges;
+Default Fonts
+~~~~~~~~~~~~~
 
-This is usually not what you want. What you want is this::
+The ``rst-faces-defaults`` group contains all necessary for
+customizing the default fonts used for section title faces.
 
-     - Bananas;
-     - One Apple a day keeps the doctor away, and eating more keeps
-       the pirates at bay;
-     - Oranges;
+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``.
 
-The problem is that emacs does not recognize the various consecutive
-items as forming paragraph boundaries.  You can fix this easily by
-changing the global value of the parapraph boundary detection to
-recognize such lists, using the ``rst-set-paragraph-separation``
-function::
+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.
 
-   (add-hook 'text-mode-hook 'rst-set-paragraph-separation)
+The group is contained in the ``rst-faces`` group.
 
+All customizable features have a comment explaining their
+meaning. Refer to the customization of your Emacs (try ``M-x
+customize``).
+
+
+
+Other Useful Settings
+=====================
+
+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
+reStructuredText_ documents.
 
 ``text-mode`` Settings
 ----------------------
@@ -536,7 +582,6 @@ functions and modes that pertain somewhat to text-mode:
 - auto-mode-alist
 - fill-region
 
-
 Editing Tables: Emacs table mode
 --------------------------------
 
@@ -609,45 +654,25 @@ and ".,:;"), and free.
 __ http://www.tobias-jung.de/seekingprofont/
 
 
+
 Credits
 =======
 
 - The automatic section adjustment and table of contents features were
   written by Martin Blais;
-- ``rst-mode`` and its syntax highlighting was implemented by Stefan
-  Merten;
+- Syntax highlighting was implemented by Stefan Merten;
 - Various other functions were implemented by David Goodger.
 
-
 Obsolete Files
-==============
-
-On 2005-10-30, ``restructuredtext.el``, ``rst-html.el`` and
-``rst-mode.el`` were merged to form the new ``rst.el``.  You can
-consider the old files obsolete and remove them.
-
-
-Future Work
-===========
-
-Here are some features and ideas that will be worked on in the future,
-in those frenzied mornings of excitement over the virtues of the
-one-true-way kitchen sink of editors:
+--------------
 
-- It would be nice to differentiate between text files using
-  reStructuredText_ and other general text files.  If we had a
-  function to automatically guess whether a .txt file is following the
-  reStructuredText_ conventions, we could trigger rst-mode without
-  having to hard-code this in every text file, nor forcing the user to
-  add a local mode variable at the top of the file.
+On 2005-10-30, ``rst.el`` integrated and replaced the contents of the
+following files:
 
-  We could perform this guessing by searching for a valid decoration
-  at the top of the document or searching for reStructuredText_
-  directives further on.
+- ``restructuredtext.el``
+- ``rst-html.el``
+- ``rst-mode.el`` 
 
-- The suggested decorations when adjusting should not have to cycle
-  below one below the last section decoration level preceding the
-  cursor.  We need to fix that.
 
 
 .. _Emacs: http://www.gnu.org/software/emacs/emacs.html
@@ -656,7 +681,7 @@ one-true-way kitchen sink of editors:
 
 ..
    Local Variables:
-   mode: indented-text
+   mode: rst
    indent-tabs-mode: nil
    sentence-end-double-space: t
    fill-column: 70