Elpher Manual v3.6.0

Next: , Previous: , Up: (dir)   [Contents][Index]

Elpher

This manual documents Elpher, a gopher and gemini client for Emacs.

Copyright © 2019-2023 Tim Vaughan
Copyright © 2021 Daniel Semyonov
Copyright © 2021 Alex Schroeder

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 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License in the file COPYING in the same directory as this file for more details.

Table of Contents


Next: , Previous: , Up: Elpher   [Contents][Index]

1 Introduction

Elpher aims to be a capable and practical gopher and gemini 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:

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 incorporated quickly, so please get in touch if you have some ideas.


Next: , Previous: , Up: Elpher   [Contents][Index]

2 Installation


2.1 Installing from ELPA or MELPA

Elpher is available on the non-GNU ELPA package archive. If you are using Emacs 28 or later, this archive should be available on your system by default. For Emacs 27, you’ll need to follow the instructions at https://elpa.nongnu.org to make the archive accessible.

Alternatively, Elpher is available from the MELPA package archive. If you have never installed packages from this repository before, you’ll need to follow the instructions at https://melpa.org/#/getting-started.

Once one of these package archives is installed, enter the following to install Elpher:

M-x package-install RET elpher RET

To uninstall, use

M-x package-delete RET elpher RET.

2.2 Installing by hand

It is also possible to install Elpher directly by downloading the file elpher.el from gopher://thelambdalab.xyz/1/projects/elpher (you’ll need to download the “source archive” and extract it), adding it to a directory in your load-path, and then adding

(require 'elpher)

to your Emacs initialization file.


Next: , Previous: , Up: Elpher   [Contents][Index]

3 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, gemini pages, 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 a 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.

Note that you can launch multiple Elpher sessions in parallel by using a prefix:

C-u M-x elpher RET

5 Bookmarks

Elpher makes use of standard Emacs bookmarks. See Bookmarks in The Emacs Editor. The following commands are used to add new bookmarks:

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.

B (elpher-open-bookmarks)

Visit a page displaying all elpher bookmarks. The behaviour of the this function depends on the customization variable elpher-use-emacs-bookmark-menu. If nil (the default), the command will visit a special elpher page listing all elpher-specific bookmarks. If non-nil, the command will simply open the standard Emacs bookmark list displaying all current bookmarks (including non-elpher bookmarks).

C-x r l (bookmark-bmenu-list)

This command opens the standard Emacs bookmark menu, with which bookmarks can be renamed, deleted or annotated.

On opening the bookmarks page, elpher will offer to import any legacy (2.x) bookmarks files into the new system. Once the import is complete, the original bookmarks file will have “-legacy” appended to it, so so that elpher knows not to import it again.

If you have any other legacy bookmark files (besides the one in the original location, or specified in the elpher-bookmarks-file customization variable, which should be automatically detected), you can can import these using

M-x elpher-bookmark-import RET

Once this is done, you may delete these legacy bookmarks files.


6 Gopher 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 see (emacs)Recognizing coding systems.) While this approach can be okay, it is important to realize 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:

! (elpher-set-coding-system)

Causes a elpher to prompt for a coding system to use for decoding future gopher text. The TAB key can be used at this prompt to display a list of alternatives (which is extensive) and to auto-complete. An empty response will cause Elpher to return to its default auto-detection 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.


7 Encrypted gopher connections

While RFC 1436 does not broach the topic of encryption at all, several modern gopher servers can serve content over encrypted connections, and a common choice for this is TLS.

Elpher can retrieve selectors using Emacs’ built-in TLS support which uses the GnuTLS library. (It is possible to build emacs without GnuTLS, in which case encryption is not supported.)

To retrieve documents using TLS, Elpher’s TLS mode must be enabled. This can be directly toggled using T, but note that just as with the character encoding, changing this mode only affects subsequent connections.

Alternatively, TLS mode is automatically enabled whenever gopher URLs starting with gophers:// are followed.

