- Changed the default bindings due to the explosion of new

  feature: we now have a prefix-map, which is bound to 'C-c p',
  so the 'C-x p XXXX' commands are all for the rst.el file
  functions.  I left a few bindings:

  * C-= is still there, because it is the single most useful
    command and it should be invoked with one key (you can get to
    it with 'C-c p a' too).

  * I moved 'C-M-{' to 'C-c n' or 'C-c p n' and did the same for
    the forward movement commands.

  * 'C-c C-l' and 'C-c C-r' have been kept, since they have a
    similar role than those bindings have in progmodes.

- I removed all the bindings from 'C-x ...' prefix map, since we
  should be using the mode-specific map, which is 'C-c ...'.  I'm
  also now using the mode-prefix-map variable, so people who have
  rebound theirs will get the benefits of their customization.

- Started defining some abbrevs, e.g. 'con' for ''.. contents::'

- Changed a lot of 'if's to 'when' and 'unless' clauses.

- I added a function to find the node within the section subtree
  where the cursor lives. This function is used to compute the
  desired location of point in the toc table, which fixes a bug
  with the cursor being off when there were missing nodes.

- The toc insertion now uses the insertion point to determine
  where to start rendering the TOC.  This fixes a problem with
  guessing the titles and subtitles and heuristically removing
  them, simplifies the rst-toc-insert function and this new
  choices automatically supports local tocs.

- Fixed the shifting functions to use markers, so that they can
  be used repeatedly with my repeat-repeatable-command advice.
  This just makes the functions more robust.

- Added an option to automatically fill on shifting a region left
  or right (this needs more work).




git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4004 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

1 files changed, 25 insertions, 16 deletions

diff --git a/docs/user/emacs.txt b/docs/user/emacs.txt
index 64daf07ac..219e8e250 100644
--- a/docs/user/emacs.txt
+++ b/docs/user/emacs.txt
@@ -67,6 +67,9 @@ this use, set it up like this::
 
   (add-hook 'text-mode-hook 'rst-text-mode-bindings)
 
+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 ...``.
+
 
 Section Decoration Adjustment
 =============================
@@ -76,9 +79,10 @@ 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.
 
-There is a function that helps a great deal to maintain these decorations:
-``rst-adjust`` (bound on ``C-=`` by default).  This function is a Swiss army 
-knife that can be invoked repeatedly and whose behaviour depends on context:
+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:
 
 #. If there is an incomplete underline, e.g.::
 
@@ -127,7 +131,7 @@ 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-u C-x C-=``.  A
+by invoking ``rst-display-decorations-hierarchy``, bound on ``C-c p 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.
@@ -142,7 +146,7 @@ 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-x C-=``.  It should present a
+Invoke this function (``rst-toc``) with ``C-c p t``.  It should present a
 temporary buffer that looks something like this::
 
   Table of Contents: 
@@ -199,16 +203,18 @@ that it is ignored by the parser.  This is the favoured usage::
         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-x +``.  If there is a single top-level section
-level (i.e. the document title), by default it is ignored.  If you have deep
-nesting of sections, you can use a numeric prefix argument to limit the depth of
-rendering of the TOC.
+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-always-include-top``, ``rst-toc-insert-style``,
-``rst-toc-insert-max-level``.
+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
@@ -223,13 +229,16 @@ 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-M-{`` and ``C-M-}`` keys.
+``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 Bulleted List Levels