1 \input texinfo @c -*-texinfo-*-
3 @setfilename elpher.info
4 @settitle Elpher Manual v1.0.0
8 This manual documents Elpher, a gopher client for Emacs.
10 Copyright @copyright{} 2019 Tim Vaughan
13 The source and documentation of Elpher is free software. You can
14 redistribute it and/or modify it under the terms of the GNU General
15 Public License as published by the Free Software Foundation; either
16 version 3, or (at your option) any later version.
18 Elpher is distributed in the hope that it will be useful, but WITHOUT
19 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
20 FITNElpher FOR A PARTICULAR PURPOSE. See the GNU General Public License in
21 the file COPYING in the same directory as this file for more details.
26 @title Elpher Gopher Client Manual
30 @vskip 0pt plus 1filll
37 @node Top, Introduction, (dir), (dir)
44 * Introduction:: Elpher Overview: what's this all about?
45 * Installation:: Installing Elpher
46 * Quick Start:: Get up and running quickly
47 * Navigation:: Fundamentals of Elpher navigation
48 * Bookmarks:: How to record and visit bookmarks
49 * Character encodings:: How Elpher handles different character encodings
50 * Encrypted connections:: How and when TLS is enabled
51 * Customization:: How to customize various aspects of Elpher
55 @node Introduction, Installation, Top, Top
58 Elpher aims to be a capable and practical gopher client for Emacs. Its
59 focus is on easy keyboard-driven navigation based on sensible default
60 bindings (with out-of-the-box support for Evil). It is intended to be
61 robust and behave in non-surprising ways at all times. Additionally,
62 Elpher provides the following bells and whistles:
66 an easily navigable history, sporting caching of visited pages (both
67 content and cursor position),
70 auto-completing menu item navigation,
73 followable web and gopher links in plain text,
76 direct visualization of image files where supported (no writing to
80 a simple bookmark management system.
83 Elpher is still under active development. Although we try very hard to
84 ensure that releases are bug-free, this cannot be guaranteed. However,
85 this also means that any usability features that you feel are missing
86 can likely by incoroporated quickly, so please get in touch if you
89 @node Installation, Quick Start, Introduction, Top
92 Elpher is available from the MELPA package repository. If you have
93 never installed packages from this repository before, you'll need
94 to follow the instructions at @url{https://melpa.org/#/getting-started}.
96 @noindent To install Elpher, enter the following:
99 @kbd{M-x package-install @key{RET} elpher @key{RET}}
102 @noindent To uninstall, use
105 @kbd{M-x package-delete @key{RET} elpher @key{RET}}.
108 While not recommended, it is also possible to install Elpher directly by
109 downloading the file @file{elpher.el} from
110 @url{https://github.com/tgvaughan/elpher}, adding it to a directory in
111 your @code{load-path}, and then adding
117 @noindent to your Emacs initialization file.
119 @node Quick Start, Navigation, Installation, Top
122 Before diving into the minutiae of the different commands available,
123 we will quickly describe how to get up and running with Elpher.
125 Once installed, you can launch Elpher using
128 @kbd{M-x elpher @key{RET}}
131 @noindent This will switch to the *Elpher* buffer and display a start
132 page, with information on each of the default keyboard bindings.
134 From here you can move point between links (which may be menu items or
135 inline URLs in text files) by using @key{TAB} and @kbd{S-@key{TAB}},
136 as in Info. You can also jump directly to a menu item using @key{m}, or
137 use the standard Emacs or Evil motion and search commands to find your
138 way around. To open a link, press @key{RET}. (Where a mouse is
139 available, Clicking on a link with the mouse cursor has the same
142 To return to the page you just followed the link from, press @key{u}.
144 Elpher caches (for the duration of an Emacs session) both page contents
145 and the position of point on each of the pages (gopher menus, query
146 results, or text pages) you visit, restoring these when you next visit
147 the same page. Thus, pressing @key{u} displays the previous page in
148 exactly the same state as when you left, meaning that you can quickly
149 and visually explore the different documents in a menu without having to
150 wait for anything to reload.
152 Of course, sometimes you'll @emph{want} to reload the current page
153 rather than stick with the cached version. To do this use @key{R}.
154 (This is particularly useful for search query results, where this
155 allows you to perform a different search.)
157 That's more-or-less it. Elpher supports a number of other features, such
158 as bookmarking, support for different coding schemes and TLS encryption,
159 and a variety of customization options, all of which are explained in
160 the rest of this document. However the emphasis is on keeping the basic
161 navigation experience as intuitive and responsive as possible.
163 @node Navigation, Bookmarks, Quick Start, Top
166 Throughout this manual, we use the word ``page'' to refer to any
167 visualization of a response from a gopher server, be it a
168 menu/directory, query result, text file or image. We use
170 Elpher's navigation interface is inspired by the Emacs Info mode.
171 Movement within a page is essentially the same as moving
172 around any other text file in Emacs, but with special keys
173 for quickly jumping between menu items and URLs in text files.
174 Movement between pages is facilitated by a simple linear history
175 coupled with caching of pages and cursor position.
178 * Within-page navigation:: Moving about within a page
179 * Between-page navigation:: Commands for moving between pages
180 * History and Caching:: Explanation of how Elpher represents history
184 @node Within-page navigation, Between-page navigation, Navigation, Navigation
185 @section Within-page navigation
187 To move about within a page, you should be able use the same keys you usually
188 use to browse files in Emacs. This is even true when Evil mode is
189 enabled. Paragraph hopping, searching etc should work as usual.
191 In addition, the following commands are provided for quickly moving between
192 links and menu items.
195 @item @key{TAB} (@code{elpher-next-link})
196 Move to the next link or menu item in the file.
198 @item @kbd{Shift-@key{TAB}}/@key{backtab} (@code{elpher-prev-link})
199 Move to the previous link or menu item in the file.
201 @item @kbd{m} (@code{elpher-jump})
202 Jump directly to a link within a file by specifying its display string
203 or link text. (Unlike the previous two commands, this immediately opens
207 The following commands can be used to retrieve information about the
208 current page, or the address of the link at point:
211 @item @kbd{i} (@code{elpher-info-link})
212 Display host, port and selector information for the link at point.
214 @item @kbd{I} (@code{elpher-info-current})
215 Display host, port and selector information for the current page.
217 @item @kbd{c} (@code{elpher-copy-link-url})
218 Add URL representing address of link at point to the kill-ring and the
219 system clipboard (if available).
221 @item @kbd{C} (@code{elpher-copy-current-url})
222 Add URL representing address of the current page to the kill-ring and
223 the system clipboard (if available).
225 @item @kbd{d} (@code{elpher-download})
226 Download link at point and save the result as a file. The minibuffer
227 will prompt for the name of the file to write, with the default name being
228 the display string (if available) associated with the link.
230 @item @kbd{D} (@code{elpher-download-current})
231 This is similar to @code{elpher-downlowd}, but instead applies to the
232 current page rather than a link.
234 @item @kbd{w} (@code{elpher-view-raw})
235 This displays the raw server response for the current page. While not
236 useful for general browsing, it is useful for debugging incorrect rendering
237 or out-of-spec server responses.
240 @node Between-page navigation, History and Caching, Within-page navigation, Navigation
241 @section Between-page navigation
243 Moving to a different page can be accomplished in several ways,
244 described by the following command:
247 @item @kbd{RET}, @kbd{mouse-1} (@code{elpher-follow-link})
248 Follow the menu item or link at point (or selected with the mouse).
250 Exactly what is meant by ``follow'' depends on the kind of item selected:
254 For text or menu type items or links, the curent page text is replaced
255 by the text of this item. Unless the customization variable
256 @code{elpher-use-header} (@pxref{Customization}) is
257 @code{nil}, the display string of the link is displayed in the buffer header.
258 Links to images behave similarly on Emacs systems supporting the display of
259 bitmap graphics, however their content is not cached in memory by default.
262 When followed, links to search/query items (type 7) prompt for input in
263 the minibuffer then display the results in the same way as for text and menu
267 Following links to binary files (and image files on unsupported systems)
268 causes Elpher to prompt for a filename in which to save the content.
271 Following links of type `h' with a selector having the `URL:' prefix, or
272 non-gopher URLs in text files, will result in Elpher using an external
273 programme to open the URL. This will be either the default system browser
274 or, if the @code{elpher-open-urls-with-eww} customization variable is non-nil,
275 Emacs' own EWW browser. (See @pxref{Customization}.)
279 Once a text, menu or query response page has been displayed, its contents are
280 cached for the duration of the Emacs session.
282 @item @kbd{g} (@code{elpher-go})
283 Open a particular page by specifying either its URL or directly entering
284 a host, port and selector.
286 Note that if a non-gopher protocol is used in the URL the result will be
287 the same as following a URL link of the same type from a gopher menu.
289 @item @kbd{O} (@code{elpher-root-dir})
290 Open the root page (empty selector) on the current host.
292 @item @kbd{u} (@code{elpher-back})
293 Return to the previous page, where ``previous'' means the page where the
294 page which was displayed immediately before the current page.
298 @node History and Caching, , Between-page navigation, Navigation
299 @section History and Caching
301 The history and caching strategy in Elpher is extremely simple, but
302 may be confusing without a good mental model of how it works. That
303 is what this section attempts to provide.
305 Essentially, @strong{every} time you navigate to a new page, either
306 by clicking or pressing @key{RET} on a link, using @key{g} to jump
307 to a new page by its address, or using @key{O} to open the root selector,
308 the following two things occur:
312 the cursor position and content for the original page are recorded in an
316 the original page is set as the ``parent'' of the new page.
319 The only way to return to pages in this history is by using @key{u},
320 which returns to the previous of the current page.
321 @footnote{The addition of the new page to the history happens even if
322 the new page is one that has been seen before. This is mostly the
323 desired behaviour. However, opening an explicit ``back'' link provided
324 by a gopher menu will also add a new entry to the history. Unless you
325 haven't yet visited that menu, it's therefore better to use @key{u} to
326 go back in this case.}
328 One aspect that may seem peculiar is that Elpher lacks a corresponding ``next'' or
329 ``forward'' command. However, since Elpher caches the position of point,
330 this will be automatically positioned on the link that was most recently followed
331 from a given page. This means that, at least for links followed from menus
332 and text files, the inverse of @key{u} is actually just @key{RET}.
335 @node Bookmarks, Character encodings, Navigation, Top
338 Elpher has a very simple link bookmarking system involving the
342 @item @key{a} (@code{elpher-bookmark-link})
343 Add a bookmark for the link at point. The minibuffer will prompt for
344 a name for the bookmark, which defaults to the display string.
346 @item @key{A} (@code{elpher-bookmark-current})
347 Add a bookmark for the current page. The minibuffer will prompt for
348 a name for the bookmark, defaulting to the display string associated
349 with the link that was followed to reach the current page.
351 @item @key{x} (@code{elpher-unbookmark-link})
352 Immediately remove the bookmark (if one exists) to the link at point.
354 @item @key{X} (@code{elpher-unbookmark-current})
355 Immediately remove the bookmark (if one exists) to the current page.
357 @item @key{B} (@code{elpher-bookmarks})
358 Open a page displaying all current bookmarks. Note that this bookmark
359 page is added to the history just as if you had opened it using a link.
360 Thus to return to the previous page, use @kbd{u}. This also means
361 that you can peruse the various bookmarks by visiting them in turn,
362 using @kbd{u} to return to the bookmark page (where the position of point
363 is cached), then moving to another bookmarked link and so on.
366 Bookmarks are stored as a s-exp in the file @file{elpher-bookmarks}
367 in the user emacs directory (usually @file{~/.emacs.d/}).
368 Any command which modifies the list of bookmarks immediately updates
371 @node Character encodings, Encrypted connections, Bookmarks, Top
372 @chapter Character encodings
374 Responses Elpher retrieves from servers are initially read as pure
375 binary data. When the data is intended to be interpreted as textual (as
376 determined by the type parameter of the gopher menu item or the gopher
377 URL), this data needs to be @emph{decoded} into a sequence of
378 characters. To do this properly requires knowledge of the encoding
379 system used by whoever authored the document.
381 Unfortunately gopher lacks a systematic way of acquiring this necessary
382 information. Thus, the details of the coding system must be either inferred from the binary data,
383 or must be specified by the user.
385 By default, Elpher applies Emacs' built-in character encoding detection
386 system to the full (undecoded) response data and uses this to attempt to
387 convert it into a character string.
388 (See @pxref{Recognize coding, Recognizing coding systems, ,emacs}.) While
389 this approach can be okay, it is important to realise that its inference
390 algorithm is extremely primitive and depends heavily on assumptions based
391 on the language settings of your emacs system.
393 The alternative is to explicitly set the coding system used for decoding
394 using the following command:
397 @item @key{S} (@code{elpher-set-coding-system})
398 Causes a elpher to prompt for a coding system to use for decoding
399 future text. The @key{TAB} key can be used at this prompt to display a
400 list of alternatives (which is extensive) and to autocomplete. An empty
401 response will cause Elpher to return to its default autodetection
405 Note that changing the coding system only affects newly loaded text.
406 Thus, if text has already been decoded using an incorrect system, you
407 will need to select the correct coding and then reload the text using
411 @node Encrypted connections, Customization, Character encodings, Top
412 @chapter Encrypted connections
414 While RFC 1436 does not broach the topic of encryption at all, several
415 modern gopher servers can serve content over encrypted connections,
416 and a common choice for this is TLS.
418 Elpher can retrieve selectors using Emacs' built-in TLS support which
419 uses the GnuTLS library. (It is possible to build emacs without
420 GnuTLS, in which case encryption is not supported.)
422 To retrieve documents using TLS, Elpher's TLS mode must be enabled.
423 This can be directly toggled using @key{T}, but note that just as with
424 the character encoding, changing this mode only affects subsequent
427 Alternatively, TLS mode is @emph{automatically} enabled whenever
428 gopher URLs starting with @code{gophers://} are followed.
430 The mode is sticky, so it remains active until switched off.
431 It can also be automatically switched off when a TLS connection fails.
432 In this case Elpher will prompt for your confirmation to ensure that
433 you can't accidentally make a non-TLS connection.
436 @node Customization, Index, Encrypted connections, Top
437 @chapter Customization
444 * Other cutomizations::
447 @node Faces, Other cutomizations, Customization, Customization
450 @node Other cutomizations, , Faces, Customization
451 @section Other customizations
453 @node Index, , Customization, Top