The mode is sticky, so it remains active until switched off. It can also be automatically switched off when a TLS connection fails. In this case Elpher will prompt for your confirmation to ensure that you can’t accidentally make a non-TLS connection.


8 Gemini support

Gemini is a new protocol being developed by several members of gopherspace. It aims to solve some of the long-standing technical issues associated with gopher as a protocol, while keeping the major benefits. For instance, it _requires_ encrypted connections, it does away with the selector type, and allows servers to explicitly specify the character coding scheme used for text documents.

The latest versions of Elpher aim to provide seamless transitions between gemini and gopher documents. Basically you should be able to open, bookmark, download and otherwise interact with gemini pages in exactly the same way as you do with other non-gemini pages. The only major difference from your perspective as a user is that you should no longer have to worry about manually toggling TLS on or off (for gemini it’s always on), and you should never have to manually set a character coding scheme.

The gemini protocol specification recommends a Trust on First Use (TOFU) behaviour when validating gemini server TLS certificates. This is because many gemini servers rely on self-signed certificates rather than certificates signed by a CA. Sadly however, this TOFU behaviour is far from straight-forward to configure using Emacs’ existing Network Security Manager. For this reason, elpher defaults to performing no certificate verification by default. This behaviour can be easily customized by setting the elpher-gemini-TLS-cert-checks customization variable to non-nil.

The gemini specification concerns both the protocol and a simple text document format (mimetype text/gemini) which is like a mixture between gophermap files and markdown-formatted files but simpler than both. Elpher renders gemini responses which are provided in this format in line with the rules in the spec. This includes wrapping long lines at word boundaries. The specific column at which this text is wrapped is defined by the customization variable elpher-gemini-max-fill-width, which is set to 80 columns by default. (This is slightly wider than Emacs’ default fill width of 70 columns due to the fact that there are a significant amount of older gemini content which, against the advice of the current spec, hard wraps at <80 columns. The larger default allows this to still look okay, while still keeping content without hard wraps looking pleasant.)

The text/gemini format also possesses a section header syntax similar to markdown. Elpher allows different header levels to be drawn with different, customizable, faces. By default, on graphically-capable emacs systems, these faces are given different heights to distinguish among levels. On terminal systems, the level is indicated by the number of preceding # symbols.

I should emphasize however that, while it is definitely functional, Elpher’s gemini support is still experimental, and various aspects will change as the protocol develops further.


8.1 Client Certificates for Gemini

Gemini makes explicit use of the client certificate mechanism that TLS provides for allowing clients to authenticate themselves with servers. The Gemini specification suggests two distinct classes of client certificates: short-lived certificates used to identify you for a single session, and more permanent certificates used to identify you over a longer time period.

When Elpher receives a request for a client certificate from a server, it will present you with the option to create and use a single-use “throwaway” certificate, or to use a “persistent” certificate (optionally creating it or installing pre-existing key and certificate files).

Certificate creation in Elpher requires an installation of OpenSSL, and —in particular—that Elpher be able to run the openssl command-line utility. By default, Elpher assumes that the openssl is on the system path, but the precise location can be set by customizing the elpher-openssl-command variable.

Each generated certificate results in the creation of a .key file and a .crt file. In the case of a throwaway certificate, these files are stored in the temporary directory indicated by the Emacs variable temporary-file-directory and are deleted when “forgotten” (as described below).

In the case of persistent certificates, these files are stored in the folder defined by the Elpher variable elpher-certificate-directory, and are never deleted by Elpher. (Of course you can delete them yourself whenever you like.) The base name of the files (i.e. sans extension) is what Elpher uses to identify the certificate.

Using throwaway certificates is as simple as pressing the t key at the prompt which appears following a certificate request from a server. There is nothing more to do.

Using a persistent certificate requires instead selecting p from the same menu. This will result in Elpher asking you for the name identifying the certificate. This entry autocompletes to the list of known certificate names, so you can use TAB to display the list.

