1 \input texinfo @c -*-texinfo-*-
3 @setfilename elpher.info
4 @settitle Elpher Manual v3.3.0
8 * Elpher: (elpher). A gopher and gemini client for Emacs.
12 This manual documents Elpher, a gopher and gemini client for Emacs.
14 Copyright @copyright{} 2019-2022 Tim Vaughan@*
15 Copyright @copyright{} 2021 Daniel Semyonov@*
16 Copyright @copyright{} 2021 Alex Schroeder
19 The source and documentation of Elpher is free software. You can
20 redistribute it and/or modify it under the terms of the GNU General
21 Public License as published by the Free Software Foundation; either
22 version 3, or (at your option) any later version.
24 Elpher is distributed in the hope that it will be useful, but WITHOUT
25 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
26 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License in
27 the file COPYING in the same directory as this file for more details.
32 @title Elpher Gopher and Gemini Client Manual
36 @vskip 0pt plus 1filll
43 @node Top, Introduction, (dir), (dir)
49 * Introduction:: Elpher Overview: what's this all about?
50 * Installation:: Installing Elpher
51 * Quick Start:: Get up and running quickly
52 * Navigation:: Fundamentals of Elpher navigation
53 * Bookmarks:: How to record and visit bookmarks
54 * Gopher character encodings:: How Elpher selects encodings for gopher pages
55 * Encrypted gopher connections:: How and when TLS is enabled for gopher
56 * Gemini support:: Support for the Gemini protocol
57 * Finger support:: Support for the Finger protocol
58 * Local files:: Opening local files in elpher
59 * About pages:: Special pages and how to reference them
60 * ANSI support:: Notes in Elpher's ANSI support
61 * Customization:: How to customize various aspects of Elpher
63 * News:: Changes introduced by major releases
64 * Contributors:: Contributors to Elpher
67 --- The Detailed Node Listing ---
71 * Within-page navigation:: Moving about within a page
72 * Between-page navigation:: Commands for moving between pages
73 * History and Caching:: Explanation of how Elpher represents history
80 @macro keycmd{key,cmd}
81 @item \key\ (@code{\cmd\})
85 @node Introduction, Installation, Top, Top
88 Elpher aims to be a capable and practical gopher and gemini client for
89 Emacs. Its focus is on easy keyboard-driven navigation based on
90 sensible default bindings (with out-of-the-box support for Evil). It is
91 intended to be robust and behave in non-surprising ways at all times.
92 Additionally, Elpher provides the following bells and whistles:
96 followable web and gopher links in plain text,
99 an easily navigable history, sporting caching of visited pages (both
100 content and cursor position),
103 auto-completing menu item navigation,
106 direct visualization of image files where supported (no writing to
110 basic support for the new ``heavier than gopher, lighter than the web'' Gemini protocol,
113 support for the Finger protocol.
117 Elpher is still under active development. Although we try very hard to
118 ensure that releases are bug-free, this cannot be guaranteed. However,
119 this also means that any usability features that you feel are missing
120 can likely by incorporated quickly, so please get in touch if you
123 @node Installation, Quick Start, Introduction, Top
124 @chapter Installation
126 @section Installing from ELPA or MELPA
128 Elpher is available on the non-GNU ELPA package archive. If you are
129 using Emacs 28 or later, this archive should be available on your system
130 by default. For Emacs 27, you'll need to follow the instructions at
131 @url{https://elpa.nongnu.org} to make the archive accessible.
133 Alternatively, Elpher is available from the MELPA package archive. If you have
134 never installed packages from this repository before, you'll need
135 to follow the instructions at @url{https://melpa.org/#/getting-started}.
137 Once one of these package archives is installed, enter the following to
141 @kbd{M-x package-install @key{RET} elpher @key{RET}}
144 @noindent To uninstall, use
147 @kbd{M-x package-delete @key{RET} elpher @key{RET}}.
150 @section Installing by hand
152 It is also possible to install Elpher directly by downloading the file
153 @file{elpher.el} from @url{gopher://thelambdalab.xyz/1/projects/elpher}
154 (you'll need to download the ``source archive'' and extract it), adding
155 it to a directory in your @code{load-path}, and then adding
161 @noindent to your Emacs initialization file.
163 @node Quick Start, Navigation, Installation, Top
166 Before diving into the minutiae of the different commands available,
167 we will quickly describe how to get up and running with Elpher.
169 Once installed, you can launch Elpher using
172 @kbd{M-x elpher @key{RET}}
175 @noindent This will switch to the *Elpher* buffer and display a start
176 page, with information on each of the default keyboard bindings.
178 From here you can move point between links (which may be menu items or
179 inline URLs in text files) by using @key{TAB} and @kbd{S-@key{TAB}},
180 as in Info. You can also jump directly to a menu item using @key{m}, or
181 use the standard Emacs or Evil motion and search commands to find your
182 way around. To open a link, press @key{RET}. (Where a mouse is
183 available, Clicking on a link with the mouse cursor has the same
186 To return to the page you just followed the link from, press @key{u}.
188 Elpher caches (for the duration of an Emacs session) both page contents
189 and the position of point on each of the pages (gopher menus, gemini
190 pages, query results, or text pages) you visit, restoring these when you
191 next visit the same page. Thus, pressing @key{u} displays the previous
192 page in exactly the same state as when you left, meaning that you can
193 quickly and visually explore the different documents in a menu without
194 having to wait for anything to reload.
196 Of course, sometimes you'll @emph{want} to reload the current page
197 rather than stick with the cached version. To do this use @key{R}.
198 (This is particularly useful for search query results, where this
199 allows you to perform a different search.)
201 That's more-or-less it. Elpher supports a number of other features,
202 such a support for different coding schemes and TLS encryption, and a
203 variety of customization options, all of which are explained in the
204 rest of this document. However the emphasis is on keeping the basic
205 navigation experience as intuitive and responsive as possible.
207 Note that you can launch multiple Elpher sessions in parallel by using
211 @kbd{C-u M-x elpher @key{RET}}
214 @node Navigation, Bookmarks, Quick Start, Top
216 Throughout this manual, we use the word ``page'' to refer to any
217 visualization of a response from a gopher or gemini server, be it a
218 menu/directory, query result, text file or image.
220 Elpher's navigation interface is inspired by the Emacs Info mode.
221 Movement within a page is essentially the same as moving
222 around any other text file in Emacs, but with special keys
223 for quickly jumping between menu items and URLs in text files.
224 Movement between pages is facilitated by a simple linear history
225 coupled with caching of pages and cursor position.
228 * Within-page navigation:: Moving about within a page
229 * Between-page navigation:: Commands for moving between pages
230 * History and Caching:: Explanation of how Elpher represents history
234 @node Within-page navigation, Between-page navigation, Navigation, Navigation
235 @section Within-page navigation
237 To move about within a page, you should be able use the same keys you usually
238 use to browse files in Emacs. This is even true when Evil mode is
239 enabled. Paragraph hopping, searching etc should work as usual.
241 In addition, the following commands are provided for quickly moving between
242 links and menu items.
245 @keycmd{@key{TAB}, elpher-next-link}
246 Move to the next link or menu item in the file.
248 @item @kbd{Shift-@key{TAB}} or @key{BACKTAB} (@code{elpher-prev-link})
249 @findex elpher-prev-link
250 Move to the previous link or menu item in the file.
252 @keycmd{@key{m}, elpher-jump}
253 Jump directly to a link within a file by specifying its display string
254 or link text. (Unlike the previous two commands, this immediately opens
259 The following commands can be used to retrieve information about the
260 current page, or the address of the link at point:
263 @keycmd{@key{i}, elpher-info-link}
264 Display host, port and selector information for the link at point.
266 @keycmd{@key{I}, elpher-info-current}
267 Display host, port and selector information for the current page.
269 @keycmd{@key{c}, elpher-copy-link-url}
270 Add URL representing address of link at point to the kill-ring and the
271 system clipboard (if available).
273 @keycmd{@key{C}, elpher-copy-current-url}
274 Add URL representing address of the current page to the kill-ring and
275 the system clipboard (if available).
277 @keycmd{@key{d}, elpher-download}
278 Download link at point and save the result as a file. The minibuffer
279 will prompt for the name of the file to write, with the default name being
280 the display string (if available) associated with the link.
282 @keycmd{@key{D}, elpher-download-current}
283 This is similar to @code{elpher-download}, but instead applies to the
284 current page rather than a link.
286 @keycmd{@key{.}, elpher-view-raw}
287 This displays the raw server response for the current page. While not
288 useful for general browsing, it is useful for debugging incorrect rendering
289 or out-of-spec server responses.
292 @node Between-page navigation, History and Caching, Within-page navigation, Navigation
293 @section Between-page navigation
295 Moving to a different page can be accomplished in several ways,
296 described by the following command:
299 @keycmd{@key{RET}\, @key{mouse-1}, elpher-follow-link}
300 Follow the menu item or link at point (or selected with the mouse).
302 Exactly what is meant by ``follow'' depends on the kind of item selected:
306 For text or menu type items or links, the current page text is replaced
307 by the text of this item. Unless the customization variable
308 @code{elpher-use-header} (@pxref{Customization}) is
309 @code{nil}, the display string of the link is displayed in the buffer header.
310 Links to images behave similarly on Emacs systems supporting the display of
311 bitmap graphics, however their content is not cached in memory by default.
314 When followed, links to search/query items (type 7) prompt for input in
315 the minibuffer then display the results in the same way as for text and menu
319 Following links to binary files (and image files on unsupported systems)
320 causes Elpher to prompt for a filename in which to save the content.
323 Following links of type `h' with a selector having the `URL:' prefix, or
324 unsupported URLs in text files, will result in Elpher using an external
325 programme to open the URL. This will be either the default system browser
326 or, if the @code{elpher-open-urls-with-eww} customization variable is non-nil,
327 Emacs' own EWW browser. (See @pxref{Customization}.)
331 Once a text, menu or query response page has been displayed, its contents are
332 cached for the duration of the Emacs session.
334 @keycmd{@key{g}, elpher-go}
335 Open a particular page by specifying either its full URL or just
336 entering a gopher host name. (The protocol defaults to gopher, so gemini
337 links must include the @code{gemini://} prefix.
339 If a unsupported protocol is used in the URL the result will be the same
340 as following a URL link of the same type from a link in a page.
342 @keycmd{@key{o}, elpher-go-current}
343 Prompts for a URL similar to @code{elpher-go}, but initialized to the URL
344 of the current page. This allows you to easily try other selectors for the
347 Remember however, that the Gopher RFC 1436 provides @emph{no} guarantees about the
348 structure of selectors.
350 @keycmd{@key{O}, elpher-root-dir}
351 Open the root page (empty selector) on the current host.
353 @keycmd{@key{u}\, @key{-}\, @key{^}\, @key{mouse-3}, elpher-back}
354 Return to the previous page, where ``previous'' means the page where the
355 page which was displayed immediately before the current page.
359 @node History and Caching, , Between-page navigation, Navigation
360 @section History and Caching
362 The history and caching strategy in Elpher is extremely simple, but
363 may be confusing without a good mental model of how it works. That
364 is what this section attempts to provide.
366 Essentially, @strong{every} time you navigate to a new page, either
367 by clicking or pressing @key{RET} on a link, using @key{g} to jump
368 to a new page by its address, or using @key{O} to open the root selector,
369 the following two things occur:
373 the cursor position and content for the original page are recorded in an
377 the original page is set as the ``parent'' of the new page.
380 The only way to return to pages in this history is by using @key{u},
381 which returns to the previous of the current page. @footnote{The
382 addition of the new page to the history happens even if the new page is
383 one that has been seen before. This is mostly the desired behaviour.
384 However, opening an explicit ``back'' link provided by a gopher menu or
385 gemini page will also add a new entry to the history. Unless you
386 haven't yet visited that menu, it's therefore better to use @key{u} to
387 go back in this case.}
389 One aspect that may seem peculiar is that Elpher lacks a corresponding ``next'' or
390 ``forward'' command. However, since Elpher caches the position of point,
391 this will be automatically positioned on the link that was most recently followed
392 from a given page. This means that, at least for links followed from menus
393 and text files, the inverse of @key{u} is actually just @key{RET}.
395 Elpher actually maintains two histories, and there are two different
396 commands to access them:
399 @keycmd{@key{s}, elpher-show-history}
400 This shows the history of the current buffer. This shows all the links
401 you would visit if you were to use @key{u} again and again.
403 @keycmd{@key{S}, elpher-show-visited-pages}
404 This shows the entire Elpher browsing history. It includes all the
405 pages you visited in your current Emacs session.
409 @node Bookmarks, Gopher character encodings, Navigation, Top
412 Elpher makes use of standard Emacs bookmarks.
413 @xref{Bookmarks, , , emacs, The Emacs Editor}.
414 The following commands are used to add new bookmarks:
417 @keycmd{@key{a}, elpher-bookmark-link}
418 Add a bookmark for the link at point. The minibuffer will prompt for
419 a name for the bookmark, which defaults to the display string.
421 @keycmd{@key{A}, elpher-bookmark-current}
422 Add a bookmark for the current page. The minibuffer will prompt for
423 a name for the bookmark, defaulting to the display string associated
424 with the link that was followed to reach the current page.
427 @keycmd{@key{B}, elpher-open-bookmarks}
428 Visit a page displaying all elpher bookmarks.
429 The behaviour of the this function depends on the customization variable
430 @code{elpher-use-emacs-bookmark-menu}. If nil (the default), the
431 command will visit a special elpher page listing all elpher-specific
432 bookmarks. If non-nil, the command will simply open the standard Emacs
433 bookmark list displaying all current bookmarks (including non-elpher
436 @keycmd{@kbd{C-x r l}, bookmark-bmenu-list}
437 This command opens the standard Emacs bookmark menu, with which bookmarks
438 can be renamed, deleted or annotated.
442 On opening the bookmarks page, elpher will offer to import any legacy
443 (2.x) bookmarks files into the new system. Once the import is complete,
444 the original bookmarks file will have ``-legacy'' appended to it, so
445 so that elpher knows not to import it again.
447 If you have any other legacy bookmark files (besides the one in the
448 original location, or specified in the @code{elpher-bookmarks-file}
449 customization variable, which should be automatically detected), you can
450 can import these using
453 @kbd{M-x elpher-bookmark-import @key{RET}}
456 Once this is done, you may delete these legacy bookmarks files.
458 @node Gopher character encodings, Encrypted gopher connections, Bookmarks, Top
459 @chapter Gopher character encodings
461 Responses Elpher retrieves from servers are initially read as pure
462 binary data. When the data is intended to be interpreted as textual (as
463 determined by the type parameter of the gopher menu item or the gopher
464 URL), this data needs to be @emph{decoded} into a sequence of
465 characters. To do this properly requires knowledge of the encoding
466 system used by whoever authored the document.
468 Unfortunately gopher lacks a systematic way of acquiring this necessary
469 information. Thus, the details of the coding system must be either
470 inferred from the binary data, or must be specified by the user.
472 By default, Elpher applies Emacs' built-in character encoding detection
473 system to the full (undecoded) response data and uses this to attempt to
474 convert it into a character string.
475 (See @pxref{Recognize coding, Recognizing coding systems, ,emacs}.) While
476 this approach can be okay, it is important to realize that its inference
477 algorithm is extremely primitive and depends heavily on assumptions based
478 on the language settings of your emacs system.
480 The alternative is to explicitly set the coding system used for decoding
481 using the following command:
484 @keycmd{@key{!},elpher-set-coding-system}
485 Causes a elpher to prompt for a coding system to use for decoding
486 future gopher text. The @key{TAB} key can be used at this prompt to display a
487 list of alternatives (which is extensive) and to auto-complete. An empty
488 response will cause Elpher to return to its default auto-detection
492 Note that changing the coding system only affects newly loaded text.
493 Thus, if text has already been decoded using an incorrect system, you
494 will need to select the correct coding and then reload the text using
498 @node Encrypted gopher connections, Gemini support, Gopher character encodings, Top
499 @chapter Encrypted gopher connections
501 While RFC 1436 does not broach the topic of encryption at all, several
502 modern gopher servers can serve content over encrypted connections,
503 and a common choice for this is TLS.
505 Elpher can retrieve selectors using Emacs' built-in TLS support which
506 uses the GnuTLS library. (It is possible to build emacs without
507 GnuTLS, in which case encryption is not supported.)
509 To retrieve documents using TLS, Elpher's TLS mode must be enabled.
510 This can be directly toggled using @key{T}, but note that just as with
511 the character encoding, changing this mode only affects subsequent
514 Alternatively, TLS mode is @emph{automatically} enabled whenever
515 gopher URLs starting with @code{gophers://} are followed.
517 The mode is sticky, so it remains active until switched off.
518 It can also be automatically switched off when a TLS connection fails.
519 In this case Elpher will prompt for your confirmation to ensure that
520 you can't accidentally make a non-TLS connection.
522 @node Gemini support, Finger support, Encrypted gopher connections, Top
523 @chapter Gemini support
525 @uref{gopher://gemini.circumlunar.space, Gemini}
526 is a new protocol being developed by several members of
527 gopherspace. It aims to solve some of the long-standing technical
528 issues associated with gopher as a protocol, while keeping the major benefits.
529 For instance, it _requires_ encrypted connections, it does away with
530 the selector type, and allows servers to explicitly specify the
531 character coding scheme used for text documents.
533 The latest versions of Elpher aim to provide seamless transitions between
534 gemini and gopher documents. Basically you should be able to open,
535 bookmark, download and otherwise interact with gemini pages in exactly
536 the same way as you do with other non-gemini pages. The only major
537 difference from your perspective as a user is that you should no longer
538 have to worry about manually toggling TLS on or off (for gemini it's
539 always on), and you should never have to manually set a character coding
542 The gemini protocol specification recommends a Trust on First Use (TOFU)
543 behaviour when validating gemini server TLS certificates. This is
544 because many gemini servers rely on self-signed certificates rather
545 than certificates signed by a CA. Sadly however, this TOFU behaviour is
546 far from straight-forward to configure using Emacs' existing Network
547 Security Manager. For this reason, elpher defaults to performing no
548 certificate verification by default. This behaviour can be easily
549 customized by setting the @code{elpher-gemini-TLS-cert-checks}
550 customization variable to non-nil.
552 The gemini specification concerns both the protocol and a simple text
553 document format (mimetype text/gemini) which is like a mixture between
554 gophermap files and markdown-formatted files but simpler than both.
555 Elpher renders gemini responses which are provided in this format in
556 line with the rules in the spec. This includes wrapping long lines at
557 word boundaries. The specific column at which this text is wrapped is
558 defined by the customization variable
559 @code{elpher-gemini-max-fill-width}, which is set to 80 columns by
560 default. (This is slightly wider than Emacs' default fill width of 70
561 columns due to the fact that there are a significant amount of older
562 gemini content which, against the advice of the current spec, hard wraps
563 at <80 columns. The larger default allows this to still look okay,
564 while still keeping content without hard wraps looking pleasant.)
566 The text/gemini format also possesses a section header syntax similar to
567 markdown. Elpher allows different header levels to be drawn with
568 different, customizable, faces. By default, on graphically-capable
569 emacs systems, these faces are given different heights to distinguish
570 among levels. On terminal systems, the level is indicated by the
571 number of preceding # symbols.
573 I should emphasize however that, while it is definitely functional,
574 Elpher's gemini support is still experimental, and various aspects will
575 change as the protocol develops further.
577 @section Client Certificates for Gemini
579 Gemini makes explicit use of the client certificate mechanism that TLS
580 provides for allowing clients to authenticate themselves with servers.
581 The Gemini specification suggests two distinct classes of client
582 certificates: short-lived certificates used to identify you for a single
583 session, and more permanent certificates used to identify you over a
586 When Elpher receives a request for a client certificate from a server,
587 it will present you with the option to create and use a single-use
588 ``throwaway'' certificate, or to use a ``persistent''
589 certificate (optionally creating it or installing pre-existing key and
592 Certificate creation in Elpher requires an installation of OpenSSL, and
593 ---in particular---that Elpher be able to run the @command{openssl} command-line
594 utility. By default, Elpher assumes that the @command{openssl} is on the
595 system path, but the precise location can be set by customizing the
596 @code{elpher-openssl-command} variable.
598 Each generated certificate results in the creation of a .key file and
599 a .crt file. In the case of a throwaway certificate, these files are
600 stored in the temporary directory indicated by the Emacs variable
601 @code{temporary-file-directory} and are deleted when ``forgotten''
602 (as described below).
604 In the case of persistent certificates, these files are stored in the
605 folder defined by the Elpher variable
606 @code{elpher-certificate-directory}, and are never deleted by Elpher.
607 (Of course you can delete them yourself whenever you like.)
608 The base name of the files (i.e. sans extension) is what Elpher uses
609 to identify the certificate.
611 Using throwaway certificates is as simple as pressing the @key{t}
612 key at the prompt which appears following a certificate request from
613 a server. There is nothing more to do.
615 Using a persistent certificate requires instead selecting @key{p} from the same
616 menu. This will result in Elpher asking you for the name identifying
617 the certificate. This entry autocompletes to the list of known certificate
618 names, so you can use @key{TAB} to display the list.
620 In the case that you choose a name that does not belong to the list of
621 known certificates, Elpher will offer to create one for you or to
622 ``install'' one from existing key and certificate files.
623 Pressing the @key{n} key will cause Elpher to begin the process of
624 creating a new persistent certificate, using some additional
625 details for which you will be prompted.
626 Alternatively, pressing the @key{i} key will cause Elpher to ask for the
627 locations of existing key and certificate files to add to
628 @code{elpher-certificate-directory} under the chosen name.
630 Once a certificate is selected, it will be used for all subsequent TLS
631 transactions to the host for which the certificate was created.
632 It is immediately ``forgotten'' when a TLS connection to another host
633 is attempted, or the following command is issued:
636 @keycmd{@key{F},elpher-forget-certificate}
637 Causes Elpher to immediately forget any currently-loaded client certificate.
640 In either case, ``forgetting'' means that the details of the key and
641 certificate file pair are erased from memory. Furthermore, in the case
642 of throw-away certificates, the corresponding files are deleted.
645 @node Finger support, Local files, Gemini support, Top
646 @chapter Finger support
648 Incidentally, Elpher has native support for querying finger servers.
649 Of course, one could argue that this functionality is more easily
650 provided by one's local telnet client. However finger URLs do appear
651 on occasion in gopherspace, and it's nice to be able to open them
654 Elpher interprets @code{finger://} URLs as follows:
659 The host is determined by the host name portion of the URL.
662 In the case that the @emph{file name} portion of the URL is non-empty (besides
663 the leading slash), this is interpreted as the user to finger.
666 Otherwise, the @emph{user} portion of the URL is interpreted as the user to finger.
669 If no user is provided, the root directory of the finger server is requested.
673 Thus @code{finger://user@@hostname} and @code{finger://hostname/user} are both equivalent.
675 (The precedence of the /user notation over the user@ notation reflects a
676 preference of the community.)
678 @node Local files, About pages, Finger support, Top
681 Elpher supports opening local files via @samp{file:} URLs.
683 For instance, pressing @key{g} and entering @code{file:~/document.gmi}
684 will load the file named @samp{document.gmi} in your home directory,
685 provided this file exists.
687 Files opened in this way are rendered according to their name, and in
688 particular their extension. The current mappings are as follows:
694 Plain text documents. All local text files are assumed to be
697 @item @samp{gophermap},@samp{gopher}
699 Gophermap files, i.e. files containing a valid directory list as specified
702 @item @samp{gemini},@samp{gmi}
704 Gemini documents (i.e. documents of MIME type ``text/gemini''). All
705 local gemini files are assumed to be UTF-8-encoded.
707 @item @samp{html},@samp{htm}
709 HTML documents. All local HTML files are assumed to be UTF-8-encoded.
711 @item @samp{png},@samp{jpg},@samp{jpeg},@samp{gif},@samp{bmp},@samp{tif},@samp{tiff}
716 A binary document, which elpher will simply offer to save somewhere
717 else. (Obviously this is not useful in its own right, but there's not
718 much that elpher can sensibly do with unknown binary files.)
723 @node About pages, ANSI support, Local files, Top
726 Like other browsers, elpher makes certain internally-generated pages
727 such as the initial welcome page, the bookmarks page, the history
728 stack and the list of visited pages pages accessible as URLs with
731 This means that these pages can be bookmarked and, more usefully,
732 added to a local file to be rendered as a user-defined start page.
734 To see the address of a special page, simply visit the page and
737 @node ANSI support, Customization, About pages, Top
738 @chapter ANSI support
740 Depending on which parts of the gopher/gemini universe you frequent,
741 you may occasionally stumble on sites which use ANSI escape codes to
742 either produce specific characters or to colour text.
744 By default, elpher uses Emacs' built-in ANSI rendering library,
745 @samp{ansi-color}, to process ANSI codes. This robustly interprets
746 the escape codes but only supports 8 colours. Any colours unsupported
747 by the library are simply stripped, leaving uncoloured text in the
750 To drastically improve the number of colours produced, install the
751 @samp{xterm-color} package from MELPA. This package will be automatically
752 used by elpher if it is available, and supports 256 colours.
753 This should be sufficient to properly render many ANSI colour
754 gopher holes and gemini capsules quite nicely.
756 In case you prefer to completely strip out the ANSI escape codes entirely
757 by customizing the @code{elpher-filter-ansi-from-text} variable.
760 @node Customization, Command Index, ANSI support, Top
761 @chapter Customization
763 Various parts of Elpher can be customized via the
764 variables belonging to the elpher customization group, accessible
768 @kbd{M-x customize-group elpher @key{RET}}
771 @noindent This group contains a number of faces that can be modified to change
772 the appearance of Elpher, including one face per menu item type.
774 The group also contains variables for customizing the behaviour of
775 Elpher. This includes how to open arbitrary (non-gopher) URLs, whether
776 to display buffer headers, how to deal with ANSI escape sequences in
777 text, the timeout to impose on network connections, and whether to
778 prompt for confirmation when switching away from TLS.
780 One particularly important customization is the @code{elpher-start-page-url}
781 variable, which holds the URL of the page displayed initially when
782 elpher starts, and when @key{U} is pressed. By default this is set to
783 @samp{about:welcome}, but any URL can be substituted. For example, you
784 might want to create a text/gemini file named
785 @samp{~/.emacs/start-page.gmi} containing useful links and set the value
786 of @code{elpher-start-page-url} to @samp{file:~/.emacs/start-page.gmi} to have
787 these links displayed at startup. Alternatively, you might prefer
788 to set the value to @samp{about:bookmarks} so that the bookmarks page
789 is used as the start page instead.
791 See the customization group itself for details.
793 @node Command Index, News, Customization, Top
794 @unnumbered Command Index
798 @node News, Contributors, Command Index, Top
801 This chapter documents the major changes introduced by Elpher releases.
805 This version includes lots of bug fixes, as well as a couple of new
808 @subsection Local gophermaps
810 Local gophermaps can now be displayed using @samp{file:}. To render
811 correctly, they must have the suffix @samp{.gopher} or @samp{.gophermap}.
813 @subsection IRI support
815 Internationalized Resource Identifiers (IRI) are an extension of URLs
816 (or, more accurately, URIs) to support a larger set of characters beyond
817 those in the US-ASCII character set. They map directly onto URIs for
818 backwards compatibility, but look like gibberish if not properly
819 decoded. When displaying URLs, Elpher now automatically decodes any IRI
820 characters and displays the decoded IRI. (For security reasons, the
821 @code{elpher-info-current} command (@kbd{I}) always displays both the
822 decoded IRI and the URI when they differ.)
826 This version introduces several minor changes which, together, make it
827 possible to set up alternative start pages configured to your liking.
829 @subsection About pages
831 Special elpher pages such as the welcome page (previously ``start''
832 page), the bookmarks page, the browsing history stack and list of
833 visited pages are now addressable via @samp{about:} URLs. For instance,
834 the standard welcome page has the address @samp{about:welcome}.
836 @subsection Local files
838 Local files can now be opened in elpher using @samp{file:} URLs. For
839 example, @kbd{g @samp{file:~/my-start.gmi}} will open
840 @samp{~/my-start.gmi} as a text/gemini document. @pxref{Local files}
843 @subsection Customizable start pages
845 The new customization variable @code{elpher-start-page-url} contains the URL
846 of the document to be loaded as elpher's ``start page''. By default
847 this is set to @samp{about:welcome}, but any elpher-accessible URL is
848 valid. @pxref{Customization} for suggestions.
852 @subsection Bookmarks system
854 While Elpher bookmarks are still handled by the Emacs bookmark
855 system, this release introduces the option to retain the
856 original elpher bookmark page for the purpose of visiting those
857 bookmarks. In v3.1.0, @key{B} visits this page (and adds it to
858 the history stack, as in previous versions), which can be interacted
859 with using the standard elpher key bindings.
861 Of course you can still view the bookmarks in the Emacs bookmark
862 menu, which you can access from anywhere using the default
863 binding @kbd{C-x r l} (or by following the link from the Elpher bookmarks
864 page). Indeed you will need to use this to rename, delete or otherwise
867 If you prefer to avoid using the Elpher bookmark page entirely, you
868 use the customization variable @code{elpher-use-emacs-bookmark-menu}
869 to have the @key{B} key open the Emacs bookmark menu directly, as in
870 the previous release.
874 @subsection Bookmarks system
876 Bookmarks are now handled by Emacs' own bookmark management system,
877 instead of Elpher's own system.
878 (For details, @xref{Bookmarks, , , emacs, The Emacs Editor}.)
879 This means two things. Firstly,
880 the bookmarks file (elpher-bookmarks by default) and format used by
881 previous versions are now deprecated. If these are detected, Elpher
882 will offer to import your old bookmarks when you first accessing the
883 bookmark list with the new version. A suffix will be added to your
884 old bookmarks file so that Elpher knows that the import is complete.
886 Secondly, the old Elpher bookmark menu has been removed in the new
887 version. Instead, @key{B} brings up the menu provided by the Emacs
888 function @code{bookmark-bmenu-list}. This has different key and mouse
889 bindings to Elpher's old menu, but is much more functional. Bookmarks
890 can be renamed, deleted in groups, and much more. (Use @kbd{C-h m} with
891 the menu open to see the complete list.)
895 Browsing history can now be accessed via new bindings to @key{s} and @key{S}.
896 The former shows the current history ``stack'' (pages accessible with
897 the @key{u} key), while the latter shows a list of all pages which have
898 been visited in the current session.
900 @subsection Socks connections
902 Elpher can now use socks connections to browse via TOR.
904 @subsection browse-url, Org and mu4e integration
906 These integrations provide support for elpher-handling of gemini, gopher
907 and finger URLs using @code{browse-url}, in Org documents, and the mu4e
910 @subsection imenu integration
912 Gemini document headers are now navigable via imenu.
913 For details, @xref{Imenu, , , emacs, The Emacs Editor}.
915 @node Contributors, , News, Top
916 @chapter Contributors
918 Elpher was originally written and is currently maintained by Tim Vaughan
919 @email{plugd@@thelambdalab.xyz}. Significant improvements and
920 maintenance have also been contributed by and with the help of Alex
921 Schroeder @email{alex@@gnu.org}. In addition, the following people have
922 all generously provided assistance and/or patches:
925 @item Jens Östlund @email{jostlund@@gmail.com}
926 @item F. Jason Park @email{jp@@neverwas.me}
927 @item Christopher Brannon @email{chris@@the-brannons.com}
928 @item Omar Polo @email{op@@omarpolo.com}
929 @item Noodles! @email{nnoodle@@chiru.no}
930 @item Abhiseck Paira @email{abhiseckpaira@@disroot.org}
931 @item Zhiwei Chen @email{chenzhiwei03@@kuaishou.com}
932 @item condy0919 @email{condy0919@@gmail.com}
933 @item Alexis @email{flexibeast@@gmail.com}
934 @item Étienne Deparis @email{etienne@@depar.is}
935 @item Simon Nicolussi @email{sinic@@sinic.name}
936 @item Michel Alexandre Salim @email{michel@@michel-slm.name}
937 @item Koushk Roy @email{kroy@@twilio.com}
938 @item Vee @email{vee@@vnsf.xyz}
939 @item Simon South @email{simon@@simonsouth.net}
940 @item Daniel Semyonov @email{daniel@@dsemy.com}
941 @item Bradley Thornton @email{bradley@@northtech.us}