1 \input texinfo @c -*-texinfo-*-
3 @setfilename elpher.info
4 @settitle Elpher Manual v2.0.0
8 * Elpher: (elpher). A gopher client for Emacs.
12 This manual documents Elpher, a gopher client for Emacs.
14 Copyright @copyright{} 2019 Tim Vaughan
17 The source and documentation of Elpher is free software. You can
18 redistribute it and/or modify it under the terms of the GNU General
19 Public License as published by the Free Software Foundation; either
20 version 3, or (at your option) any later version.
22 Elpher is distributed in the hope that it will be useful, but WITHOUT
23 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
24 FITNElpher FOR A PARTICULAR PURPOSE. See the GNU General Public License in
25 the file COPYING in the same directory as this file for more details.
30 @title Elpher Gopher Client Manual
34 @vskip 0pt plus 1filll
41 @node Top, Introduction, (dir), (dir)
47 @macro keycmd{key,cmd}
48 @item \key\ (@code{\cmd\})
53 * Introduction:: Elpher Overview: what's this all about?
54 * Installation:: Installing Elpher
55 * Quick Start:: Get up and running quickly
56 * Navigation:: Fundamentals of Elpher navigation
57 * Bookmarks:: How to record and visit bookmarks
58 * Character encodings:: How Elpher handles different character encodings
59 * Encrypted connections:: How and when TLS is enabled
60 * Gemini support:: Support for the Gemini protocol
61 * Customization:: How to customize various aspects of Elpher
65 --- The Detailed Node Listing ---
69 * Within-page navigation:: Moving about within a page
70 * Between-page navigation:: Commands for moving between pages
71 * History and Caching:: Explanation of how Elpher represents history
76 @node Introduction, Installation, Top, Top
79 Elpher aims to be a capable and practical gopher client for Emacs. Its
80 focus is on easy keyboard-driven navigation based on sensible default
81 bindings (with out-of-the-box support for Evil). It is intended to be
82 robust and behave in non-surprising ways at all times. Additionally,
83 Elpher provides the following bells and whistles:
87 followable web and gopher links in plain text,
90 an easily navigable history, sporting caching of visited pages (both
91 content and cursor position),
94 auto-completing menu item navigation,
97 direct visualization of image files where supported (no writing to
101 a bookmark management system,
104 basic support for the new ``heavier than gopher, lighter than the web'' Gemini protocol.
108 Elpher is still under active development. Although we try very hard to
109 ensure that releases are bug-free, this cannot be guaranteed. However,
110 this also means that any usability features that you feel are missing
111 can likely by incorporated quickly, so please get in touch if you
114 @node Installation, Quick Start, Introduction, Top
115 @chapter Installation
117 Elpher is available from the MELPA package repository. If you have
118 never installed packages from this repository before, you'll need
119 to follow the instructions at @url{https://melpa.org/#/getting-started}.
121 @noindent To install Elpher, enter the following:
124 @kbd{M-x package-install @key{RET} elpher @key{RET}}
127 @noindent To uninstall, use
130 @kbd{M-x package-delete @key{RET} elpher @key{RET}}.
133 While not recommended, it is also possible to install Elpher directly by
134 downloading the file @file{elpher.el} from
135 @url{https://github.com/tgvaughan/elpher}, adding it to a directory in
136 your @code{load-path}, and then adding
142 @noindent to your Emacs initialization file.
144 @node Quick Start, Navigation, Installation, Top
147 Before diving into the minutiae of the different commands available,
148 we will quickly describe how to get up and running with Elpher.
150 Once installed, you can launch Elpher using
153 @kbd{M-x elpher @key{RET}}
156 @noindent This will switch to the *Elpher* buffer and display a start
157 page, with information on each of the default keyboard bindings.
159 From here you can move point between links (which may be menu items or
160 inline URLs in text files) by using @key{TAB} and @kbd{S-@key{TAB}},
161 as in Info. You can also jump directly to a menu item using @key{m}, or
162 use the standard Emacs or Evil motion and search commands to find your
163 way around. To open a link, press @key{RET}. (Where a mouse is
164 available, Clicking on a link with the mouse cursor has the same
167 To return to the page you just followed the link from, press @key{u}.
169 Elpher caches (for the duration of an Emacs session) both page contents
170 and the position of point on each of the pages (gopher menus, query
171 results, or text pages) you visit, restoring these when you next visit
172 the same page. Thus, pressing @key{u} displays the previous page in
173 exactly the same state as when you left, meaning that you can quickly
174 and visually explore the different documents in a menu without having to
175 wait for anything to reload.
177 Of course, sometimes you'll @emph{want} to reload the current page
178 rather than stick with the cached version. To do this use @key{R}.
179 (This is particularly useful for search query results, where this
180 allows you to perform a different search.)
182 That's more-or-less it. Elpher supports a number of other features, such
183 as bookmarking, support for different coding schemes and TLS encryption,
184 and a variety of customization options, all of which are explained in
185 the rest of this document. However the emphasis is on keeping the basic
186 navigation experience as intuitive and responsive as possible.
188 @node Navigation, Bookmarks, Quick Start, Top
191 Throughout this manual, we use the word ``page'' to refer to any
192 visualization of a response from a gopher server, be it a
193 menu/directory, query result, text file or image. We use
195 Elpher's navigation interface is inspired by the Emacs Info mode.
196 Movement within a page is essentially the same as moving
197 around any other text file in Emacs, but with special keys
198 for quickly jumping between menu items and URLs in text files.
199 Movement between pages is facilitated by a simple linear history
200 coupled with caching of pages and cursor position.
203 * Within-page navigation:: Moving about within a page
204 * Between-page navigation:: Commands for moving between pages
205 * History and Caching:: Explanation of how Elpher represents history
209 @node Within-page navigation, Between-page navigation, Navigation, Navigation
210 @section Within-page navigation
212 To move about within a page, you should be able use the same keys you usually
213 use to browse files in Emacs. This is even true when Evil mode is
214 enabled. Paragraph hopping, searching etc should work as usual.
216 In addition, the following commands are provided for quickly moving between
217 links and menu items.
220 @keycmd{@key{TAB}, elpher-next-link}
221 Move to the next link or menu item in the file.
223 @keycmd{@kbd{Shift-@key{TAB}}/@key{backtab}, @code{elpher-prev-link}}
224 Move to the previous link or menu item in the file.
226 @keycmd{@key{m}, elpher-jump}
227 Jump directly to a link within a file by specifying its display string
228 or link text. (Unlike the previous two commands, this immediately opens
232 The following commands can be used to retrieve information about the
233 current page, or the address of the link at point:
236 @keycmd{@key{i}, elpher-info-link}
237 Display host, port and selector information for the link at point.
239 @keycmd{@key{I}, elpher-info-current}
240 Display host, port and selector information for the current page.
242 @keycmd{@key{c}, elpher-copy-link-url}
243 Add URL representing address of link at point to the kill-ring and the
244 system clipboard (if available).
246 @keycmd{@key{C}, elpher-copy-current-url}
247 Add URL representing address of the current page to the kill-ring and
248 the system clipboard (if available).
250 @keycmd{@key{d}, elpher-download}
251 Download link at point and save the result as a file. The minibuffer
252 will prompt for the name of the file to write, with the default name being
253 the display string (if available) associated with the link.
255 @keycmd{@key{D}, elpher-download-current}
256 This is similar to @code{elpher-download}, but instead applies to the
257 current page rather than a link.
259 @keycmd{@key{.}, elpher-view-raw}
260 This displays the raw server response for the current page. While not
261 useful for general browsing, it is useful for debugging incorrect rendering
262 or out-of-spec server responses.
265 @node Between-page navigation, History and Caching, Within-page navigation, Navigation
266 @section Between-page navigation
268 Moving to a different page can be accomplished in several ways,
269 described by the following command:
272 @keycmd{@key{RET}\, @kbd{mouse-1}, elpher-follow-link}
273 Follow the menu item or link at point (or selected with the mouse).
275 Exactly what is meant by ``follow'' depends on the kind of item selected:
279 For text or menu type items or links, the current page text is replaced
280 by the text of this item. Unless the customization variable
281 @code{elpher-use-header} (@pxref{Customization}) is
282 @code{nil}, the display string of the link is displayed in the buffer header.
283 Links to images behave similarly on Emacs systems supporting the display of
284 bitmap graphics, however their content is not cached in memory by default.
287 When followed, links to search/query items (type 7) prompt for input in
288 the minibuffer then display the results in the same way as for text and menu
292 Following links to binary files (and image files on unsupported systems)
293 causes Elpher to prompt for a filename in which to save the content.
296 Following links of type `h' with a selector having the `URL:' prefix, or
297 non-gopher URLs in text files, will result in Elpher using an external
298 programme to open the URL. This will be either the default system browser
299 or, if the @code{elpher-open-urls-with-eww} customization variable is non-nil,
300 Emacs' own EWW browser. (See @pxref{Customization}.)
304 Once a text, menu or query response page has been displayed, its contents are
305 cached for the duration of the Emacs session.
307 @keycmd{@key{g}, elpher-go}
308 Open a particular page by specifying either its full URL or just entering
311 If a non-gopher protocol is used in the URL the result will be the same
312 as following a URL link of the same type from a gopher menu.
314 @keycmd{@key{o}, elpher-go-current}
315 Prompts for a URL similar to @code{elpher-go}, but initialized to the URL
316 of the current page. This allows you to easily try other selectors for the
319 Remember however, that the Gopher RFC 1436 provides no guarantees about the
320 structure of selectors.
322 @keycmd{@key{O}, elpher-root-dir}
323 Open the root page (empty selector) on the current host.
325 @keycmd{@key{u}\, @kbd{mouse-3}, elpher-back}
326 Return to the previous page, where ``previous'' means the page where the
327 page which was displayed immediately before the current page.
331 @node History and Caching, , Between-page navigation, Navigation
332 @section History and Caching
334 The history and caching strategy in Elpher is extremely simple, but
335 may be confusing without a good mental model of how it works. That
336 is what this section attempts to provide.
338 Essentially, @strong{every} time you navigate to a new page, either
339 by clicking or pressing @key{RET} on a link, using @key{g} to jump
340 to a new page by its address, or using @key{O} to open the root selector,
341 the following two things occur:
345 the cursor position and content for the original page are recorded in an
349 the original page is set as the ``parent'' of the new page.
352 The only way to return to pages in this history is by using @key{u},
353 which returns to the previous of the current page.
354 @footnote{The addition of the new page to the history happens even if
355 the new page is one that has been seen before. This is mostly the
356 desired behaviour. However, opening an explicit ``back'' link provided
357 by a gopher menu will also add a new entry to the history. Unless you
358 haven't yet visited that menu, it's therefore better to use @key{u} to
359 go back in this case.}
361 One aspect that may seem peculiar is that Elpher lacks a corresponding ``next'' or
362 ``forward'' command. However, since Elpher caches the position of point,
363 this will be automatically positioned on the link that was most recently followed
364 from a given page. This means that, at least for links followed from menus
365 and text files, the inverse of @key{u} is actually just @key{RET}.
368 @node Bookmarks, Character encodings, Navigation, Top
371 Elpher has a very simple link bookmarking system involving the
375 @keycmd{@key{a}, elpher-bookmark-link}
376 Add a bookmark for the link at point. The minibuffer will prompt for
377 a name for the bookmark, which defaults to the display string.
379 @keycmd{@key{A}, elpher-bookmark-current}
380 Add a bookmark for the current page. The minibuffer will prompt for
381 a name for the bookmark, defaulting to the display string associated
382 with the link that was followed to reach the current page.
384 @keycmd{@key{x}, elpher-unbookmark-link}
385 Immediately remove the bookmark (if one exists) to the link at point.
387 @keycmd{@key{X}, elpher-unbookmark-current}
388 Immediately remove the bookmark (if one exists) to the current page.
390 @keycmd{@key{B}, elpher-bookmarks}
391 Open a page displaying all current bookmarks. Note that this bookmark
392 page is added to the history just as if you had opened it using a link.
393 Thus to return to the previous page, use @kbd{u}. This also means
394 that you can peruse the various bookmarks by visiting them in turn,
395 using @kbd{u} to return to the bookmark page (where the position of point
396 is cached), then moving to another bookmarked link and so on.
399 Bookmarks are stored as a s-exp in the file @file{elpher-bookmarks}
400 in the user emacs directory (usually @file{~/.emacs.d/}).
401 Any command which modifies the list of bookmarks immediately updates
404 @node Character encodings, Encrypted connections, Bookmarks, Top
405 @chapter Character encodings
407 Responses Elpher retrieves from servers are initially read as pure
408 binary data. When the data is intended to be interpreted as textual (as
409 determined by the type parameter of the gopher menu item or the gopher
410 URL), this data needs to be @emph{decoded} into a sequence of
411 characters. To do this properly requires knowledge of the encoding
412 system used by whoever authored the document.
414 Unfortunately gopher lacks a systematic way of acquiring this necessary
415 information. Thus, the details of the coding system must be either inferred from the binary data,
416 or must be specified by the user.
418 By default, Elpher applies Emacs' built-in character encoding detection
419 system to the full (undecoded) response data and uses this to attempt to
420 convert it into a character string.
421 (See @pxref{Recognize coding, Recognizing coding systems, ,emacs}.) While
422 this approach can be okay, it is important to realize that its inference
423 algorithm is extremely primitive and depends heavily on assumptions based
424 on the language settings of your emacs system.
426 The alternative is to explicitly set the coding system used for decoding
427 using the following command:
430 @keycmd{@key{S},elpher-set-coding-system}
431 Causes a elpher to prompt for a coding system to use for decoding
432 future text. The @key{TAB} key can be used at this prompt to display a
433 list of alternatives (which is extensive) and to auto-complete. An empty
434 response will cause Elpher to return to its default auto-detection
438 Note that changing the coding system only affects newly loaded text.
439 Thus, if text has already been decoded using an incorrect system, you
440 will need to select the correct coding and then reload the text using
444 @node Encrypted connections, Gemini support, Character encodings, Top
445 @chapter Encrypted connections
447 While RFC 1436 does not broach the topic of encryption at all, several
448 modern gopher servers can serve content over encrypted connections,
449 and a common choice for this is TLS.
451 Elpher can retrieve selectors using Emacs' built-in TLS support which
452 uses the GnuTLS library. (It is possible to build emacs without
453 GnuTLS, in which case encryption is not supported.)
455 To retrieve documents using TLS, Elpher's TLS mode must be enabled.
456 This can be directly toggled using @key{T}, but note that just as with
457 the character encoding, changing this mode only affects subsequent
460 Alternatively, TLS mode is @emph{automatically} enabled whenever
461 gopher URLs starting with @code{gophers://} are followed.
463 The mode is sticky, so it remains active until switched off.
464 It can also be automatically switched off when a TLS connection fails.
465 In this case Elpher will prompt for your confirmation to ensure that
466 you can't accidentally make a non-TLS connection.
468 @node Gemini support, Customization, Encrypted connections, Top
469 @chapter Gemini support
471 @uref{gopher://zaibatsu.circumlunar.space/1/~solderpunk/gemini, Gemini}
472 is a new protocol being devloped by several members of
473 gopherspace. It aims to solve some of the long-standing technical
474 issues associated with gopher as a protocol, while keeping the major benifits.
475 For instance, it _requires_ encrypted connections, it does away with
476 the selector type, and allows servers to explicitly specify the
477 character coding scheme used for text documents.
479 The latest versions of Elpher aim to provide seemless navigation between
480 gemini and gopher documents. Basically you should be able to open,
481 bookmark, download and otherwise interact with gemini pages in exactly
482 the same way as you do with other non-gemini pages. The only major
483 difference from your perspective as a user is that you should no longer
484 have to worry about manually toggling TLS on or off (for gemini it's
485 always on), and you should never have to manually set a character coding
488 I should emphasize however that, while it is definitely functional,
489 Elpher's gemini support is still experimental, and various aspects will
490 change as the protocol develops further. Additionally, the use of
491 client TLS certicificates is not yet supported.
493 @node Customization, Command Index, Gemini support, Top
494 @chapter Customization
496 Various parts of Elpher can be customized via the
497 variables belonging to the elpher customization group, accessible
501 @kbd{M-x customize-group elpher @key{RET}}
504 @noindent This group contains a number of faces that can be modified to change
505 the appearance of Elpher, including one face per menu item type.
507 The group also contains variables for customizing the behaviour of
508 Elpher. This includes how to open arbitrary (non-gopher) URLs,
509 whether to display buffer headers, whether to look for naked URLs in
510 gopher menus (as opposed to just plain text files), and whether
511 to prompt for confirmation when switching away from TLS.
513 See the customization group itself for details.
515 @node Command Index, , Customization, Top
516 @unnumbered Command Index