Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
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.
Next: Installation, Previous: Elpher, Up: Elpher [Contents][Index]
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: Quick Start, Previous: Introduction, Up: Elpher [Contents][Index]
Next: Installing by hand, Previous: Installation, Up: Installation [Contents][Index]
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.
Previous: Installing from ELPA or MELPA, Up: Installation [Contents][Index]
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: Navigation, Previous: Installation, Up: Elpher [Contents][Index]
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
Next: Gopher character encodings, Previous: Navigation, Up: Elpher [Contents][Index]
Elpher makes use of standard Emacs bookmarks. See Bookmarks in The Emacs Editor. The following commands are used to add new bookmarks:
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.
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.
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).
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.
Next: Encrypted gopher connections, Previous: Bookmarks, Up: Elpher [Contents][Index]
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.
Next: Gemini support, Previous: Gopher character encodings, Up: Elpher [Contents][Index]
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.
Next: Finger support, Previous: Encrypted gopher connections, Up: Elpher [Contents][Index]
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.
Next: Hiding preformatted text in text/gemini documents, Previous: Gemini support, Up: Gemini support [Contents][Index]
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:
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.
Previous: Client Certificates for Gemini, Up: Gemini support [Contents][Index]
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: Local files, Previous: Gemini support, Up: Elpher [Contents][Index]
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: About pages, Previous: Finger support, Up: Elpher [Contents][Index]
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:
Plain text documents. All local text files are assumed to be UTF-8-encoded.
Gophermap files, i.e. files containing a valid directory list as specified by RFC 1436.
Gemini documents (i.e. documents of MIME type “text/gemini”). All local gemini files are assumed to be UTF-8-encoded.
HTML documents. All local HTML files are assumed to be UTF-8-encoded.
Image files.
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: ANSI support, Previous: Local files, Up: Elpher [Contents][Index]
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: Customization, Previous: About pages, Up: Elpher [Contents][Index]
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: Command Index, Previous: ANSI support, Up: Elpher [Contents][Index]
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: News, Previous: Customization, Up: Elpher [Contents][Index]
| Jump to: | B E |
|---|
| Jump to: | B E |
|---|
Next: Contributors, Previous: Command Index, Up: Elpher [Contents][Index]
This chapter documents the major changes introduced by Elpher releases.
This version includes the ability to open all link types in
Elpher documents in a new buffer. By default, this is bound
to S-RET and S-mouse-1, but this can be modified
by adding adjusting the bindings in elpher-link-keymap.
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.
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.
This version includes lots of bug fixes, as well as a couple of new features.
Local gophermaps can now be displayed using ‘file:’. To render correctly, they must have the suffix ‘.gopher’ or ‘.gophermap’.
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.)
This version introduces several minor changes which, together, make it possible to set up alternative start pages configured to your liking.
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’.
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.
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.
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.
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.)
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.
Elpher can now use socks connections to browse via TOR.
These integrations provide support for elpher-handling of gemini, gopher
and finger URLs using browse-url, in Org documents, and the mu4e
mail system.
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:
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.