README.md

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