Reformat documentation; add a local variables block for Emacs.

Remove overview.txt since it is redundant with user-guide.txt.

svn path=/trunk/; revision=671

4 files changed, 262 insertions, 304 deletions

diff --git a/doc/developer-guide.txt b/doc/developer-guide.txt
index b347b3e..76a8865 100644
--- a/doc/developer-guide.txt
+++ b/doc/developer-guide.txt
@@ -8,9 +8,10 @@ Introduction
 About eselect
 --------------
 
-eselect is a framework for simplifying and introducing consistency to the
-various Gentoo ``foo-config`` and ``update-blah`` tools. It is an option for
-developers who don't like reinventing the wheel, not a mandatory tool.
+eselect is a framework for simplifying and introducing consistency to
+the various Gentoo ``foo-config`` and ``update-blah`` tools. It is an
+option for developers who don't like reinventing the wheel, not a
+mandatory tool.
 
 Getting Started
 ===============
@@ -18,19 +19,19 @@ Getting Started
 Introduction
 ------------
 
-When porting your application to use the eselect framework, you will generally
-need to create a module. Often this can be heavily based upon an existing
-module, so check to see whether there is something that does almost what you
-need first (symlink handling is a good example of something that can be copied
-rather than reinvented).
+When porting your application to use the eselect framework, you will
+generally need to create a module. Often this can be heavily based upon
+an existing module, so check to see whether there is something that does
+almost what you need first (symlink handling is a good example of
+something that can be copied rather than reinvented).
 
 A Simple Module
 ---------------
 
 It's easiest to illustrate by example. Here's a simple module, named
-``cow.eselect``. It has two actions, ``moo`` and ``think``, plus the standard
-``help``, ``usage`` and ``version`` actions, and is installed to
-``$(datadir)/eselect/modules/`` ::
+``cow.eselect``. It has two actions, ``moo`` and ``think``, plus the
+standard ``help``, ``usage`` and ``version`` actions, and is installed
+to ``$(datadir)/eselect/modules/`` ::
 
 
     # Copyright 1999-2005 Gentoo Foundation
@@ -108,22 +109,25 @@ It's easiest to illustrate by example. Here's a simple module, named
         echo "${@:-Am I a cow?}" | cowthink ${params}
     }
 
