Update README

README.rst

@@ -1,8 +1,7 @@
 .emacs.d
 ========
 
-My personal Emacs configuration.  It comes with a heavily modified version of
-the ``underwater`` theme available from the Emacs repos.
+My personal Emacs configuration.
 
 Installation
 ------------
@@ -13,13 +12,90 @@ Just clone this repository into your home directory:
 
    git clone https://github.com/Wojtek242/.emacs.d ~/.emacs.d
 
-It uses a simple addition to the built-in package management called EModule_.
+This configuration uses the `Source Code Pro`_ font.  If you do not have it
+installed and it isn't available through your distribution you can install
+the font by running
 
-Under development
------------------
+::
 
-I expect this configuration to stall at certain points.  I am hoping to iron
-out these cases as I stumble upon them.
+   git clone https://github.com/adobe-fonts/source-code-pro.git --branch release ~/.local/source-code-pro
+   sudo cp ~/.local/source-code-pro/OTF/*.otf /usr/local/share/fonts
 
+After cloning the repository and waiting for all packages to install on the
+first startup you will also have to run the following command from within Emacs
+in order to get all the icons used by the modeline
 
-.. _EModule: https://github.com/Wojtek242/emodule
+::
+
+   M-x all-the-icons-install-fonts
+
+Rust support
+------------
+
+If you would like to use this configuration with the Rust programming language
+you will want to also clone the submodules to get the patched version of Racer
+and Deferred so when cloning remember to use the ``--recursive`` option
+
+::
+
+   git clone --recursive https://github.com/Wojtek242/.emacs.d ~/.emacs.d
+
+You will also have to install the Rust standard library sources and set the
+environment variable ``RUST_SRC_PATH`` to point at the source directory.
+
+Package Management
+------------------
+
+This ``.emacs.d`` uses its own small framework for package management located
+in the ``emodule`` directory.  Its operation is heavily inspired by Spacemacs_,
+but is much smaller with fewer features and thus simpler.
+
+The purpose of using such a package manager is to ensure that all packages are
+always installed before any configuration happens.  Furthermore, it will also
+remove all unused packages and manage upgrades and backups.
+
+Package configuration happens in the ``modules`` directory.  A file called
+``MODULE.el`` corresponds to an individual ``MODULE``.  Inside each module
+file, all the pre-requisite packages must be defined in a variable called
+``emodule/MODULE-packages`` and all package configuration must be done in a
+single function called ``emodule/MODULE-init``.  Each module must also be added
+to the ``emodule/init`` call in the ``init.el`` file.
+
+The ``emodule`` package manager runs during every startup. It will first ensure
+all packages are installed before it runs any ``init`` functions so it is safe
+to write configuration for packages that depends on other packages without any
+concerns about ordering. This applies even if the configuration is spread
+across multiple modules.
+
+When Emacs is first launched with this configuration it will download all
+the ``Elpa`` and ``Melpa`` packages that it needs so the first startup takes
+much longer to complete.
+
+Upgrades are supported and can be initiated either from the home screen or by
+calling ``emodule/upgrade``.  I don't like tracking ``elpa`` with git as it
+introduces a lot of code churn and makes analysing diffs, especially between
+distant commits, very difficult. Instead, on each upgrade the ``elpa``
+directory will be backed up to ``elpa.tar.xz``.  You can restore the last
+backup by calling ``emodule/restore``. This repository should always contain a
+functional backup of ``elpa``.
+
+Theme
+-----
+
+The theme in use started with the ``underwater`` theme and has been heavily
+modified, with inspiration from the Spacemacs_ theme, to add support for all
+new faces introduced by the installed packages.  The code setting up the theme
+is quite messy.  It is my plan to simplify it one day.
+
+The theme files are located in ``themes``.
+
+Stability
+---------
+
+I have been using this configuration at work and at home for many months now
+which helped flush many bugs.  It has been pretty reliable, but suffers from
+the occasional glitches which I think are more due to the limitations of
+Emacs and the packages used than errors in my configuration.
+
+.. _Spacemacs: http://spacemacs.org/
+.. _`Source Code Pro`: https://github.com/adobe-fonts/source-code-pro