In the case that you choose a name that does not belong to the list of known certificates, Elpher will offer to create one for you or to “install” one from existing key and certificate files. Pressing the n key will cause Elpher to begin the process of creating a new persistent certificate, using some additional details for which you will be prompted. Alternatively, pressing the i key will cause Elpher to ask for the locations of existing key and certificate files to add to elpher-certificate-directory under the chosen name.

Once a certificate is selected, it will be used for all subsequent gemini requests involving URLs begining with the URL for for which the certificate was created. It is immediately “forgotten” when a TLS connection to a non-matching URL is attempted, or the following command is issued:

F (elpher-forget-certificate)

Causes Elpher to immediately forget any currently-loaded client certificate.

In either case, “forgetting” means that the details of the key and certificate file pair are erased from memory. Furthermore, in the case of throw-away certificates, the corresponding files are deleted.

Persistant client certificates can be added to the alist contained in the customization variable elpher-certificate-map so that they are automatically activated whenever a gemini page with the matching URL prefix is visited.


8.2 Hiding preformatted text in text/gemini documents

Preformatted text is often used to display “ASCII art” or other similar text-based artwork. While for many this is a fun way to introduce personality into their gemini documents, such text can pose difficulties for screen readers.

Setting the elpher-gemini-hide-preformatted customization option to non-nil causes Elpher to hide all preformatted text blocks by default. In place of the preformatted text, Elpher instead displays the “alt text” (if any is available), along with a button which can be used to make specific blocks visible as required.

Other related customization options are elpher-gemini-preformatted-toggle-label, which is the label used for the toggle button, and elpher-gemini-preformatted-toggle-bullet, which is the margin string used to distinguish the line replacing the preformatted text.


Next: , Previous: , Up: Elpher   [Contents][Index]

9 Finger support

Incidentally, Elpher has native support for querying finger servers. Of course, one could argue that this functionality is more easily provided by one’s local telnet client. However finger URLs do appear on occasion in gopherspace, and it’s nice to be able to open them in place.

Elpher interprets finger:// URLs as follows:

Thus finger://user@hostname and finger://hostname/user are both equivalent.

(The precedence of the /user notation over the user notation reflects a preference of the community.)


Next: , Previous: , Up: Elpher   [Contents][Index]

10 Local files

Elpher supports opening local files via ‘file:’ URLs.

For instance, pressing g and entering file:~/document.gmi will load the file named ‘document.gmi’ in your home directory, provided this file exists.

Files opened in this way are rendered according to their name, and in particular their extension. The current mappings are as follows:

txt

Plain text documents. All local text files are assumed to be UTF-8-encoded.

gophermap’,‘gopher

Gophermap files, i.e. files containing a valid directory list as specified by RFC 1436.

gemini’,‘gmi

Gemini documents (i.e. documents of MIME type “text/gemini”). All local gemini files are assumed to be UTF-8-encoded.

html’,‘htm

HTML documents. All local HTML files are assumed to be UTF-8-encoded.

png’,‘jpg’,‘jpeg’,‘gif’,‘bmp’,‘tif’,‘tiff

Image files.

Anything else

A binary document, which elpher will simply offer to save somewhere else. (Obviously this is not useful in its own right, but there’s not much that elpher can sensibly do with unknown binary files.)


Next: , Previous: , Up: Elpher   [Contents][Index]

11 About pages

Like other browsers, elpher makes certain internally-generated pages such as the initial welcome page, the bookmarks page, the history stack and the list of visited pages pages accessible as URLs with the “about:” type.

This means that these pages can be bookmarked and, more usefully, added to a local file to be rendered as a user-defined start page.

To see the address of a special page, simply visit the page and press I.


Next: , Previous: , Up: Elpher   [Contents][Index]

12 ANSI support

Depending on which parts of the gopher/gemini universe you frequent, you may occasionally stumble on sites which use ANSI escape codes to either produce specific characters or to colour text.

By default, elpher uses Emacs’ built-in ANSI rendering library, ‘ansi-color’, to process ANSI codes. This robustly interprets the escape codes but only supports 8 colours. Any colours unsupported by the library are simply stripped, leaving uncoloured text in the majority of cases.