-As you can see, the format is fairly similar to that of an ebuild -- it is a
-bash script which is run in a special environment. This is intentional. There
-are ``DESCRIPTION`` and ``VERSION`` variables globally which are used by
-``eselect`` and some of the default action handlers, and a series of functions.
-
-.. Warning:: In ebuilds, global scope code can cause problems. In eselect
-  modules, global scope code is **absolutely forbidden**. Your module *will* be
-  sourced for tasks other than running your actions. For example, if
-  ``eselect modules list`` is executed, your module will be sourced to obtain
-  the description. Any code being run here would be a very bad thing.
-
-Unlike ebuilds, the function names are not fixed. Any function whose name starts
-with ``do_`` is considered to be an action implementation. It is conventional to
-have a ``describe_`` function for every ``do_`` function that gives a short
-description of the function -- this is used for ``eselect modulename help``,
-for example. The ``describe_action_options`` and ``describe_action_parameters``
+As you can see, the format is fairly similar to that of an ebuild -- it
+is a bash script which is run in a special environment. This is
+intentional. There are ``DESCRIPTION`` and ``VERSION`` variables
+globally which are used by ``eselect`` and some of the default action
+handlers, and a series of functions.
+
+.. Warning:: In ebuilds, global scope code can cause problems.
+  In eselect modules, global scope code is **absolutely forbidden**.
+  Your module *will* be sourced for tasks other than running your
+  actions. For example, if ``eselect modules list`` is executed, your
+  module will be sourced to obtain the description. Any code being run
+  here would be a very bad thing.
+
+Unlike ebuilds, the function names are not fixed. Any function whose
+name starts with ``do_`` is considered to be an action implementation.
+It is conventional to have a ``describe_`` function for every ``do_``
+function that gives a short description of the function -- this is
+used for ``eselect modulename help``, for example.
+The ``describe_action_options`` and ``describe_action_parameters``
 functions are optional.
 
 .. Note:: If eselect is invoked as ``cow-config`` or ``cow-update`` (for
@@ -132,49 +136,50 @@ functions are optional.
 Standard Action Names
 ---------------------
 
-The following list contains suggested allowed names for actions. If there is no
-suitable name on the list for your task, it is best to ask for the list to be
-updated -- for consistency, it would be nice to have a standardised list of
-action names. (The cow module, being a silly demonstration module, is exempt.)
+The following list contains suggested allowed names for actions.
+If there is no suitable name on the list for your task, it is best to
+ask for the list to be updated -- for consistency, it would be nice to
+have a standardised list of action names. (The cow module, being a silly
+demonstration module, is exempt.)
 
 help
-        Display a help message. Automatic.
+    Display a help message. Automatic.
 usage
-        Display a usage message. Automatic.
+    Display a usage message. Automatic.
 version
-        Display the current version. Automatic.
+    Display the current version. Automatic.
 show
-        Used to display the current provider of a symlink, or the currently
-        installed module, or the current status.
+    Used to display the current provider of a symlink, or the currently
+    installed module, or the current status.
 list
-        Used to display all available providers of a symlink, or all available
-        modules.
+    Used to display all available providers of a symlink, or all
+    available modules.
 set
-        Used to set a new provider or a symlink.
+    Used to set a new provider or a symlink.
 enable
-        Used to enable an optional feature.
+    Used to enable an optional feature.
 disable
-        Used to disable an optional feature.
+    Used to disable an optional feature.
 scan
-        Read information off the current filesystem.
+    Read information off the current filesystem.
 update
-        Used to automatically select a new provider for a symlink (as opposed to
-        ``set``, which generally takes a parameter manually selecting the
-        provider) or to gather system information that is vital to further
-        actions.
+    Used to automatically select a new provider for a symlink (as
+    opposed to ``set``, which generally takes a parameter manually
+    selecting the provider) or to gather system information that is
+    vital to further actions.
 
-.. Note:: You can override the ``help``, ``usage`` and ``version`` actions. They
-  are provided by default by ``lib/default.eselect``. You should only do this
-  with a good reason. Removing them is not a good idea, ``eselect`` assumes
-  that they exist.
+.. Note:: You can override the ``help``, ``usage`` and ``version``
+  actions. They are provided by default by ``lib/default.eselect``.
+  You should only do this with a good reason. Removing them is not
+  a good idea, ``eselect`` assumes that they exist.
 
 Utility Functions
 =================
 
-eselect provides many utility functions. These are useful for standardised
-output formatting. Where possible, these should be used, especially for output.
-If a standard function is not available for the output format required, consider
-implementing one.
+eselect provides many utility functions. These are useful for
+standardised output formatting. Where possible, these should be used,
+especially for output. If a standard function is not available for the
+output format required, consider implementing one.
 
 The following categories of function are available by default:
 
@@ -198,32 +203,33 @@ These are implemented in ``libs/core.bash``.
 The ``die`` Function
 ,,,,,,,,,,,,,,,,,,,,
 
-The ``die`` function (which, unlike its ebuild counterpart, *can* be called from
-within subshells) is used to exit with a fatal error. It should be invoked as
-``die -q "Message to display"``. If the ``-q`` is not provided, a stacktrace
-will be displayed -- this should never happen because of user input error, only
-abnormal conditions.
+The ``die`` function (which, unlike its ebuild counterpart, *can* be
+called from within subshells) is used to exit with a fatal error. It
+should be invoked as ``die -q "Message to display"``. If the ``-q`` is
+not provided, a stacktrace will be displayed -- this should never happen
+because of user input error, only abnormal conditions.
 
 The ``check_do`` Function
 ,,,,,,,,,,,,,,,,,,,,,,,,,
 
-The ``check_do`` utility function checks that the first parameter is a function,
-and then calls it with any additional parameters as its arguments. If the
-function does not exist, ``die`` is called. Again, this is mostly internal.
+The ``check_do`` utility function checks that the first parameter is
+a function, and then calls it with any additional parameters as its
+arguments. If the function does not exist, ``die`` is called. Again,
+this is mostly internal.
 
 The ``do_action`` Function
 ,,,,,,,,,,,,,,,,,,,,,,,,,,
 
-The ``do_action`` utility function is the correct way to call a utility function
-which is defined in another module. The first parameter is the action,
-additional parameters are passed as arguments.
+The ``do_action`` utility function is the correct way to call a utility
+function which is defined in another module. The first parameter is the
+action, additional parameters are passed as arguments.
 
 The ``inherit`` Function
 ,,,,,,,,,,,,,,,,,,,,,,,,
 
-The ``inherit`` function sources eselect library files based on their name. In
-order to source the file ``libs/foo.bash`` you have to add ``inherit foo`` in
-global scope of your module.
+The ``inherit`` function sources eselect library files based on their
+name. In order to source the file ``libs/foo.bash`` you have to add
+``inherit foo`` in global scope of your module.
 
 The ``sed`` Function
 ,,,,,,,,,,,,,,,,,,,,
@@ -238,63 +244,65 @@ These are implemented in ``libs/output.bash``.
 The ``write_error_msg`` Function
 ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
 
-The ``write_error_msg`` function displays an error message in the standard
-format. It is similar to ``eerror``.
+The ``write_error_msg`` function displays an error message in the
+standard format. It is similar to ``eerror``.
 
 The ``write_warning_msg`` Function
 ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
 
-The ``write_warning_msg`` function displays a warning message in the standard
-format. It is similar to ``ewarn``.
+The ``write_warning_msg`` function displays a warning message in the
+standard format. It is similar to ``ewarn``.
 
 The ``write_list_`` Functions
 ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
 
-To display a list, the ``write_list_`` family of functions should be used. Lists
-should always start with a header, which can be displayed using
-``write_list_start The Header``.
+To display a list, the ``write_list_`` family of functions should be
+used. Lists should always start with a header, which can be displayed
+using ``write_list_start The Header``.
 
-To display a numbered list, the ``write_numbered_list_entry`` function should be
-used for each item. The first parameter is the list item number, the second is
-the list item text (remember to quote this).
+To display a numbered list, the ``write_numbered_list_entry`` function
+should be used for each item. The first parameter is the list item
+number, the second is the list item text (remember to quote this).
 
-To display a keyword/value list, the ``write_kv_list_entry`` function should be
-used. The first parameter is the key, the second the value.
+To display a keyword/value list, the ``write_kv_list_entry`` function
+should be used. The first parameter is the key, the second the value.
 
 The ``write_numbered_list`` function is a wrapper around
-``write_numbered_list_entry`` that handles the numbering automatically. Each
-parameter passed is displayed as a numbered list item, the first with index 1,
-the second with index 2 and so on. The -m option can be used to specify a
-negative report message that is output for an empty list.
+``write_numbered_list_entry`` that handles the numbering automatically.
+Each parameter passed is displayed as a numbered list item, the first
+with index 1, the second with index 2 and so on. The -m option can be
+used to specify a negative report message that is output for an empty
+list.
 
-If -p is passed as the first argument to these functions, 'plain' highlighting
-is used.
+If -p is passed as the first argument to these functions, 'plain'
+highlighting is used.
 
 The ``highlight`` Function
 ,,,,,,,,,,,,,,,,,,,,,,,,,,
 
-The ``highlight`` utility function can be used to emphasise some text which is
-to be displayed by any of the above functions. A typical invocation might look
-like: ::
+The ``highlight`` utility function can be used to emphasise some text
+which is to be displayed by any of the above functions. A typical
+invocation might look like: ::
 
     write_list_start "This is $(highlight list) example"
-    write_kv_list_entry "First" "This is the first"
-    write_kv_list_entry "$(highlight Second)" "This is the $(highlight second) entry"
+    write_kv_list_entry "First" "This is the first entry"
+    write_kv_list_entry \
+        "$(highlight Second)" "This is the $(highlight second) entry"
     write_kv_list_entry "Third" "$(highlight The end)"
 
 The ``highlight_warning`` Function
 ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
 
-The ``highlight_warning`` function is like ``highlight``, but for warnings. It
-displays the text in question in red.
+The ``highlight_warning`` function is like ``highlight``, but for
+warnings. It displays the text in question in red.
 
 The ``highlight_marker`` Function
 ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
 
-To mark a list entry as active/selected, the ``highlight_marker`` function
-should be used. First argument is the list entry. The function places a
-highlighted star (or its second argument instead, if set) behind the entry.
-A typical invocation might look like: ::
+To mark a list entry as active/selected, the ``highlight_marker``
+function should be used. First argument is the list entry. The function
+places a highlighted star (or its second argument instead, if set)
+behind the entry. A typical invocation might look like: ::
 
     for (( i = 0; i < ${#targets[@]}; i++ )); do
         [[ test_if_target_is_active ]] \
@@ -304,8 +312,8 @@ A typical invocation might look like: ::
 The ``space`` Function
 ,,,,,,,,,,,,,,,,,,,,,,
 
-The ``space`` utility function takes a single integer parameter. It displays
-that many space characters.
+The ``space`` utility function takes a single integer parameter.
+It displays that many space characters.
 
 Test Functions
 --------------
@@ -315,15 +323,16 @@ These are implemented in ``libs/tests.bash``.
 The ``has`` Function
 ,,,,,,,,,,,,,,,,,,,,
 
-The ``has`` utility function is like Portage's ``hasq``. It returns true if and
-only if the first parameter is equal to any of the remaining parameters.
+The ``has`` utility function is like Portage's ``hasq``. It returns true
+if and only if the first parameter is equal to any of the remaining
+parameters.
 
 The ``is_function`` Function
 ,,,,,,,,,,,,,,,,,,,,,,,,,,,,
 
-The ``is_function`` utility function returns true if and only if its parameter
-exists and is a function. This is mostly used internally, but may have some use
-for modules.
+The ``is_function`` utility function returns true if and only if its
+parameter exists and is a function. This is mostly used internally, but
+may have some use for modules.
 
 The ``is_number`` Function
 ,,,,,,,,,,,,,,,,,,,,,,,,,,
@@ -338,14 +347,14 @@ These are implemented in ``libs/path-manipulation``.
 The ``basename`` Function
 ,,,,,,,,,,,,,,,,,,,,,,,,,
 
-The ``basename`` function is a transparent bash-only replacement for the external
-``basename`` application.
+The ``basename`` function is a transparent bash-only replacement for the
+external ``basename`` application.
 
 The ``dirname`` Function
 ,,,,,,,,,,,,,,,,,,,,,,,,
 
-The ``dirname`` function is a transparent bash-only replacement for the external
-``dirname`` application.
+The ``dirname`` function is a transparent bash-only replacement for the
+external ``dirname`` application.
 
 The ``canonicalise`` Function
 ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
@@ -361,9 +370,9 @@ These are implemented in ``libs/manip.bash``.
 The ``svn_date_to_version`` Function
 ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
 
-The ``svn_date_to_version`` function can be used instead of manually keeping
-track of ``VERSION``. It is safe to use in global scope. The canonical usage is
-as follows: ::
+The ``svn_date_to_version`` function can be used instead of manually
+keeping track of ``VERSION``. It is safe to use in global scope.
+The canonical usage is as follows: ::
 
     SVN_DATE='$Date: $'
     VERSION=$(svn_date_to_version "${SVN_DATE}" )
@@ -381,10 +390,11 @@ The ``store_config`` Function
 ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
 
 The ``store_config`` function saves a key/value pair in a given
-configuration file which is passed as first argument. This file
-is a bash script consisting only of key/value pairs and should not be altered
-manually. Comments in the file will be deleted each time ``store_config`` is
-called. The function is invoked as ``store_config filename key value``.
+configuration file which is passed as first argument. This file is
+a bash script consisting only of key/value pairs and should not be
+altered manually. Comments in the file will be deleted each time
+``store_config`` is called. The function is invoked as
+``store_config filename key value``.
 
 The ``load_config`` Function
 ,,,,,,,,,,,,,,,,,,,,,,,,,,,,
@@ -396,10 +406,11 @@ and prints the associated value.
 The ``append_config`` Function
 ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
 
-The ``append_config`` function appends an item to an already stored value in the
-modules configuration file. It uses ``load_config`` / ``store_config``
-internally and should be invoked as ``append_config filename key item``. Note that
-the item will not be appended if it occurs in the key's value already.
+The ``append_config`` function appends an item to an already stored
+value in the modules configuration file. It uses ``load_config`` /
+``store_config`` internally and should be invoked as
+``append_config filename key item``. Note that the item will not be
+appended if it occurs in the key's value already.
 
 Multilib Functions
 ------------------
@@ -409,10 +420,10 @@ These are implemented in ``libs/multilib.bash``.
 The ``list_libdirs`` Function
 ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
 
-The ``list_libdirs`` function returns a set of valid libdirs for the used
-architecture. By default it uses /etc/ld.so.conf to obtain all valid libdirs. If
-this fails due to a missing or broken file, this function uses ``uname`` to
-determine the architecture.
+The ``list_libdirs`` function returns a set of valid libdirs for the
+used architecture. By default it uses /etc/ld.so.conf to obtain all
+valid libdirs. If this fails due to a missing or broken file, this
+function uses ``uname`` to determine the architecture.
 
 Package-Manager Functions
 -------------------------
@@ -422,63 +433,72 @@ These are implemented in ``libs/package-manager.bash``.
 The ``arch`` Function
 ,,,,,,,,,,,,,,,,,,,,,
 
-The ``arch`` function returns the correct value of ${ARCH} for the current
-system. If the package manager cannot provide this information, ``arch`` falls
-back to a ``uname -m`` and ``uname -s`` based lookup-table.
+The ``arch`` function returns the correct value of ${ARCH} for the
+current system. If the package manager cannot provide this information,
+``arch`` falls back to a ``uname -m`` and ``uname -s`` based
+lookup-table.
 
 The ``envvar`` Function
 ,,,,,,,,,,,,,,,,,,,,,,,,,
 
-The ``envvar`` function retrieves the contents of a configuration-environment
-variable for a given package. The syntax is ``envvar ${package-name}
-${var-name}``.
+The ``envvar`` function retrieves the contents of a
+configuration-environment variable for a given package. The syntax is
+``envvar ${package-name} ${var-name}``.
 
 The ``best_version`` Function
 ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
 
-The ``best_version`` function returns the highest available version for a
-given package dep atom.
+The ``best_version`` function returns the highest available version for
+a given package dep atom.
 
 The ``has_version`` Function
 ,,,,,,,,,,,,,,,,,,,,,,,,,,,,
 
-The ``has_version`` function checks whether a given versioned package dep atom
-is installed.
+The ``has_version`` function checks whether a given versioned package
+dep atom is installed.
 
 The ``get_repositories`` Function
 ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
 
-The ``get_repositories`` function returns a list of repositories known to the
-package manager.
+The ``get_repositories`` function returns a list of repositories known
+to the package manager.
 
 The ``get_repo_news_dir`` Function
 ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
 
-The ``get_repo_news_dir`` function returns the directory where to find GLEP 42
-news items for a given repository.
+The ``get_repo_news_dir`` function returns the directory where to find
+GLEP 42 news items for a given repository.
 
 A Basic Skeleton Library
 ========================
 
-The ``libs/skel.bash`` library provides for a simple eselect module to switch
-between implementations of anything that installs to a ``lib*`` directory
-(i.e., lib, lib32, lib64). This will satisfy the requirements for most cases in
-which one must switch between providers of a certain library or any package
-installing a library.
+The ``libs/skel.bash`` library provides for a simple eselect module to
+switch between implementations of anything that installs to a ``lib*``
+directory (i.e., lib, lib32, lib64). This will satisfy the requirements
+for most cases in which one must switch between providers of a certain
+library or any package installing a library.
 
 Creating a simple module
 ------------------------
 
-To use this library, all you need to do is create an eselect module containing
-settings for the MODULE and IFACE variables. The MODULE variable is the name
-used to refer to the implementations being switched in help text. The IFACE
-variable indicates the subdirectory of /etc/env.d/ in which eselect files for
-these implementations will be stored.
-
-Each package must install a symlink map using the ``add`` action. The map must
-use relative symlinks, one source-destination mapping per line in the form
-``source destination``. The source must be relative to the destination, not
-absolute. Instead of using ``lib`` or ``lib64`` etc., you must use @LIBDIR@.
-The ``libs/skel.bash`` library detects the proper library directory at runtime.
-
-.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+To use this library, all you need to do is create an eselect module
+containing settings for the MODULE and IFACE variables. The MODULE
+variable is the name used to refer to the implementations being switched
+in help text. The IFACE variable indicates the subdirectory of
+/etc/env.d/ in which eselect files for these implementations will be
+stored.
+
+Each package must install a symlink map using the ``add`` action. The
+map must use relative symlinks, one source-destination mapping per line
+in the form ``source destination``. The source must be relative to the
+destination, not absolute. Instead of using ``lib`` or ``lib64`` etc.,
+you must use @LIBDIR@. The ``libs/skel.bash`` library detects the proper
+library directory at runtime.
+
+.. Local Variables:
+.. mode: rst
+.. fill-column: 72
+.. indent-tabs-mode: nil
+.. End:
+
+.. vim: set ft=glep tw=72 sw=4 et spell spelllang=en :
diff --git a/doc/overview.txt b/doc/overview.txt
deleted file mode 100644
index b45f7b3..0000000
--- a/doc/overview.txt
+++ /dev/null
@@ -1,83 +0,0 @@
-A Brief Overview of eselect
-============================
-
-eselect is a modular framework for writing configuration utilities. It consists
-of:
-
-* A main program named ``eselect``.
-* Various modules (``*.eselect`` files) which carry out different tasks.
-* Several libraries which help ensure consistent behaviour and simplify the
-  creation of new modules.
-
-A module provides several actions. Actions typically either display some
-information (``list`` and ``show`` actions are common) or update the system
-somehow (for example, ``set`` and ``update``). Each module also provides
-``help`` and ``usage`` actions which explains how to use the module.
-
-eselect is invoked as ``eselect <module> <action>``. Some actions take
-additional arguments -- these are added to the commandline.
-
-Some modules install symlinks to the main program. eselect handles these
-intelligently -- for example, it realises that ``profile-config list`` should be
-treated as if the user had run ``eselect profile list``.
-
-Advantages for End Users and System Administrators
---------------------------------------------------
-
-For system administrators and end users, tools written as eselect modules offer
-several advantages over the traditional 'write each tool from scratch' approach:
-
-Consistent user interface
-    eselect modules provide a consistent user interface. Thanks to eselect's
-    action framework, there is no longer any need to remember or look up dozens
-    of ``-x`` style switches for each tool. The output format used by modules is
-    also standardised.
-
-Consistent help format
-    All eselect modules provide easily accessible help documentation via the
-    ``help`` and ``usage`` actions.
-
-Consistent tool naming
-    There is no need to remember dozens of ``foo-config`` and ``update-blah``
-    names. To see a list of available tools, simply run ``eselect`` with no
-    arguments. Of course, the ``foo-config`` style names are still available
-    (via symlinks) if you prefer.
-
-Guaranteed Support for ``$ROOT``
-    For those of you using ``$ROOT``, you will not have to worry about whether a
-    particular tool can handle it. Support for ``$ROOT`` is required for all
-    eselect modules.
-
-Advantages for Developers and Package Maintainers
--------------------------------------------------
-
-Writing your tool as an eselect module rather than starting from scratch gives
-you various benefits:
-
-Faster Development Time
-    Much of the work is already done for you. eselect provides a series of
-    libraries for common tasks, and the main ``eselect`` program handles most
-    of the hard work for you. All you need to do is provide the actions and any
-    domain-specific functions you require.
-
-Automatic Actions
-    The ``help`` and ``usage`` actions are automatically generated from your
-    actions, so there's no need to spend time worrying about keeping these
-    written and up to date.
-
-Easy Consistent Behaviour
-    Because most of the input, output and commandline handling is split off into
-    library functions, writing a 'standard' module which behaves consistently
-    with other tools is very simple.
-
-Familiar Format
-    For Gentoo developers, the eselect module format will be very familiar --
-    it is a ``bash`` file with similar structure to ebuilds.
-
-Further Documentation
----------------------
-
-Further user and developer documentation is included with the main eselect
-distribution.
-
-.. vim: set ft=glep tw=80 sw=4 sts=4 et spell spelllang=en : ..
diff --git a/doc/release-guide.txt b/doc/release-guide.txt
index 40a1da7..9e37520 100644
--- a/doc/release-guide.txt
+++ b/doc/release-guide.txt
@@ -1,16 +1,16 @@
 eselect Release Guide
 ======================
 
-.. Note:: This guide is intended for people who do ``eselect`` releases. It is
-  probably of no interest to the rest of you.
+.. Note:: This guide is intended for people who do ``eselect`` releases.
+  It is probably of no interest to the rest of you.
 
 Update version in configure.ac.
 
-Make sure ChangeLog is tidy.  Add ChangeLog entry for updating configure.ac
-and tagging the release.
+Make sure ChangeLog is tidy. Add ChangeLog entry for updating
+configure.ac and tagging the release.
 
-Update NEWS file with a summary of changes mentioned in ChangeLog since the
-last release.
+Update NEWS file with a summary of changes mentioned in ChangeLog since
+the last release.
 
 Do a test run in trunk/. ::
 
@@ -43,4 +43,10 @@ Sign it (there may be a dist-sign target in the future). ::
 
     $ gpg --armor --detach-sign ${P}.tar.bz2
 
-.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+.. Local Variables:
+.. mode: rst
+.. fill-column: 72
+.. indent-tabs-mode: nil
+.. End:
+
+.. vim: set ft=glep tw=72 sw=4 et spell spelllang=en :
diff --git a/doc/user-guide.txt b/doc/user-guide.txt
index dd19e05..5df9a9f 100644
--- a/doc/user-guide.txt
+++ b/doc/user-guide.txt
@@ -8,71 +8,80 @@ A Brief Overview
 Introduction
 ------------
 
-eselect is a tool for administration and configuration on Gentoo systems. It
-_will_ modify the system's behaviour and should be used with care by the system
-administrator. eselect is a modular framework for writing configuration
-utilities. It consists of:
+eselect is a tool for administration and configuration on Gentoo
+systems. It _will_ modify the system's behaviour and should be used with
+care by the system administrator. eselect is a modular framework for
+writing configuration utilities. It consists of:
 
 * A main program named ``eselect``.
 * Various modules (``*.eselect`` files) which carry out different tasks.
-* Several libraries which help ensure consistent behaviour and simplify the
-  creation of new modules.
+* Several libraries which help ensure consistent behaviour and simplify
+  the creation of new modules.
 
 A module provides several actions. Actions typically either display some
-information (``list`` and ``show`` actions are common) or update the system
-somehow (for example, ``set`` and ``update``). Each module also provides
-``help`` and ``usage`` actions which explain how to use the module.
+information (``list`` and ``show`` actions are common) or update the
+system somehow (for example, ``set`` and ``update``). Each module also
+provides ``help`` and ``usage`` actions which explain how to use the
+module.
 
 Some modules install symlinks to the main program. eselect handles these
-intelligently -- for example, it realises that ``profile-config list`` should be
-treated as if the user had run ``eselect profile list``.
+intelligently -- for example, it realises that ``profile-config list``
+should be treated as if the user had run ``eselect profile list``.
 
 Advantages for End Users and System Administrators
 --------------------------------------------------
 
-For system administrators and end users, tools written as eselect modules offer
-several advantages over the traditional 'write each tool from scratch' approach:
+For system administrators and end users, tools written as eselect
+modules offer several advantages over the traditional 'write each tool
+from scratch' approach:
+
+Consistent user interface
+    eselect modules provide a consistent user interface. Thanks to
+    eselect's action framework, there is no longer any need to remember
+    or look up dozens of ``-x`` style switches for each tool. The output
+    format used by modules is also standardised.
 
-Consistent UI
-  eselect modules provide a consistent user interface. Thanks
-  to eselect's action framework, there is no longer any need to remember or
-  look up dozens of ``-x`` style switches for each tool. The output format
-  used by modules is also standardised.
 Consistent help format
-  All eselect modules provide easily accessible help documentation via the
-  ``help`` and ``usage`` actions.
+    All eselect modules provide easily accessible help documentation via
+    the ``help`` and ``usage`` actions.
+
 Consistent tool naming
-  There is no need to remember dozens of ``foo-config`` and ``update-blah``
-  names. To see a list of available tools, simply run ``eselect`` with no
-  arguments. Of course the foo-config style are still available (via symlinks)
-  if you prefer them.
+    There is no need to remember dozens of ``foo-config`` and
+    ``update-blah`` names. To see a list of available tools, simply run
+    ``eselect`` with no arguments. Of course, the ``foo-config`` style
+    names are still available (via symlinks) if you prefer them.
+
 Guaranteed support for ``$ROOT``
-  For those of you using $ROOT, you will not have to worry about whether a
-  particular tool can handle it. Support for ``$ROOT`` is required for all
-  eselect modules.
+    For those of you using ``$ROOT``, you will not have to worry about
+    whether a particular tool can handle it. Support for ``$ROOT`` is
+    required for all eselect modules.
 
 Advantages for Developers and Package Maintainers
 -------------------------------------------------
 
-Writing your tool as an eselect module rather than starting from scratch gives
-you various benefits:
+Writing your tool as an eselect module rather than starting from scratch
+gives you various benefits:
 
 Faster development time
-  Much of the work has already been done for you. eselect provides a series
-  of libraries for common tasks, and the main ``eselect`` program handles
-  most of the hard work for you. All you need to do is provide the actions and
-  any domain specific functions you require.
+    Much of the work has already been done for you. eselect provides a
+    series of libraries for common tasks, and the main ``eselect``
+    program handles most of the hard work for you. All you need to do is
+    provide the actions and any domain-specific functions you require.
+
 Automatic actions
-  The ``help`` and ``usage`` actions are automatically generated from your
-  actions, so there is no need to spend time worrying about keeping these
-  written up to date.
+    The ``help`` and ``usage`` actions are automatically generated from
+    your actions, so there is no need to spend time worrying about
+    keeping these written up to date.
+
 Easy, consistent behaviour
-  Because most of the input, output and command line handling is split off
-  into library functions, writing a 'standard' module which behaves
-  consistently with other tools is very simple.
+    Because most of the input, output and command line handling is split
+    off into library functions, writing a 'standard' module which
+    behaves consistently with other tools is very simple.
+
 Familiar format
-  For Gentoo developers, the eselect module format will be very familiar -- it
-  is a ``bash`` file with a structure that is quite similar to ebuilds.
+    For Gentoo developers, the eselect module format will be very
+    familiar -- it is a ``bash`` file with a structure that is quite
+    similar to ebuilds.
 
 Using eselect
 =============
@@ -82,35 +91,35 @@ Usage
 
 eselect should be called as shown below: ::
 
-	eselect [<global-options>] <module> <action> <options>
+        eselect [<global-options>] <module> <action> <options>
 
-eselect features consistently named actions among most of its modules. There
-is only one global option as of now; --no-colour, which asks eselect to stop
-showing colored output. The following are standard action names -- each module
-may provide a subset of these actions:
+eselect features consistently named actions among most of its modules.
+There is only one global option as of now; --no-colour, which asks
+eselect to stop showing colored output. The following are standard
+action names -- each module may provide a subset of these actions:
 
 help
-  Print the modules help screen.
+    Print the modules help screen.
 usage
-  Print information on how to invoke the modules actions.
+    Print information on how to invoke the modules actions.
 version
-  Print the modules version and other useful information.
+    Print the modules version and other useful information.
 list
-  Prints a set of selectable options.
+    Print a set of selectable options.
 show
-  Prints the currently active configuration(s).
+    Print the currently active configuration(s).
 set
-  Select one of the options offered by ``list``.
+    Select one of the options offered by ``list``.
 enable
-  Enable one of the module specific features.
+    Enable one of the module specific features.
 disable
-  Disable one of the module specific features.
+    Disable one of the module specific features.
 update
-  Like ``set``, but automatically selects an option rather than taking a
-  parameter.
+    Like ``set``, but automatically selects an option rather than taking
+    a parameter.
 scan
-  Gather information about the system and store it for future usage by the
-  module.
+    Gather information about the system and store it for future usage by
+    the module.
 
 A typical session will look like the following for most modules: ::
 
@@ -126,4 +135,10 @@ A typical session will look like the following for most modules: ::
 
 You can usually set items either by name or by number.
 
-.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+.. Local Variables:
+.. mode: rst
+.. fill-column: 72
+.. indent-tabs-mode: nil
+.. End:
+
+.. vim: set ft=glep tw=72 sw=4 et spell spelllang=en :