X-Git-Url: https://thelambdalab.xyz/gitweb/index.cgi?a=blobdiff_plain;f=README.md;h=af0c1842b8f6585481fc52f7998b5a7981351451;hb=71b4b025b5c0450405aae3d342428cfd624ace01;hp=7998055cf3b664ee568004db150740ba6f24f51e;hpb=e0e6d24fd9f7c1a62364fdd82be207ffbb98589f;p=elpher.git

diff --git a/README.md b/README.md
index 7998055..af0c184 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,92 @@
-# elopher
+Elpher
+======
 
-Simple gopher client for emacs.
+Elpher aims to provide a full-featured gopher client for GNU Emacs.
 
-## Licence
+It supports:
+- simple keyboard and mouse-driven browsing, including out-of-the-box
+  compatibility with evil-mode,
+- caching of visited sites,
+- clean and configurable visualization of Gopher directories,
+- direct visualisation of image files,
+- jumping directly to links by name (with autocompletion),
+- clickable web and gopher links in plain text,
+- a simple bookmark management system.
 
-Elopher is free software and is distributed under the terms of version
+Installation
+------------
+
+Elpher is available from [MELPA](https://melpa.org).  If you have
+never installed packages from this repository before, you'll need
+to follow the instructions at https://melpa.org/#/getting-started.
+
+To install Elpher, enter the following:
+
+    M-x package-install RET elpher RET
+
+To uninstall, use `M-x package-delete RET elpher RET`.
+
+Usage
+-----
+
+Once installed, use `M-x elpher` to launch the browser.  This will
+open a start page which documents the default key bindings and
+provides some links to help kick start your exploration of gopherspace.
+
+To customize the various faces Elpher uses, the start page
+and a few other odds and ends, use the following:
+
+    M-x customize-group RET elpher RET
+
+History and Caching
+-------------------
+
+This is an aspect of Elpher that perhaps requires separate explanation.
+
+Every item you visit with Elpher is modeled as a "node" in a tree.
+For instance, a gopher directory represents a single node.  When
+you open such a directory, Elpher creates nodes for every entry
+in that directory and makes these children of the original directory node:
+
+               X  <- current directory node
+               |
+            -------
+            |  |  |
+            o  o  o  <- nodes representing entries in directory
+
+If one of those entries is itself a directory and you click on it,
+Elpher marks that node the current node, and extends the tree as follows:
+
+               o  <- original directory node
+               |
+            -------
+            |  |  |
+            o  o  X  <- current directory node (marked with X)
+                  |
+              ---------
+              | | | | |
+              o o o o o  <- nodes representing entries in new directory
+              
+Pressing the 'u' key (introduced on page which opens when elopher starts)
+always moves to the page representing "parent" node, whatever that is.
+
+Once a node is visited, its "contents" (i.e. whatever is retrieved
+from the gopher server) are recorded in memory with the corresponding
+node.  The cursor position (point) is also stored. If the node is
+visited again in the same session, the cached contents are displayed
+and the cursor returns to its previous position.  This makes
+navigating amongst different documents referenced from within the same
+directory very snappy. (To conserve memory, this caching isn't by
+default applied to images entries viewed in the browser.)
+
+This hierarchy is also maintained when gopher URLs are followed from plain
+text documents, and when directories are retrieved explicitly using the 'g'
+key. When it is viewed, the bookmark page also becomes a part of this
+hierarchy.
+
+Licence
+-------
+
+Elpher is free software and is distributed under the terms of version
 3 the GNU General Public License, which can be found in the file named
 COPYING.