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.

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 installation is

Navigation
**********

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.

<S-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).

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.

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

d  (elpher-download)

g  (elpher-go)

O  (elpher-root-dir)

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

Bookmarks
*********

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

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