To drastically improve the number of colours produced, install the ‘xterm-color’ package from MELPA. This package will be automatically used by elpher if it is available, and supports 256 colours. This should be sufficient to properly render many ANSI colour gopher holes and gemini capsules quite nicely.

In case you prefer to completely strip out the ANSI escape codes entirely by customizing the elpher-filter-ansi-from-text variable.


Next: , Previous: , Up: Elpher   [Contents][Index]

13 Customization

Various parts of Elpher can be customized via the variables belonging to the elpher customization group, accessible using

M-x customize-group elpher RET

This group contains a number of faces that can be modified to change the appearance of Elpher, including one face per menu item type.

The group also contains variables for customizing the behaviour of Elpher. This includes how to open arbitrary (non-gopher) URLs, whether to display buffer headers, how to deal with ANSI escape sequences in text, the timeout to impose on network connections, and whether to prompt for confirmation when switching away from TLS.

One particularly important customization is the elpher-start-page-url variable, which holds the URL of the page displayed initially when elpher starts, and when U is pressed. By default this is set to ‘about:welcome’, but any URL can be substituted. For example, you might want to create a text/gemini file named ‘~/.emacs/start-page.gmi’ containing useful links and set the value of elpher-start-page-url to ‘file:~/.emacs/start-page.gmi’ to have these links displayed at startup. Alternatively, you might prefer to set the value to ‘about:bookmarks’ so that the bookmarks page is used as the start page instead.

See the customization group itself for details.


Next: , Previous: , Up: Elpher   [Contents][Index]

Command Index

Jump to:   B   E  
Index Entry  Section

B
bookmark-bmenu-list: Bookmarks

E
elpher-back: Between-page navigation
elpher-bookmark-current: Bookmarks
elpher-bookmark-link: Bookmarks
elpher-copy-current-url: Within-page navigation
elpher-copy-link-url: Within-page navigation
elpher-download: Within-page navigation
elpher-download-current: Within-page navigation
elpher-follow-current-link: Between-page navigation
elpher-follow-current-link-new-buffer: Between-page navigation
elpher-forget-certificate: Client Certificates for Gemini
elpher-go: Between-page navigation
elpher-go-current: Between-page navigation
elpher-info-current: Within-page navigation
elpher-info-link: Within-page navigation
elpher-jump: Within-page navigation
elpher-next-link: Within-page navigation
elpher-open-bookmarks: Bookmarks
elpher-prev-link: Within-page navigation
elpher-root-dir: Between-page navigation
elpher-set-coding-system: Gopher character encodings
elpher-show-history: History and Caching
elpher-show-visited-pages: History and Caching
elpher-view-raw: Within-page navigation

Jump to:   B   E  

Next: , Previous: , Up: Elpher   [Contents][Index]

14 News

This chapter documents the major changes introduced by Elpher releases.


Next: , Previous: , Up: News   [Contents][Index]

14.1 v3.6.0

Next: , Previous: , Up: News   [Contents][Index]

14.2 v3.5.0

14.2.1 Automatic activation of client certificates in gemini

This version introduces a new customization variable elpher-certificate-map which allows you to pre-specify a set of gemini URLs and the client certificates which should be used when accessing them.

See Client Certificates for Gemini for more details.


Next: , Previous: , Up: News   [Contents][Index]

14.3 v3.4.0

14.3.1 Toggling preformatted text visibility

This version introduces the ability to hide preformatted text in text/gemini documents by default. To enable this, set the customization variable elpher-gemini-hide-preformatted to non-nil. This causes all preformated text blocks to be replaced with their “alt-text” (if any is available) and a button for toggling the visibility of the text block.

This feature is intended to make it easier for people using screen readers to read text/gemini documents.


Next: , Previous: , Up: News   [Contents][Index]

14.4 v3.3.0

This version includes lots of bug fixes, as well as a couple of new features.

14.4.1 Local gophermaps

Local gophermaps can now be displayed using ‘file:’. To render correctly, they must have the suffix ‘.gopher’ or ‘.gophermap’.

