I have cleaned up all the emacs support code for restructured text.

If you are using it, this will most certainly affect you, here are
the list of changes:

1. I moved the contents of restructuredtext.el, rst-mode.el and
   rst-html.el into a single file, named rst.el, and removed the old
   files.  You can remove the old files from your load-path and
   replace them with rst.el, the old files are to be considered
   OBSOLETE from now (2005-10-30).  All new contents will go to
   rst.el.

2. All the rest-* function names from restructuredtext.el have been
   RENAMED to rst-* (to be consistent with the code that was in
   rst-mode.el).  Almost all the contents of rst.el now start with
   rst-.

3. rst-text-mode-hook has been renamed to rst-text-mode-bindings.
   Because it is not a hook, but rather a function to be bound to a
   hook.  This was confusing and is now following the general emacs
   conventions.  This will affect you if you were enabling the
   adjusting and toc functions.

4. I removed the rst-html-stylesheet and the simpler rst-html-compile
   function.  It was replaced by the implementation of
   rst-html-html-comple-with-conf, which is more generic, and which
   now also uses the rst-html-options.

In addition, I wrote a document that describes how to use all the
features included in rst.el, because many emacs users I meet are not
aware of them.  You will be able to find it under
docs/user/emacs.txt.  I linked to it from the index page.



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

1 files changed, 475 insertions, 0 deletions

