Menu
▾
▴
[Docutils-checkins] r3981 - in trunk/docutils: docs/index.txt docs/user/emacs.txt tools/editors/emacs/README.txt tools/editors/emacs/restructuredtext.el tools/editors/emacs/rst-html.el tools/editors/emacs/rst-mode.el tools/editors/emacs/rst.el tools/editors/emacs/tests/tests-adjust-section.el tools/editors/emacs/tests/tests-basic.el
|
From: <bl...@us...> - 2005-10-30 15:13:56
|
Author: blais
Date: 2005-10-30 16:13:46 +0100 (Sun, 30 Oct 2005)
New Revision: 3981
Added:
trunk/docutils/docs/user/emacs.txt
trunk/docutils/tools/editors/emacs/rst.el
Removed:
trunk/docutils/tools/editors/emacs/restructuredtext.el
trunk/docutils/tools/editors/emacs/rst-html.el
trunk/docutils/tools/editors/emacs/rst-mode.el
Modified:
trunk/docutils/docs/index.txt
trunk/docutils/tools/editors/emacs/README.txt
trunk/docutils/tools/editors/emacs/tests/tests-adjust-section.el
trunk/docutils/tools/editors/emacs/tests/tests-basic.el
Log:
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.
Modified: trunk/docutils/docs/index.txt
===================================================================
--- trunk/docutils/docs/index.txt 2005-10-30 14:32:45 UTC (rev 3980)
+++ trunk/docutils/docs/index.txt 2005-10-30 15:13:46 UTC (rev 3981)
@@ -95,7 +95,11 @@
demonstration of most reStructuredText features; you can also have a
look at the `text source <user/rst/demo.txt>`__)
+Editor support:
+* `Emacs support for reStructuredText <user/emacs.html>`_
+
+
.. _ref:
``ref/``: Reference Material for All Groups
Added: trunk/docutils/docs/user/emacs.txt
===================================================================
--- trunk/docutils/docs/user/emacs.txt 2005-10-30 14:32:45 UTC (rev 3980)
+++ trunk/docutils/docs/user/emacs.txt 2005-10-30 15:13:46 UTC (rev 3981)
@@ -0,0 +1,475 @@
+========================================
+ Emacs Support for reStructuredText
+========================================
+
+:Author: Martin Blais <bl...@fu...>
+: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
Property changes on: trunk/docutils/docs/user/emacs.txt
___________________________________________________________________
Name: svn:keywords
+ Author Date Id Revision
Name: svn:eol-style
+ native
Modified: trunk/docutils/tools/editors/emacs/README.txt
===================================================================
--- trunk/docutils/tools/editors/emacs/README.txt 2005-10-30 14:32:45 UTC (rev 3980)
+++ trunk/docutils/tools/editors/emacs/README.txt 2005-10-30 15:13:46 UTC (rev 3981)
@@ -12,85 +12,18 @@
This directory contains the following Emacs lisp package files:
-* restructuredtext.el by Martin Blais and David Goodger
+* rst.el : Emacs support for ReStructuredText. This file contains
- Support code for editing reStructuredText with Emacs indented-text
- mode.
+ * Section decoration/adornment creation and updating (M. Blais);
+ * Table-of-contents mode and insertion (M. Blais);
+ * Font-lock syntax highlighting (S. Merten);
+ * Some handy editing functions (D. Goodger).
+ * Some functions for converting documents from emacs (M. Blais).
-* rst-mode.el by Stefan Merten
+* tests subdirectory: automated tests for some of the features in rst.el.
+ Please make sure the tests pass if you change the LISP code. Just type "make"
+ to run the tests.
- Provides support for documents marked up using the reStructuredText
- format, including font locking as well as some convenience functions
- for editing.
+To install the package, put a copy of the package file in a directory on your
+``load-path`` (use ``C-h v load-path`` to check).
-* rst-html.el by Martin Blais
-
- Provides a few functions and variables that can help in automating
- the conversion of reST documents to HTML from within Emacs.
-
-Each file includes specific usage instructions. To install a package,
-put a copy of the package file in a directory on your ``load-path``
-(use ``C-h v load-path`` to check).
-
-
-Character Processing Notes
-==========================
-
-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/
-.. _reStructuredText: http://docutils.sf.net/rst.html
Deleted: trunk/docutils/tools/editors/emacs/restructuredtext.el
Deleted: trunk/docutils/tools/editors/emacs/rst-html.el
Deleted: trunk/docutils/tools/editors/emacs/rst-mode.el
Copied: trunk/docutils/tools/editors/emacs/rst.el (from rev 3978, trunk/docutils/tools/editors/emacs/restructuredtext.el)
===================================================================
--- trunk/docutils/tools/editors/emacs/restructuredtext.el 2005-10-29 21:17:26 UTC (rev 3978)
+++ trunk/docutils/tools/editors/emacs/rst.el 2005-10-30 15:13:46 UTC (rev 3981)
@@ -0,0 +1,2479 @@
+;; Authors: Martin Blais <bl...@fu...>,
+;; Stefan Merten <sm...@oe...>
+;; David Goodger <go...@py...>
+;; Date: $Date$
+;; Copyright: This module has been placed in the public domain.
+;;
+;; Support code for editing reStructuredText with Emacs. Basically, this
+;; package contains:
+;;
+;; - Functions to automatically adjust and cycle the section underline
+;; decorations;
+;; - A mode that displays the table of contents and allows you to jump anywhere
+;; from it;
+;; - Functions to insert and automatically update a TOC in your source document;
+;; - A mode which supports font-lock highlighting of reStructuredText
+;; structures;
+;; - Some other convenience functions.
+;;
+;; See the accompanying document in the docutils documentation about
+;; the contents of this package and how to use it.
+;;
+;; For more information about reStructuredText, see
+;; http://docutils.sourceforge.net/rst.html
+;;
+;; **IMPORTANT NOTE TO PACKAGERS**: this package is the result of merging:
+;;
+;; - restructuredtext.el
+;; - rst-mode.el
+;; - rst-html.el
+;;
+;; Those files are now OBSOLETE and have been replaced by this single package
+;; file (2005-10-30).
+;;
+;; Installation instructions
+;; -------------------------
+;;
+;; Add this line to your .emacs file and bind the versatile sectioning commands
+;; in text mode, like this::
+;;
+;; (require 'rst)
+;; (add-hook 'text-mode-hook 'rst-text-mode-bindings)
+;;
+;; The keys it defines are:
+;;
+;; C-= : updates or rotates the section title around point or
+;; promotes/demotes the decorations within the region (see full details
+;; below).
+;;
+;; Note that C-= is a good binding, since it allows you to specify a
+;; negative arg easily with C-- C-= (easy to type), as well as ordinary
+;; prefix arg with C-u C-=.
+;;
+;; C-x C-= : displays the hierarchical table-of-contents of the document and
+;; allows you to jump to any section from it.
+;;
+;; C-u C-x C-= : displays the title decorations from this file.
+;;
+;; C-x + : insert the table of contents in the text. See the many options
+;; for customizing how it will look.
+;;
+;; C-M-{, C-M-} : navigate between section titles.
+;;
+;; Other specialized and more generic functions are also available (see source
+;; code). The most important function provided by this file for section title
+;; adjustments is rst-adjust.
+;;
+;; There are many variables that can be customized, look for defcustom and
+;; defvar in this file.
+;;
+;; If you use the table-of-contents feature, you may want to add a hook to
+;; update the TOC automatically everytime you adjust a section title::
+;;
+;; (add-hook 'rst-adjust-hook 'rst-toc-insert-update)
+;;
+;; rst-mode
+;; --------
+;;
+;; There is a special mode that you can setup if you want to have syntax
+;; highlighting. The mode is based on `text-mode' and inherits some things from
+;; it. Particularly `text-mode-hook' is run before `rst-mode-hook'.
+;;
+;; Add the following lines to your `.emacs' file:
+;;
+;; (setq auto-mode-alist
+;; (append '(("\\.rst$" . rst-mode)
+;; ("\\.rest$" . rst-mode)) auto-mode-alist))
+;;
+;; If you are using `.txt' as a standard extension for reST files as
+;; http://docutils.sourceforge.net/FAQ.html#what-s-the-standard-filename-extension-for-a-restructuredtext-file
+;; suggests you may use one of the `Local Variables in Files' mechanism Emacs
+;; provides to set the major mode automatically. For instance you may use
+;;
+;; .. -*- mode: rst -*-
+;;
+;; in the very first line of your file. However, because this is a major
+;; security breach you or your administrator may have chosen to switch that
+;; feature off. See `Local Variables in Files' in the Emacs documentation for a
+;; more complete discussion.
+;;
+;;
+;; TODO list
+;; =========
+;;
+;; Bindings
+;; --------
+;; - We need to automatically add the rst-text-mode-bindings to rst-mode
+;; - We need to find better bindings because C-= does not generate an event on
+;; the Macs.
+;;
+;; rst-toc-insert features
+;; ------------------------
+;; - Support local table of contents, like in doctree.txt.
+;; - On load, detect any existing TOCs and set the properties for links.
+;; - TOC insertion should have an option to add empty lines.
+;; - TOC insertion should deal with multiple lines
+;;
+;; - There is a bug on redo after undo of adjust when rst-adjust-hook uses the
+;; automatic toc update. The cursor ends up in the TOC and this is
+;; annoying. Gotta fix that.
+;;
+;; Other
+;; -----
+;; - Add an option to forego using the file structure in order to make
+;; suggestion, and to always use the preferred decorations to do that.
+;;
+
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Bindings and hooks
+
+(defgroup rst nil "Support for reStructuredText documents"
+ :group 'wp
+ :version "21.1"
+ :link '(url-link "http://docutils.sourceforge.net/rst.html"))
+
+(defun rst-toc-or-hierarchy ()
+ "Binding for either TOC or decorations hierarchy."
+ (interactive)
+ (if (not current-prefix-arg)
+ (rst-toc)
+ (rst-display-decorations-hierarchy)))
+
+(defun rst-text-mode-bindings ()
+ "Default text mode hook for rest."
+ (local-set-key [(control ?=)] 'rst-adjust)
+ (local-set-key [(control x)(control ?=)] 'rst-toc-or-hierarchy)
+ (local-set-key [(control x)(?+)] 'rst-toc-insert)
+ (local-set-key [(control meta ?{)] 'rst-backward-section)
+ (local-set-key [(control meta ?})] 'rst-forward-section)
+ (local-set-key [(control c)(control r)] 'rst-shift-region-right)
+ (local-set-key [(control c)(control l)] 'rst-shift-region-left)
+ )
+
+;; Note: we cannot bind the TOC update on file write because it messes with
+;; undo. If we disable undo, since it adds and removes characters, the
+;; positions in the undo list are not making sense anymore. Dunno what to do
+;; with this, it would be nice to update when saving.
+;;
+;; (add-hook 'write-contents-hooks 'rst-toc-insert-update-fun)
+;; (defun rst-toc-insert-update-fun ()
+;; ;; Disable undo for the write file hook.
+;; (let ((buffer-undo-list t)) (rst-toc-insert-update) ))
+
+
+
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Support functions
+
+(require 'cl)
+
+;; Generic Filter function.
+(if (not (fboundp 'filter))
+ (defun filter (pred list)
+ "Returns a list of all the elements fulfilling the pred requirement (that
+is for which (pred elem) is true)"
+ (if list
+ (let ((head (car list))
+ (tail (filter pred (cdr list))))
+ (if (funcall pred head)
+ (cons head tail)
+ tail)))))
+
+
+;; From emacs-22
+(if (not (fboundp 'line-number-at-pos))
+ (defun line-number-at-pos (&optional pos)
+ "Return (narrowed) buffer line number at position POS.
+ If POS is nil, use current buffer location."
+ (let ((opoint (or pos (point))) start)
+ (save-excursion
+ (goto-char (point-min))
+ (setq start (point))
+ (goto-char opoint)
+ (forward-line 0)
+ (1+ (count-lines start (point)))))) )
+
+
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Section Decoration Adjusment
+;; ============================
+;;
+;; The following functions implement a smart automatic title sectioning feature.
+;; The idea is that with the cursor sitting on a section title, we try to get as
+;; much information from context and try to do the best thing automatically.
+;; This function can be invoked many times and/or with prefix argument to rotate
+;; between the various sectioning decorations.
+;;
+;; Definitions: the two forms of sectioning define semantically separate section
+;; levels. A sectioning DECORATION consists in:
+;;
+;; - a CHARACTER
+;;
+;; - a STYLE which can be either of 'simple' or 'over-and-under'.
+;;
+;; - an INDENT (meaningful for the over-and-under style only) which determines
+;; how many characters and over-and-under style is hanging outside of the
+;; title at the beginning and ending.
+;;
+;; Important note: an existing decoration must be formed by at least two
+;; characters to be recognized.
+;;
+;; Here are two examples of decorations (| represents the window border, column
+;; 0):
+;;
+;; |
+;; 1. char: '-' e |Some Title
+;; style: simple |----------
+;; |
+;; 2. char: '=' |==============
+;; style: over-and-under | Some Title
+;; indent: 2 |==============
+;; |
+;;
+;; Some notes:
+;;
+;; - The underlining character that is used depends on context. The file is
+;; scanned to find other sections and an appropriate character is selected.
+;; If the function is invoked on a section that is complete, the character is
+;; rotated among the existing section decorations.
+;;
+;; Note that when rotating the characters, if we come to the end of the
+;; hierarchy of decorations, the variable rst-preferred-decorations is
+;; consulted to propose a new underline decoration, and if continued, we cycle
+;; the decorations all over again. Set this variable to nil if you want to
+;; limit the underlining character propositions to the existing decorations in
+;; the file.
+;;
+;; - A prefix argument can be used to alternate the style.
+;;
+;; - An underline/overline that is not extended to the column at which it should
+;; be hanging is dubbed INCOMPLETE. For example::
+;;
+;; |Some Title
+;; |-------
+;;
+;; Examples of default invocation:
+;;
+;; |Some Title ---> |Some Title
+;; | |----------
+;;
+;; |Some Title ---> |Some Title
+;; |----- |----------
+;;
+;; | |------------
+;; | Some Title ---> | Some Title
+;; | |------------
+;;
+;; In over-and-under style, when alternating the style, a variable is
+;; available to select how much default indent to use (it can be zero). Note
+;; that if the current section decoration already has an indent, we don't
+;; adjust it to the default, we rather use the current indent that is already
+;; there for adjustment (unless we cycle, in which case we use the indent
+;; that has been found previously).
+
+(defgroup rst-adjust nil
+ "Settings for adjustment and cycling of section title
+decorations."
+ :group 'rst
+ :version "21.1")
+
+(defcustom rst-preferred-decorations '( (?= over-and-under 1)
+ (?= simple 0)
+ (?- simple 0)
+ (?~ simple 0)
+ (?+ simple 0)
+ (?` simple 0)
+ (?# simple 0)
+ (?@ simple 0) )
+ "Preferred ordering of section title decorations. This
+ sequence is consulted to offer a new decoration suggestion when
+ we rotate the underlines at the end of the existing hierarchy
+ of characters, or when there is no existing section title in
+ the file."
+ :group 'rst-adjust)
+
+
+(defcustom rst-default-indent 1
+ "Number of characters to indent the section title when toggling
+ decoration styles. This is used when switching from a simple
+ decoration style to a over-and-under decoration style."
+ :group 'rst-adjust)
+
+
+(defvar rst-section-text-regexp "^[ \t]*\\S-*[a-zA-Z0-9]\\S-*"
+ "Regular expression for valid section title text.")
+
+
+(defun rst-line-homogeneous-p (&optional accept-special)
+ "Predicate return the unique char if the current line is
+ composed only of a single repeated non-whitespace
+ character. This returns the char even if there is whitespace at
+ the beginning of the line.
+
+ If ACCEPT-SPECIAL is specified we do not ignore special sequences
+ which normally we would ignore when doing a search on many lines.
+ For example, normally we have cases to ignore commonly occuring
+ patterns, such as :: or ...; with the flag do not ignore them."
+ (save-excursion
+ (back-to-indentation)
+ (if (not (looking-at "\n"))
+ (let ((c (thing-at-point 'char)))
+ (if (and (looking-at (format "[%s]+[ \t]*$" c))
+ (or accept-special
+ (and
+ ;; Common patterns.
+ (not (looking-at "::[ \t]*$"))
+ (not (looking-at "\\.\\.\\.[ \t]*$"))
+ ;; Discard one char line
+ (not (looking-at ".[ \t]*$"))
+ )))
+ (string-to-char c))
+ ))
+ ))
+
+(defun rst-line-homogeneous-nodent-p (&optional accept-special)
+ (save-excursion
+ (beginning-of-line)
+ (if (looking-at "^[ \t]+")
+ nil
+ (rst-line-homogeneous-p accept-special)
+ )))
+
+
+(defun rst-compare-decorations (deco1 deco2)
+ "Compare decorations. Returns true if both are equal,
+according to restructured text semantics (only the character and
+the style are compared, the indentation does not matter."
+ (and (eq (car deco1) (car deco2))
+ (eq (cadr deco1) (cadr deco2))))
+
+
+(defun rst-get-decoration-match (hier deco)
+ "Returns the index (level) of the decoration in the given hierarchy.
+This basically just searches for the item using the appropriate
+comparison and returns the index. We return nil if the item is
+not found."
+ (let ((cur hier))
+ (while (and cur (not (rst-compare-decorations (car cur) deco)))
+ (setq cur (cdr cur)))
+ cur))
+
+
+(defun rst-suggest-new-decoration (alldecos &optional prev)
+ "Suggest a new, different decoration, different from all that
+have been seen.
+
+ ALLDECOS is the set of all decorations, including the line
+ numbers. PREV is the optional previous decoration, in order to
+ suggest a better match."
+
+ ;; For all the preferred decorations...
+ (let* (
+ ;; If 'prev' is given, reorder the list to start searching after the
+ ;; match.
+ (fplist
+ (cdr (rst-get-decoration-match rst-preferred-decorations prev)))
+
+ ;; List of candidates to search.
+ (curpotential (append fplist rst-preferred-decorations)))
+ (while
+ ;; For all the decorations...
+ (let ((cur alldecos)
+ found)
+ (while (and cur (not found))
+ (if (rst-compare-decorations (car cur) (car curpotential))
+ ;; Found it!
+ (setq found (car curpotential))
+ (setq cur (cdr cur))))
+ found)
+
+ (setq curpotential (cdr curpotential)))
+
+ (copy-list (car curpotential)) ))
+
+(defun rst-delete-line ()
+ "A version of kill-line that does not use the kill-ring."
+ (delete-region (line-beginning-position) (+ 1 (line-end-position))))
+
+(defun rst-update-section (char style &optional indent)
+ "Unconditionally updates the style of a section decoration
+ using the given character CHAR, with STYLE 'simple or
+ 'over-and-under, and with indent INDENT. If the STYLE is
+ 'simple, whitespace before the title is removed (indent is
+ always assume to be 0).
+
+ If there are existing overline and/or underline from the
+ existing decoration, they are removed before adding the
+ requested decoration."
+
+ (interactive)
+ (let (marker
+ len
+ ec
+ (c ?-))
+
+ (end-of-line)
+ (setq marker (point-marker))
+
+ ;; Fixup whitespace at the beginning and end of the line
+ (if (or (null indent) (eq style 'simple))
+ (setq indent 0))
+ (beginning-of-line)
+ (delete-horizontal-space)
+ (insert (make-string indent ? ))
+
+ (end-of-line)
+ (delete-horizontal-space)
+
+ ;; Set the current column, we're at the end of the title line
+ (setq len (+ (current-column) indent))
+
+ ;; Remove previous line if it consists only of a single repeated character
+ (save-excursion
+ (forward-line -1)
+ (and (rst-line-homogeneous-p 1)
+ ;; Avoid removing the underline of a title right above us.
+ (save-excursion (forward-line -1)
+ (not (looking-at rst-section-text-regexp)))
+ (rst-delete-line)))
+
+ ;; Remove following line if it consists only of a single repeated
+ ;; character
+ (save-excursion
+ (forward-line +1)
+ (and (rst-line-homogeneous-p 1)
+ (rst-delete-line))
+ ;; Add a newline if we're at the end of the buffer, for the subsequence
+ ;; inserting of the underline
+ (if (= (point) (buffer-end 1))
+ (newline 1)))
+
+ ;; Insert overline
+ (if (eq style 'over-and-under)
+ (save-excursion
+ (beginning-of-line)
+ (open-line 1)
+ (insert (make-string len char))))
+
+ ;; Insert underline
+ (forward-line +1)
+ (open-line 1)
+ (insert (make-string len char))
+
+ (forward-line +1)
+ (goto-char marker)
+ ))
+
+
+(defun rst-normalize-cursor-position ()
+ "If the cursor is on a decoration line or an empty line , place
+ it on the section title line (at the end). Returns the line
+ offset by which the cursor was moved. This works both over or
+ under a line."
+ (if (save-excursion (beginning-of-line)
+ (or (rst-line-homogeneous-p 1)
+ (looking-at "^[ \t]*$")))
+ (progn
+ (beginning-of-line)
+ (cond
+ ((save-excursion (forward-line -1)
+ (beginning-of-line)
+ (and (looking-at rst-section-text-regexp)
+ (not (rst-line-homogeneous-p 1))))
+ (progn (forward-line -1) -1))
+ ((save-excursion (forward-line +1)
+ (beginning-of-line)
+ (and (looking-at rst-section-text-regexp)
+ (not (rst-line-homogeneous-p 1))))
+ (progn (forward-line +1) +1))
+ (t 0)))
+ 0 ))
+
+
+(defun rst-find-all-decorations ()
+ "Finds all the decorations in the file, and returns a list of
+ (line, decoration) pairs. Each decoration consists in a (char,
+ style, indent) triple.
+
+ This function does not detect the hierarchy of decorations, it
+ just finds all of them in a file. You can then invoke another
+ function to remove redundancies and inconsistencies."
+
+ (let (positions
+ (curline 1))
+ ;; Iterate over all the section titles/decorations in the file.
+ (save-excursion
+ (beginning-of-buffer)
+ (while (< (point) (buffer-end 1))
+ (if (rst-line-homogeneous-nodent-p)
+ (progn
+ (setq curline (+ curline (rst-normalize-cursor-position)))
+
+ ;; Here we have found a potential site for a decoration,
+ ;; characterize it.
+ (let ((deco (rst-get-decoration)))
+ (if (cadr deco) ;; Style is existing.
+ ;; Found a real decoration site.
+ (progn
+ (push (cons curline deco) positions)
+ ;; Push beyond the underline.
+ (forward-line 1)
+ (setq curline (+ curline 1))
+ )))
+ ))
+ (forward-line 1)
+ (setq curline (+ curline 1))
+ ))
+ (reverse positions)))
+
+
+(defun rst-infer-hierarchy (decorations)
+ "Build a hierarchy of decorations using the list of given decorations.
+
+ This function expects a list of (char, style, indent)
+ decoration specifications, in order that they appear in a file,
+ and will infer a hierarchy of section levels by removing
+ decorations that have already been seen in a forward traversal of the
+ decorations, comparing just the character and style.
+
+ Similarly returns a list of (char, style, indent), where each
+ list element should be unique."
+
+ (let ((hierarchy-alist (list)))
+ (dolist (x decorations)
+ (let ((char (car x))
+ (style (cadr x))
+ (indent (caddr x)))
+ (if (not (assoc (cons char style) hierarchy-alist))
+ (progn
+ (setq hierarchy-alist
+ (append hierarchy-alist
+ (list (cons (cons char style) x))))
+ ))
+ ))
+ (mapcar 'cdr hierarchy-alist)
+ ))
+
+
+(defun rst-get-hierarchy (&optional alldecos ignore)
+ "Returns a list of decorations that represents the hierarchy of
+ section titles in the file.
+
+ If the line number in IGNORE is specified, the decoration found
+ on that line (if there is one) is not taken into account when
+ building the hierarchy."
+ (let ((all (or alldecos (rst-find-all-decorations))))
+ (setq all (assq-delete-all ignore all))
+ (rst-infer-hierarchy (mapcar 'cdr all))))
+
+
+(defun rst-get-decoration (&optional point)
+ "Looks around point and finds the characteristics of the
+ decoration that is found there. We assume that the cursor is
+ already placed on the title line (and not on the overline or
+ underline).
+
+ This function returns a (char, style, indent) triple. If the
+ characters of overline and underline are different, we return
+ the underline character. The indent is always calculated. A
+ decoration can be said to exist if the style is not nil.
+
+ A point can be specified to go to the given location before
+ extracting the decoration."
+
+ (let (char style indent)
+ (save-excursion
+ (if point (goto-char point))
+ (beginning-of-line)
+ (if (looking-at rst-section-text-regexp)
+ (let* ((over (save-excursion
+ (forward-line -1)
+ (rst-line-homogeneous-nodent-p)))
+
+ (under (save-excursion
+ (forward-line +1)
+ (rst-line-homogeneous-nodent-p)))
+ )
+
+ ;; Check that the line above the overline is not part of a title
+ ;; above it.
+ (if (and over
+ (save-excursion
+ (and (equal (forward-line -2) 0)
+ (looking-at rst-section-text-regexp))))
+ (setq over nil))
+
+ (cond
+ ;; No decoration found, leave all return values nil.
+ ((and (eq over nil) (eq under nil)))
+
+ ;; Overline only, leave all return values nil.
+ ;;
+ ;; Note: we don't return the overline character, but it could perhaps
+ ;; in some cases be used to do something.
+ ((and over (eq under nil)))
+
+ ;; Underline only.
+ ((and under (eq over nil))
+ (setq char under
+ style 'simple))
+
+ ;; Both overline and underline.
+ (t
+ (setq char under
+ style 'over-and-under))
+ )
+ )
+ )
+ ;; Find indentation.
+ (setq indent (save-excursion (back-to-indentation) (current-column)))
+ )
+ ;; Return values.
+ (list char style indent)))
+
+
+(defun rst-get-decorations-around (&optional alldecos)
+ "Given the list of all decorations (with positions),
+find the decorations before and after the given point.
+A list of the previous and next decorations is returned."
+ (let* ((all (or alldecos (rst-find-all-decorations)))
+ (curline (line-number-at-pos))
+ prev next
+ (cur all))
+
+ ;; Search for the decorations around the current line.
+ (while (and cur (< (caar cur) curline))
+ (setq prev cur
+ cur (cdr cur)))
+ ;; 'cur' is the following decoration.
+
+ (if (and cur (caar cur))
+ (setq next (if (= curline (caar cur)) (cdr cur) cur)))
+
+ (mapcar 'cdar (list prev next))
+ ))
+
+
+(defun rst-decoration-complete-p (deco &optional point)
+ "Return true if the decoration DECO around POINT is complete."
+ ;; Note: we assume that the detection of the overline as being the underline
+ ;; of a preceding title has already been detected, and has been eliminated
+ ;; from the decoration that is given to us.
+
+ ;; There is some sectioning already present, so check if the current
+ ;; sectioning is complete and correct.
+ (let* ((char (car deco))
+ (style (cadr deco))
+ (indent (caddr deco))
+ (endcol (save-excursion (end-of-line) (current-column)))
+ )
+ (if char
+ (let ((exps (concat "^"
+ (regexp-quote (make-string (+ endcol indent) char))
+ "$")))
+ (and
+ (save-excursion (forward-line +1)
+ (beginning-of-line)
+ (looking-at exps))
+ (or (not (eq style 'over-and-under))
+ (save-excursion (forward-line -1)
+ (beginning-of-line)
+ (looking-at exps))))
+ ))
+ ))
+
+
+(defun rst-get-next-decoration
+ (curdeco hier &optional suggestion reverse-direction)
+ "Get the next decoration for CURDECO, in given hierarchy HIER,
+and suggesting for new decoration SUGGESTION."
+
+ (let* (
+ (char (car curdeco))
+ (style (cadr curdeco))
+
+ ;; Build a new list of decorations for the rotation.
+ (rotdecos
+ (append hier
+ ;; Suggest a new decoration.
+ (list suggestion
+ ;; If nothing to suggest, use first decoration.
+ (car hier)))) )
+ (or
+ ;; Search for next decoration.
+ (cadr
+ (let ((cur (if reverse-direction rotdecos
+ (reverse rotdecos)))
+ found)
+ (while (and cur
+ (not (and (eq char (caar cur))
+ (eq style (cadar cur)))))
+ (setq cur (cdr cur)))
+ cur))
+
+ ;; If not found, take the first of all decorations.
+ suggestion
+ )))
+
+
+(defun rst-adjust ()
+ "Adjust/rotate the section decoration for the section title
+around point or promote/demote the decorations inside the region,
+depending on if the region is active. This function is meant to
+be invoked possibly multiple times, and can vary its behaviour
+with a positive prefix argument (toggle style), or with a
+negative prefix argument (alternate behaviour).
+
+This function is the main focus of this module and is a bit of a
+swiss knife. It is meant as the single most essential function
+to be bound to invoke to adjust the decorations of a section
+title in restructuredtext. It tries to deal with all the
+possible cases gracefully and to do `the right thing' in all
+cases.
+
+See the documentations of rst-adjust-decoration and
+rst-promote-region for full details.
+
+Prefix Arguments
+================
+
+The method can take either (but not both) of
+
+a. a (non-negative) prefix argument, which means to toggle the
+ decoration style. Invoke with C-u prefix for example;
+
+b. a negative numerical argument, which generally inverts the
+ direction of search in the file or hierarchy. Invoke with C--
+ prefix for example.
+
+"
+ (interactive)
+
+ (let* ( ;; Parse the positive and negative prefix arguments.
+ (reverse-direction
+ (and current-prefix-arg
+ (< (prefix-numeric-value current-prefix-arg) 0)))
+ (toggle-style
+ (and current-prefix-arg (not reverse-direction))))
+
+ (if (and transient-mark-mode mark-active)
+ ;; Adjust decorations within region.
+ (rst-promote-region current-prefix-arg)
+ ;; Adjust decoration around point.
+ (rst-adjust-decoration toggle-style reverse-direction))
+
+ ;; Run the hooks to run after adjusting.
+ (run-hooks 'rst-adjust-hook)
+
+ ))
+
+(defvar rst-adjust-hook nil
+ "Hooks to be run after running rst-adjust.")
+
+(defun rst-adjust-decoration (&optional toggle-style reverse-direction)
+"Adjust/rotate the section decoration for the section title around point.
+
+This function is meant to be invoked possibly multiple times, and
+can vary its behaviour with a true TOGGLE-STYLE argument, or with
+a REVERSE-DIRECTION argument.
+
+General Behaviour
+=================
+
+The next action it takes depends on context around the point, and
+it is meant to be invoked possibly more than once to rotate among
+the various possibilities. Basically, this function deals with:
+
+- adding a decoration if the title does not have one;
+
+- adjusting the length of the underline characters to fit a
+ modified title;
+
+- rotating the decoration in the set of already existing
+ sectioning decorations used in the file;
+
+- switching between simple and over-and-under styles.
+
+You should normally not have to read all the following, just
+invoke the method and it will do the most obvious thing that you
+would expect.
+
+
+Decoration Definitions
+======================
+
+The decorations consist in
+
+1. a CHARACTER
+
+2. a STYLE which can be either of 'simple' or 'over-and-under'.
+
+3. an INDENT (meaningful for the over-and-under style only)
+ which determines how many characters and over-and-under
+ style is hanging outside of the title at the beginning and
+ ending.
+
+See source code for mode details.
+
+
+Detailed Behaviour Description
+==============================
+
+Here are the gory details of the algorithm (it seems quite
+complicated, but really, it does the most obvious thing in all
+the particular cases):
+
+Before applying the decoration change, the cursor is placed on
+the closest line that could contain a section title.
+
+Case 1: No Decoration
+---------------------
+
+If the current line has no decoration around it,
+
+- search backwards for the last previous decoration, and apply
+ the decoration one level lower to the current line. If there
+ is no defined level below this previous decoration, we suggest
+ the most appropriate of the rst-preferred-decorations.
+
+ If REVERSE-DIRECTION is true, we simply use the previous
+ decoration found directly.
+
+- if there is no decoration found in the given direction, we use
+ the first of rst-preferred-decorations.
+
+The prefix argument forces a toggle of the prescribed decoration
+style.
+
+Case 2: Incomplete Decoration
+-----------------------------
+
+If the current line does have an existing decoration, but the
+decoration is incomplete, that is, the underline/overline does
+not extend to exactly the end of the title line (it is either too
+short or too long), we simply extend the length of the
+underlines/overlines to fit exactly the section title.
+
+If the prefix argument is given, we toggle the style of the
+decoration as well.
+
+REVERSE-DIRECTION has no effect in this case.
+
+Case 3: Complete Existing Decoration
+------------------------------------
+
+If the decoration is complete (i.e. the underline (overline)
+length is already adjusted to the end of the title line), we
+search/parse the file to establish the hierarchy of all the
+decorations (making sure not to include the decoration around
+point), and we rotate the current title's decoration from within
+that list (by default, going *down* the hierarchy that is present
+in the file, i.e. to a lower section level). This is meant to be
+used potentially multiple times, until the desired decoration is
+found around the title.
+
+If we hit the boundary of the hierarchy, exactly one choice from
+the list of preferred decorations is suggested/chosen, the first
+of those decoration that has not been seen in the file yet (and
+not including the decoration around point), and the next
+invocation rolls over to the other end of the hierarchy (i.e. it
+cycles). This allows you to avoid having to set which character
+to use by always using the
+
+If REVERSE-DIRECTION is true, the effect is to change the
+direction of rotation in the hierarchy of decorations, thus
+instead going *up* the hierarchy.
+
+However, if there is a non-negative prefix argument, we do not
+rotate the decoration, but instead simply toggle the style of the
+current decoration (this should be the most common way to toggle
+the style of an existing complete decoration).
+
+
+Point Location
+==============
+
+The invocation of this function can be carried out anywhere
+within the section title line, on an existing underline or
+overline, as well as on an empty line following a section title.
+This is meant to be as convenient as possible.
+
+
+Indented Sections
+=================
+
+Indented section titles such as ::
+
+ My Title
+ --------
+
+are illegal in restructuredtext and thus not recognized by the
+parser. This code will thus not work in a way that would support
+indented sections (it would be ambiguous anyway).
+
+
+Joint Sections
+==============
+
+Section titles that are right next to each other may not be
+treated well. More work might be needed to support those, and
+special conditions on the completeness of existing decorations
+might be required to make it non-ambiguous.
+
+For now we assume that the decorations are disjoint, that is,
+there is at least a single line between the titles/decoration
+lines.
+
+
+Suggested Binding
+=================
+
+We suggest that you bind this function on C-=. It is close to
+C-- so a negative argument can be easily specified with a flick
+of the right hand fingers and the binding is unused in text-mode."
+ (interactive)
+
+ ;; If we were invoked directly, parse the prefix arguments into the
+ ;; arguments of the function.
+ (if current-prefix-arg
+ (setq reverse-direction
+ (and current-prefix-arg
+ (< (prefix-numeric-value current-prefix-arg) 0))
+
+ toggle-style
+ (and current-prefix-arg (not reverse-direction))))
+
+ (let* (;; Check if we're on an underline around a section title, and move the
+ ;; cursor to the title if this is the case.
+ (moved (rst-normalize-cursor-position))
+
+ ;; Find the decoration and completeness around point.
+ (curdeco (rst-get-decoration))
+ (char (car curdeco))
+ (style (cadr curdeco))
+ (indent (caddr curdeco))
+
+ ;; New values to be computed.
+ char-new style-new indent-new
+ )
+
+ ;; We've moved the cursor... if we're not looking at some text, we have
+ ;; nothing to do.
+ (if (save-excursion (beginning-of-line)
+ (looking-at rst-section-text-regexp))
+ (progn
+ (cond
+ ;;---------------------------------------------------------------------
+ ;; Case 1: No Decoration
+ ((and (eq char nil) (eq style nil))
+
+ (let* ((alldecos (rst-find-all-decorations))
+
+ (around (rst-get-decorations-around alldecos))
+ (prev (car around))
+ cur
+
+ (hier (rst-get-hierarchy alldecos))
+ )
+
+ ;; Advance one level down.
+ (setq cur
+ (if prev
+ (if (not reverse-direction)
+ (or (cadr (rst-get-decoration-match hier prev))
+ (rst-suggest-new-decoration hier prev))
+ prev)
+ (copy-list (car rst-preferred-decorations))
+ ))
+
+ ;; Invert the style if requested.
+ (if toggle-style
+ (setcar (cdr cur) (if (eq (cadr cur) 'simple)
+ 'over-and-under 'simple)) )
+
+ (setq char-new (car cur)
+ style-new (cadr cur)
+ indent-new (caddr cur))
+ ))
+
+ ;;---------------------------------------------------------------------
+ ;; Case 2: Incomplete Decoration
+ ((not (rst-decoration-complete-p curdeco))
+
+ ;; Invert the style if requested.
+ (if toggle-style
+ (setq style (if (eq style 'simple) 'over-and-under 'simple)))
+
+ (setq char-new c...
[truncated message content] |