14.4.2 IRI support

Internationalized Resource Identifiers (IRI) are an extension of URLs (or, more accurately, URIs) to support a larger set of characters beyond those in the US-ASCII character set. They map directly onto URIs for backwards compatibility, but look like gibberish if not properly decoded. When displaying URLs, Elpher now automatically decodes any IRI characters and displays the decoded IRI. (For security reasons, the elpher-info-current command (I) always displays both the decoded IRI and the URI when they differ.)


Next: , Previous: , Up: News   [Contents][Index]

14.5 v3.2.0

This version introduces several minor changes which, together, make it possible to set up alternative start pages configured to your liking.

14.5.1 About pages

Special elpher pages such as the welcome page (previously “start” page), the bookmarks page, the browsing history stack and list of visited pages are now addressable via ‘about:’ URLs. For instance, the standard welcome page has the address ‘about:welcome’.

14.5.2 Local files

Local files can now be opened in elpher using ‘file:’ URLs. For example, g ‘file:~/my-start.gmi will open ‘~/my-start.gmi’ as a text/gemini document. see Local files for details.

14.5.3 Customizable start pages

The new customization variable elpher-start-page-url contains the URL of the document to be loaded as elpher’s “start page”. By default this is set to ‘about:welcome’, but any elpher-accessible URL is valid. see Customization for suggestions.


Next: , Previous: , Up: News   [Contents][Index]

14.6 v3.1.0

14.6.1 Bookmarks system

While Elpher bookmarks are still handled by the Emacs bookmark system, this release introduces the option to retain the original elpher bookmark page for the purpose of visiting those bookmarks. In v3.1.0, B visits this page (and adds it to the history stack, as in previous versions), which can be interacted with using the standard elpher key bindings.

Of course you can still view the bookmarks in the Emacs bookmark menu, which you can access from anywhere using the default binding C-x r l (or by following the link from the Elpher bookmarks page). Indeed you will need to use this to rename, delete or otherwise edit your bookmarks.

If you prefer to avoid using the Elpher bookmark page entirely, you use the customization variable elpher-use-emacs-bookmark-menu to have the B key open the Emacs bookmark menu directly, as in the previous release.


Previous: , Up: News   [Contents][Index]

14.7 v3.0.0

14.7.1 Bookmarks system

Bookmarks are now handled by Emacs’ own bookmark management system, instead of Elpher’s own system. (For details, See Bookmarks in The Emacs Editor.) This means two things. Firstly, the bookmarks file (elpher-bookmarks by default) and format used by previous versions are now deprecated. If these are detected, Elpher will offer to import your old bookmarks when you first accessing the bookmark list with the new version. A suffix will be added to your old bookmarks file so that Elpher knows that the import is complete.

Secondly, the old Elpher bookmark menu has been removed in the new version. Instead, B brings up the menu provided by the Emacs function bookmark-bmenu-list. This has different key and mouse bindings to Elpher’s old menu, but is much more functional. Bookmarks can be renamed, deleted in groups, and much more. (Use C-h m with the menu open to see the complete list.)

14.7.2 History

Browsing history can now be accessed via new bindings to s and S. The former shows the current history “stack” (pages accessible with the u key), while the latter shows a list of all pages which have been visited in the current session.

14.7.3 Socks connections

Elpher can now use socks connections to browse via TOR.

14.7.4 browse-url, Org and mu4e integration

These integrations provide support for elpher-handling of gemini, gopher and finger URLs using browse-url, in Org documents, and the mu4e mail system.

14.7.5 imenu integration

Gemini document headers are now navigable via imenu. For details, See Imenu in The Emacs Editor.


Previous: , Up: Elpher   [Contents][Index]

15 Contributors

Elpher was originally written and is currently maintained by Tim Vaughan plugd@thelambdalab.xyz. Significant improvements and maintenance have also been contributed by and with the help of Alex Schroeder alex@gnu.org. In addition, the following people have all generously provided assistance and/or patches:


Footnotes

(1)

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 or gemini page 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.