Elpher
******

This manual documents Elpher, a gopher client for Emacs.

Copyright © 2019 Tim Vaughan

     The source and documentation of Elpher is free software.  You can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

     Elpher is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNElpher FOR A PARTICULAR PURPOSE. See the GNU General Public License in the file COPYING in the same directory as this file for more details.

Introduction
************

Elpher aims to be a capable and practical gopher client for Emacs.  Its focus is on easy keyboard-driven navigation based on sensible default bindings (with out-of-the-box support for Evil).  It is intended to be robust and behave in non-surprising ways at all times.  Additionally, Elpher provides the following bells and whistles:

  * an easily navigable history, sporting caching of visited pages (both content and cursor position),

  * auto-completing menu item navigation,

  * followable web and gopher links in plain text,

  * direct visualization of image files where supported (no writing to disk), and

  * a simple bookmark management system.

Elpher is still under active development.  Although we try very hard to ensure that releases are bug-free, this cannot be guaranteed.  However, this also means that any usability features that you feel are missing can likely by incoroporated quickly, so please get in touch if you have some ideas.

Installation
************

Elpher is available from the MELPA package repository.  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.

While not recommended, it is also possible to install Elpher directly by downloading the file elpher.el from https://github.com/tgvaughan/elpher, adding it to a directory in your load-path, and then adding

     (require 'elpher)

to your Emacs initialization file.

Quick Start
***********

Before diving into the minutiae of the different commands available, we will quickly describe how to get up and running with Elpher.

Once installed, you can launch Elpher using

     M-x elpher RET

This will switch to the *Elpher* buffer and display a start page, with information on each of the default keyboard bindings.

From here you can move point between links (which may be menu items or inline URLs in text files) by using TAB and S-TAB, as in Info.  You can also jump directly to a menu item using m, or use the standard Emacs or Evil motion and search commands to find your way around.  To open a link, press RET.  (Where a mouse is available, Clicking on a link with the mouse cursor has the same effect.)

To return to the page you just followed the link from, press u.

Elpher caches (for the duration of an Emacs session) both page contents and the position of point on each of the pages (gopher menus, query results, or text pages) you visit, restoring these when you next visit the same page.  Thus, pressing u displays the previous page in exactly the same state as when you left, meaning that you can quickly and visually explore the different documents in a menu without having to wait for anything to reload.

Of course, sometimes you'll want to reload the current page rather than stick with the cached version.  To do this use R. (This is particularly useful for search query results, where this allows you to perform a different search.)

That's more-or-less it. Elpher supports a number of other features, such as bookmarking, support for different coding schemes and TLS encryption, and a variety of customization options, all of which are explained in the rest of this document.  However the emphasis is on keeping the basic navigation experience as intuitive and responsive as possible.

Navigation
**********

by Throughout this manual, we use the word ``page'' to refer to any visualization of a response from a gopher server, be it a menu/directory, query result, text file or image.  We use

Elpher's navigation interface is inspired by the Emacs Info mode. Movement within a page is essentially the same as moving around any other text file in Emacs, but with special keys for quickly jumping between menu items and URLs in text files. Movement between pages is facilitated by a simple linear history coupled with caching of pages and cursor position.

Within-page navigation
======================

To move about within a page, you should be able use the same keys you usually use to browse files in Emacs.  This is even true when Evil mode is enabled. Paragraph hopping, searching etc should work as usual.

In addition, the following commands are provided for quickly moving between links and menu items.

TAB  (elpher-next-link)
     Move to the next link or menu item in the file.

Shift-TAB/backtab  (elpher-prev-link)
     Move to the previous link or menu item in the file.

m  (elpher-jump)
     Jump directly to a link within a file by specifying its display string or link text.  (Unlike the previous two commands, this immediately opens the selected link.

The following commands can be used to retrieve information about the current page, or the address of the link at point:

i  (elpher-info-link)
     Display host, port and selector information for the link at point.

I  (elpher-info-current)
     Display host, port and selector information for the current page.

c  (elpher-copy-link-url)
     Add URL representing address of link at point to the kill-ring and the system clipboard (if available).

C  (elpher-copy-current-url)
     Add URL representing address of the current page to the kill-ring and the system clipboard (if available).

d  (elpher-download)
     Download link at point and save the result as a file.  The minibuffer will prompt for the name of the file to write, with the default name being the display string (if available) associated with the link.

D  (elpher-download-current)
     This is similar to elpher-downlowd, but instead applies to the current page rather than a link.

w (elpher-view-raw)
     This displays the raw server response for the current page.  While not useful for general browsing, it is useful for debugging incorrect rendering or out-of-spec server responses.

Between-page navigation
=======================

Moving to a different page can be accomplished in several ways, described by the following command:

RET, mouse-1  (elpher-follow-link)
     Follow the menu item or link at point (or selected with the mouse).

     Exactly what is meant by ``follow'' depends on the kind of item selected:

       * For text or menu type items or links, the curent page text is replaced by the text of this item.  Unless the customization variable elpher-use-header (see Customization) is nil, the display string of the link is displayed in the buffer header. Links to images behave similarly on Emacs systems supporting the display of bitmap graphics, however their content is not cached in memory by default.

       * When followed, links to search/query items (type 7) prompt for input in the minibuffer then display the results in the same way as for text and menu items.

       * Following links to binary files (and image files on unsupported systems) causes Elpher to prompt for a filename in which to save the content.

       * Following links of type `h' with a selector having the `URL:' prefix, or non-gopher URLs in text files, will result in Elpher using an external programme to open the URL.  This will be either the default system browser or, if the elpher-open-urls-with-eww customization variable is non-nil, Emacs' own EWW browser. (See Customization.)

     Once a text, menu or query response page has been displayed, its contents are cached for the duration of the Emacs session.

g  (elpher-go)
     Open a particular page by specifying either its URL or directly entering a host, port and selector.

     Note that if a non-gopher protocol is used in the URL the result will be the same as following a URL link of the same type from a gopher menu.

O  (elpher-root-dir)
     Open the root page (empty selector) on the current host.

u  (elpher-back)
     Return to the previous page, where ``previous'' means the page where the page which was displayed immediately before the current page.

History and Caching
===================

The history and caching strategy in Elpher is extremely simple, but may be confusing without a good mental model of how it works.  That is what this section attempts to provide.

Essentially, every time you navigate to a new page, either by clicking or pressing RET on a link, using g to jump to a new page by its address, or using O to open the root selector, the following two things occur:

 1. the cursor position and content for the original page are recorded in an in-memory cache, and

 2. the original page is set as the ``parent'' of the new page.

The only way to return to pages in this history is by using u, which returns to the previous of the current page. (The addition of the new page to the history happens even if the new page is one that has been seen before. This is mostly the desired behaviour.  However, opening an explicit ``back'' link provided by a gopher menu will also add a new entry to the history.  Unless you haven't yet visited that menu, it's therefore better to use u to go back in this case.)

One aspect that may seem peculiar is that Elpher lacks a corresponding ``next'' or ``forward'' command.  However, since Elpher caches the position of point, this will be automatically positioned on the link that was most recently followed from a given page.  This means that, at least for links followed from menus and text files, the inverse of u is actually just RET.

Bookmarks
*********

Elpher has a very simple link bookmarking system involving the following commands:

a  (elpher-bookmark-link)
     Add a bookmark for the link at point.  The minibuffer will prompt for a name for the bookmark, which defaults to the display string.

A  (elpher-bookmark-current)
     Add a bookmark for the current page.  The minibuffer will prompt for a name for the bookmark, defaulting to the display string associated with the link that was followed to reach the current page.

x  (elpher-unbookmark-link)
     Immediately remove the bookmark (if one exists) to the link at point.

X  (elpher-unbookmark-current)
     Immediately remove the bookmark (if one exists) to the current page.

B  (elpher-bookmarks)
     Open a page displaying all current bookmarks.  Note that this bookmark page is added to the history just as if you had opened it using a link. Thus to return to the previous page, use u.  This also means that you can peruse the various bookmarks by visiting them in turn, using u to return to the bookmark page (where the position of point is cached), then moving to another bookmarked link and so on.

Bookmarks are stored as a s-exp in the file elpher-bookmarks in the user emacs directory (usually ~/.emacs.d/). Any command which modifies the list of bookmarks immediately updates this file.

Character encodings
*******************

Responses Elpher retrieves from servers are initially read as pure binary data.  When the data is intended to be interpreted as textual (as determined by the type parameter of the gopher menu item or the gopher URL), this data needs to be decoded into a sequence of characters.  To do this properly requires knowledge of the encoding system used by whoever authored the document.

Unfortunately gopher lacks a systematic way of acquiring this necessary information. Thus, the details of the coding system must be either inferred from the binary data, or must be specified by the user.

By default, Elpher applies Emacs' built-in character encoding detection system to the full (undecoded) response data and uses this to attempt to convert it into a character string. (see Recognizing coding systems (emacs).) While this can be okay, it is important to realise that its inference algorithm is extremely primitive and depends heavily on assumptions based on the language settings of your emacs system.

The alternative is to explicitly set the coding system used for decoding using the following command:

S  (elpher-set-coding-system)
     Causes a elpher to prompt for a coding system to use for decoding future text.  The TAB key can be used at this prompt to display a list of alternatives (which is extensive) and to autocomplete.  An empty response will cause Elpher to return to its default autodetection behaviour.

     Note that changing the coding system only affects newly loaded text. Thus, if text has already been decoded using an incorrect system, you will need to select the correct coding and then reload the text using R.

Encrypted connections
*********************

Customization
*************