README.md

   1 # Elpher
   2
   3 Elpher aims to provide a full-featured gopher client for GNU Emacs.
   4
   5 It supports:
   6 - simple keyboard and mouse-driven browsing, including out-of-the-box
   7   compatibility with evil-mode,
   8 - caching of visited sites,
   9 - clean and configurable visualization of Gopher directories,
  10 - direct visualisation of image files,
  11 - jumping directly to links by name (with autocompletion),
  12 - clickable web and gopher links in plain text.
  13
  14 Keep the non-web internet alive!
  15
  16 ## Installation
  17
  18 To install, simply save the file `elpher.el` and use `M-x
  19 package-install-file`, specifying the path to the saved elisp file.
  20
  21 To uninstall, use `M-x package-delete`.
  22
  23 ## Usage
  24
  25 Once installed, use `M-x elpher` to launch the browser.  This will
  26 open a start page which documents the default key bindings and
  27 provides some links to help kick start your exploration of gopherspace.
  28
  29 To customize the various faces Elpher uses, the start page
  30 and a few other odds and ends, simply use `M-x customize-group`
  31 and enter "elpher" at the group prompt.
  32
  33 ## History and Caching
  34
  35 This is an aspect of Elpher that perhaps requires separate explanation.
  36
  37 Every item you visit with Elpher is modeled as a "node" in a tree.
  38 For instance, a gopher directory represents a single node.  When
  39 you open such a directory, Elpher creates nodes for every entry
  40 in that directory and makes these children of the original directory node:
  41
  42                X  <- current directory node
  43                |
  44             -------
  45             |  |  |
  46             o  o  o  <- nodes representing entries in directory
  47
  48 If one of those entries is itself a directory and you click on it,
  49 Elpher marks that node the current node, and extends the tree as follows:
  50
  51                o  <- original directory node
  52                |
  53             -------
  54             |  |  |
  55             o  o  X  <- current directory node (marked with X)
  56                   |
  57               ---------
  58               | | | | |
  59               o o o o o  <- nodes representing entries in new directory
  60
  61 Pressing the 'u' key (introduced on page which opens when elopher starts)
  62 always moves to the page representing "parent" node, whatever that is.
  63
  64 Once a node is visited, its "contents" (i.e. whatever is retrieved
  65 from the gopher server) are recorded with the corresponding node.  The
  66 cursor position (point) is also stored. If the node is visited again,
  67 the cached contents are displayed and the cursor returns to its
  68 previous position.  This makes navigating amongst different documents
  69 referenced from within the same directory very snappy.
  70
  71 This hierarchy is also maintained when gopher URLs are followed from plain
  72 text documents, and when directories are retrieved explicitly using the 'g'
  73 key.
  74
  75 ## Licence
  76
  77 Elpher is free software and is distributed under the terms of version
  78 3 the GNU General Public License, which can be found in the file named
  79 COPYING.