diff --git a/docs/user/emacs.txt b/docs/user/emacs.txt
new file mode 100644
index 000000000..347ee6b19
--- /dev/null
+++ b/docs/user/emacs.txt
@@ -0,0 +1,475 @@
+========================================
+   Emacs Support for reStructuredText
+========================================
+
+:Author: Martin Blais <blais@furius.ca>
+:Date: 2005-10-29
+:Abstract:
+
+    High-level description of the existing emacs support for editing
+    reStructuredText text documents.  Suggested setup code and usage
+    instructions are provided.
+
+.. contents::
+..
+    1   Introduction
+    2   Basic Setup
+    3   Section Decoration Adjustment
+      3.1  Promoting and Demoting Many Sections
+      3.2  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 Bulleted List Levels
+    8   Major Mode for Editing reStructuredText Documents
+    9   Converting Documents from Emacs
+    10  Other / External Useful Emacs Settings
+      10.1  Settings for Filling Bulleted Lists
+      10.2  ``text-mode`` Settings
+      10.3  Editing Tables: Emacs table mode
+      10.4  Character Processing
+    11  Credits
+    12  Obsolete Files
+    13  Future Work
+
+
+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``.
+
+This document describes the most important features that it provides, how to
+setup your emacs to use them and how to invoke them.
+
+
+Basic Setup
+===========
+
+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)  ;; or (load "rst")
+
+Additional configuration variables can be customized and can be found by
+browsing the source code for ``rst.el``.
+
+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::
+
+  (add-hook 'text-mode-hook 'rst-text-mode-hook)
+
+
+Section Decoration Adjustment
+=============================
+
+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.
+
+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 knife
+that can be invoked repeatedly and whose behaviour depends on context:
+
+#. If there is an incomplete underline, 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.
+
+#. If there is no section decoration, a decoration one level under the last
+   encountered section level is added;
+
+#. 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.
+
+Invoking the function with a negative prefix argument, e.g. ``C-- C-=``, will
+effectively reverse the direction of decoration 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 documentation of ``rst-adjust`` for more description
+of the prefix arguments to alter the behaviour 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 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).
+
+
+Customizations
+--------------
+
+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 characters 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-u C-x C-=``.  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
+=================
+
+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 ``Ret`` to go to a specific section.
+
+Invoke this function (``rst-toc``) with ``C-x C-=``.  It should present a
+temporary buffer that looks somewhat 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.
+
+
+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 gets computed automatically by
+docutils, you should place such a table of contents within a contents, so that
+it gets ignored by docutils, e.g.  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-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
+rendenring 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``.
+
+
+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 everytime 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)
+
+
+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.
+
+
+Shifting Bulleted List Levels
+=============================
+
+Due to the nature of reStructuredText_, bulleted lists are always indented by
+two characters (unless they are part of a blockquote), e.g. ::
+
+   - Fruits
+
+     - Bananas
+     - Apples
+     - Oranges
+
+   - Veggies
+
+     - Zucchini
+     - Chick Peas
+
+To this effect, when re-organizing bulleted lists, it can be useful to shift
+regions of text by indents of two characters.  You can use the ``C-c C-r`` and
+``C-c C-l`` to shift the current region.  These bindings are similar to the ones
+provided by python-mode for editing python code and behave similarly.
+
+
+Major Mode for Editing reStructuredText Documents
+=================================================
+
+There is a major mode available for editing and syntax highlighting
+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 setup an
+``auto-mode-alist`` to automatically turn it on whenever you visit
+reStructuredText_ documents::
+
+   (add-to-list 'auto-mode-alist '("\\.rst$" . rst-mode) )
+
+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 -*-
+
+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).
+
+.. [#]  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
+===============================
+
+At the moment there is minimal support for calling ``rst2html.py`` from within
+Emacs.  You can add a key binding like this to invoke it::
+
+  (local-set-key [(control c)(?9)] 'rst-html-compile)
+
+This function basically creates a compilation command with the correct HTML
+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.
+
+.. 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.
+
+
+Other / External Useful Emacs 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.
+
+
+Settings for Filling Bulleted Lists
+-----------------------------------
+
+One problem with the default text-mode settings is that *filling* long lines in
+bulleted lists that do not have an empty line between them merges them together,
+e.g.::
+
+     - Bananas;
+     - One Apple a day keeps the doctor away, and eating more keeps the pirates at bay;
+     - Oranges;
+
+Becomes::
+
+     - Bananas; One Apple a day keeps the doctor away, and
+     - eating more keeps the pirates at bay; Oranges;
+
+This is usually not what you want. What you want is this::
+
+     - Bananas;
+     - One Apple a day keeps the doctor away, and eating more
+       keeps the pirates at bay;
+     - Oranges;
+
+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, like this::
+
+   (setq paragraph-start (concat paragraph-start "\\|[ \t]*[-*] "))
+
+
+``text-mode`` Settings
+----------------------
+
+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:
+
+- indent-tabs-mode
+- colon-double-space
+- auto-fill-mode
+- auto-mode-alist
+- fill-region
+
+
+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 reStructuredText_.
+
+.. _Emacs table mode: http://table.sourceforge.net/
+
+
+
+Character Processing
+--------------------
+
+Since reStructuredText punts on the issue of character processing,
+here are some useful resources for Emacs users in the Unicode world:
+
+* `xmlunicode.el and unichars.el from Norman Walsh
+  <http://nwalsh.com/emacs/xmlchars/index.html>`__
+
+* `An essay by Tim Bray, with example code
+  <http://www.tbray.org/ongoing/When/200x/2003/09/27/UniEmacs>`__
+
+* 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
+    "option-e e" resulting in "é" [eacute]), first enable the option
+    key by setting the command key as your meta key::
+
+        (setq mac-command-key-is-meta t) ;; nil for option key
+
+    Next, use one of these lines::
+
+        (set-keyboard-coding-system 'mac-roman)
+        (setq mac-keyboard-text-encoding kTextEncodingISOLatin1)
+
+    I prefer the first line, because it enables non-Latin-1 characters
+    as well (em-dash, curly quotes, etc.).
+
+  - 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::
+
+      (create-fontset-from-fontset-spec
+       "-apple-monaco-medium-r-normal--10-*-*-*-*-*-fontset-monaco,
+        ascii:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman,
+        latin-iso8859-1:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman,
+        mule-unicode-0100-24ff:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman")
+
+    Latin-1 doesn't cover characters like em-dash and curly quotes, so
+    "mule-unicode-0100-24ff" is needed.
+
+    Next, use that fontset::
+
+        (set-frame-font "fontset-monaco")
+
+  - To enable cooperation between the system clipboard and the Emacs
+    kill ring, add this line::
+
+        (set-clipboard-coding-system 'mac-roman)
+
+  Other useful resources are in `Andrew Choi's Emacs 21 for Mac OS X
+  FAQ <http://members.shaw.ca/akochoi-emacs/stories/faq.html>`__.
+
+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.
+
+__ 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;
+- 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
+frenzy morning 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 hardcode this on every text file, nor
+  forcing the user to add a local mode variable at the top of the file.  
+
+  We could perform this guessing by searching for a valid decoration at the top
+  of the document or searching for reStructuredText_ directives further on.
+
+- We would like to support local table of contents insertion.
+
+- 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/emacs FIXME check
+.. _reStructuredText: http://docutils.sf.net/rst.html