1 \input texinfo @c -*-texinfo-*-
3 @setfilename elpher.info
4 @settitle Elpher Manual v3.6.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-2023 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 * Installing from ELPA or MELPA:: Installing from a package repository
72 * Installing by hand:: Installing directly from the source
76 * Within-page navigation:: Moving about within a page
77 * Between-page navigation:: Commands for moving between pages
78 * History and Caching:: Explanation of how Elpher represents history
82 * Client Certificates for Gemini:: Accessing secure gemini pages
83 * Hiding preformatted text in text/gemini documents:: An accessibility option
100 @macro keycmd{key,cmd}
101 @item \key\ (@code{\cmd\})
105 @node Introduction, Installation, Top, Top
106 @chapter Introduction
108 Elpher aims to be a capable and practical gopher and gemini client for
109 Emacs. Its focus is on easy keyboard-driven navigation based on
110 sensible default bindings (with out-of-the-box support for Evil). It is
111 intended to be robust and behave in non-surprising ways at all times.
112 Additionally, Elpher provides the following bells and whistles:
116 followable web and gopher links in plain text,
119 an easily navigable history, sporting caching of visited pages (both
120 content and cursor position),
123 auto-completing menu item navigation,
126 direct visualization of image files where supported (no writing to
130 basic support for the new ``heavier than gopher, lighter than the web'' Gemini protocol,
133 support for the Finger protocol.
137 Elpher is still under active development. Although we try very hard to
138 ensure that releases are bug-free, this cannot be guaranteed. However,
139 this also means that any usability features that you feel are missing
140 can likely by incorporated quickly, so please get in touch if you
143 @node Installation, Quick Start, Introduction, Top
144 @chapter Installation
147 * Installing from ELPA or MELPA:: Installing from a package repository
148 * Installing by hand:: Installing directly from the source
151 @node Installing from ELPA or MELPA, Installing by hand, Installation, Installation
152 @section Installing from ELPA or MELPA
154 Elpher is available on the non-GNU ELPA package archive. If you are
155 using Emacs 28 or later, this archive should be available on your system
156 by default. For Emacs 27, you'll need to follow the instructions at
157 @url{https://elpa.nongnu.org} to make the archive accessible.
159 Alternatively, Elpher is available from the MELPA package archive. If you have
160 never installed packages from this repository before, you'll need
161 to follow the instructions at @url{https://melpa.org/#/getting-started}.
163 Once one of these package archives is installed, enter the following to
167 @kbd{M-x package-install @key{RET} elpher @key{RET}}
170 @noindent To uninstall, use
173 @kbd{M-x package-delete @key{RET} elpher @key{RET}}.
176 @node Installing by hand, , Installing from ELPA or MELPA, Installation
177 @section Installing by hand
179 It is also possible to install Elpher directly by downloading the file
180 @file{elpher.el} from @url{gopher://thelambdalab.xyz/1/projects/elpher}
181 (you'll need to download the ``source archive'' and extract it), adding
182 it to a directory in your @code{load-path}, and then adding
188 @noindent to your Emacs initialization file.
190 @node Quick Start, Navigation, Installation, Top
193 Before diving into the minutiae of the different commands available,
194 we will quickly describe how to get up and running with Elpher.
196 Once installed, you can launch Elpher using
199 @kbd{M-x elpher @key{RET}}
202 @noindent This will switch to the *Elpher* buffer and display a start
203 page, with information on each of the default keyboard bindings.
205 From here you can move point between links (which may be menu items or
206 inline URLs in text files) by using @key{TAB} and @kbd{S-@key{TAB}},
207 as in Info. You can also jump directly to a menu item using @key{m}, or
208 use the standard Emacs or Evil motion and search commands to find your
209 way around. To open a link, press @key{RET}. (Where a mouse is
210 available, Clicking on a link with the mouse cursor has the same
213 To return to the page you just followed the link from, press @key{u}.
215 Elpher caches (for the duration of an Emacs session) both page contents
216 and the position of point on each of the pages (gopher menus, gemini
217 pages, query results, or text pages) you visit, restoring these when you
218 next visit the same page. Thus, pressing @key{u} displays the previous
219 page in exactly the same state as when you left, meaning that you can
220 quickly and visually explore the different documents in a menu without
221 having to wait for anything to reload.
223 Of course, sometimes you'll @emph{want} to reload the current page
224 rather than stick with the cached version. To do this use @key{R}.
225 (This is particularly useful for search query results, where this
226 allows you to perform a different search.)
228 That's more-or-less it. Elpher supports a number of other features,
229 such a support for different coding schemes and TLS encryption, and a
230 variety of customization options, all of which are explained in the
231 rest of this document. However the emphasis is on keeping the basic
232 navigation experience as intuitive and responsive as possible.
234 Note that you can launch multiple Elpher sessions in parallel by using
238 @kbd{C-u M-x elpher @key{RET}}
241 @node Navigation, Bookmarks, Quick Start, Top
243 Throughout this manual, we use the word ``page'' to refer to any
244 visualization of a response from a gopher or gemini server, be it a
245 menu/directory, query result, text file or image.
247 Elpher's navigation interface is inspired by the Emacs Info mode.
248 Movement within a page is essentially the same as moving
249 around any other text file in Emacs, but with special keys
250 for quickly jumping between menu items and URLs in text files.
251 Movement between pages is facilitated by a simple linear history
252 coupled with caching of pages and cursor position.
255 * Within-page navigation:: Moving about within a page
256 * Between-page navigation:: Commands for moving between pages
257 * History and Caching:: Explanation of how Elpher represents history
261 @node Within-page navigation, Between-page navigation, Navigation, Navigation
262 @section Within-page navigation
264 To move about within a page, you should be able use the same keys you usually
265 use to browse files in Emacs. This is even true when Evil mode is
266 enabled. Paragraph hopping, searching etc should work as usual.
268 In addition, the following commands are provided for quickly moving between
269 links and menu items.
272 @keycmd{@key{TAB}, elpher-next-link}
273 Move to the next link or menu item in the file.
275 @item @kbd{Shift-@key{TAB}} or @key{BACKTAB} (@code{elpher-prev-link})
276 @findex elpher-prev-link
277 Move to the previous link or menu item in the file.
279 @keycmd{@key{m}, elpher-jump}
280 Jump directly to a link within a file by specifying its display string
281 or link text. (Unlike the previous two commands, this immediately opens
286 The following commands can be used to retrieve information about the
287 current page, or the address of the link at point:
290 @keycmd{@key{i}, elpher-info-link}
291 Display host, port and selector information for the link at point.
293 @keycmd{@key{I}, elpher-info-current}
294 Display host, port and selector information for the current page.
296 @keycmd{@key{c}, elpher-copy-link-url}
297 Add URL representing address of link at point to the kill-ring and the
298 system clipboard (if available).
300 @keycmd{@key{C}, elpher-copy-current-url}
301 Add URL representing address of the current page to the kill-ring and
302 the system clipboard (if available).
304 @keycmd{@key{d}, elpher-download}
305 Download link at point and save the result as a file. The minibuffer
306 will prompt for the name of the file to write, with the default name being
307 the display string (if available) associated with the link.
309 @keycmd{@key{D}, elpher-download-current}
310 This is similar to @code{elpher-download}, but instead applies to the
311 current page rather than a link.
313 @keycmd{@key{.}, elpher-view-raw}
314 This displays the raw server response for the current page. While not
315 useful for general browsing, it is useful for debugging incorrect rendering
316 or out-of-spec server responses.
319 @node Between-page navigation, History and Caching, Within-page navigation, Navigation
320 @section Between-page navigation
322 Moving to a different page can be accomplished in several ways,
323 described by the following command:
326 @keycmd{@key{RET}\, @key{mouse-1}, elpher-follow-current-link}
327 Follow the menu item or link at point (or selected with the mouse).
329 Exactly what is meant by ``follow'' depends on the kind of item selected:
333 For text or menu type items or links, the current page text is replaced
334 by the text of this item. Unless the customization variable
335 @code{elpher-use-header} (@pxref{Customization}) is
336 @code{nil}, the display string of the link is displayed in the buffer header.
337 Links to images behave similarly on Emacs systems supporting the display of
338 bitmap graphics, however their content is not cached in memory by default.
341 When followed, links to search/query items (type 7) prompt for input in
342 the minibuffer then display the results in the same way as for text and menu
346 Following links to binary files (and image files on unsupported systems)
347 causes Elpher to prompt for a filename in which to save the content.
350 Following links of type `h' with a selector having the `URL:' prefix, or
351 unsupported URLs in text files, will result in Elpher using an external
352 programme to open the URL. This will be either the default system browser
353 or, if the @code{elpher-open-urls-with-eww} customization variable is non-nil,
354 Emacs' own EWW browser. (See @pxref{Customization}.)
358 Once a text, menu or query response page has been displayed, its contents are
359 cached for the duration of the Emacs session.
361 @keycmd{S-@key{RET}\, S-@key{mouse-1}, elpher-follow-current-link-new-buffer}
362 Create a new Elpher buffer and follow the menu item or link at point
365 @keycmd{@key{g}, elpher-go}
366 Open a particular page by specifying either its full URL or just
367 entering a gopher host name. (The protocol defaults to gopher, so gemini
368 links must include the @code{gemini://} prefix.
370 If a unsupported protocol is used in the URL the result will be the same
371 as following a URL link of the same type from a link in a page.
373 @keycmd{@key{o}, elpher-go-current}
374 Prompts for a URL similar to @code{elpher-go}, but initialized to the URL
375 of the current page. This allows you to easily try other selectors for the
378 Remember however, that the Gopher RFC 1436 provides @emph{no} guarantees about the
379 structure of selectors.
381 @keycmd{@key{O}, elpher-root-dir}
382 Open the root page (empty selector) on the current host.
384 @keycmd{@key{u}\, @key{-}\, @key{^}\, @key{mouse-3}, elpher-back}
385 Return to the previous page, where ``previous'' means the page where the
386 page which was displayed immediately before the current page.
390 @node History and Caching, , Between-page navigation, Navigation
391 @section History and Caching
393 The history and caching strategy in Elpher is extremely simple, but
394 may be confusing without a good mental model of how it works. That
395 is what this section attempts to provide.
397 Essentially, @strong{every} time you navigate to a new page, either
398 by clicking or pressing @key{RET} on a link, using @key{g} to jump
399 to a new page by its address, or using @key{O} to open the root selector,
400 the following two things occur:
404 the cursor position and content for the original page are recorded in an
408 the original page is set as the ``parent'' of the new page.
411 The only way to return to pages in this history is by using @key{u},
412 which returns to the previous of the current page. @footnote{The
413 addition of the new page to the history happens even if the new page is
414 one that has been seen before. This is mostly the desired behaviour.
415 However, opening an explicit ``back'' link provided by a gopher menu or
416 gemini page will also add a new entry to the history. Unless you
417 haven't yet visited that menu, it's therefore better to use @key{u} to
418 go back in this case.}
420 One aspect that may seem peculiar is that Elpher lacks a corresponding ``next'' or
421 ``forward'' command. However, since Elpher caches the position of point,
422 this will be automatically positioned on the link that was most recently followed
423 from a given page. This means that, at least for links followed from menus
424 and text files, the inverse of @key{u} is actually just @key{RET}.
426 Elpher actually maintains two histories, and there are two different
427 commands to access them:
430 @keycmd{@key{s}, elpher-show-history}
431 This shows the history of the current buffer. This shows all the links
432 you would visit if you were to use @key{u} again and again.
434 @keycmd{@key{S}, elpher-show-visited-pages}
435 This shows the entire Elpher browsing history. It includes all the
436 pages you visited in your current Emacs session.
440 @node Bookmarks, Gopher character encodings, Navigation, Top
443 Elpher makes use of standard Emacs bookmarks.
444 @xref{Bookmarks, , , emacs, The Emacs Editor}.
445 The following commands are used to add new bookmarks:
448 @keycmd{@key{a}, elpher-bookmark-link}
449 Add a bookmark for the link at point. The minibuffer will prompt for
450 a name for the bookmark, which defaults to the display string.
452 @keycmd{@key{A}, elpher-bookmark-current}
453 Add a bookmark for the current page. The minibuffer will prompt for
454 a name for the bookmark, defaulting to the display string associated
455 with the link that was followed to reach the current page.
458 @keycmd{@key{B}, elpher-open-bookmarks}
459 Visit a page displaying all elpher bookmarks.
460 The behaviour of the this function depends on the customization variable
461 @code{elpher-use-emacs-bookmark-menu}. If nil (the default), the
462 command will visit a special elpher page listing all elpher-specific
463 bookmarks. If non-nil, the command will simply open the standard Emacs
464 bookmark list displaying all current bookmarks (including non-elpher
467 @keycmd{@kbd{C-x r l}, bookmark-bmenu-list}
468 This command opens the standard Emacs bookmark menu, with which bookmarks
469 can be renamed, deleted or annotated.
473 On opening the bookmarks page, elpher will offer to import any legacy
474 (2.x) bookmarks files into the new system. Once the import is complete,
475 the original bookmarks file will have ``-legacy'' appended to it, so
476 so that elpher knows not to import it again.
478 If you have any other legacy bookmark files (besides the one in the
479 original location, or specified in the @code{elpher-bookmarks-file}
480 customization variable, which should be automatically detected), you can
481 can import these using
484 @kbd{M-x elpher-bookmark-import @key{RET}}
487 Once this is done, you may delete these legacy bookmarks files.
489 @node Gopher character encodings, Encrypted gopher connections, Bookmarks, Top
490 @chapter Gopher character encodings
492 Responses Elpher retrieves from servers are initially read as pure
493 binary data. When the data is intended to be interpreted as textual (as
494 determined by the type parameter of the gopher menu item or the gopher
495 URL), this data needs to be @emph{decoded} into a sequence of
496 characters. To do this properly requires knowledge of the encoding
497 system used by whoever authored the document.
499 Unfortunately gopher lacks a systematic way of acquiring this necessary
500 information. Thus, the details of the coding system must be either
501 inferred from the binary data, or must be specified by the user.
503 By default, Elpher applies Emacs' built-in character encoding detection
504 system to the full (undecoded) response data and uses this to attempt to
505 convert it into a character string.
506 (See @pxref{Recognize coding, Recognizing coding systems, ,emacs}.) While
507 this approach can be okay, it is important to realize that its inference
508 algorithm is extremely primitive and depends heavily on assumptions based
509 on the language settings of your emacs system.
511 The alternative is to explicitly set the coding system used for decoding
512 using the following command:
515 @keycmd{@key{!},elpher-set-coding-system}
516 Causes a elpher to prompt for a coding system to use for decoding
517 future gopher text. The @key{TAB} key can be used at this prompt to display a
518 list of alternatives (which is extensive) and to auto-complete. An empty
519 response will cause Elpher to return to its default auto-detection
523 Note that changing the coding system only affects newly loaded text.
524 Thus, if text has already been decoded using an incorrect system, you
525 will need to select the correct coding and then reload the text using
529 @node Encrypted gopher connections, Gemini support, Gopher character encodings, Top
530 @chapter Encrypted gopher connections
532 While RFC 1436 does not broach the topic of encryption at all, several
533 modern gopher servers can serve content over encrypted connections,
534 and a common choice for this is TLS.
536 Elpher can retrieve selectors using Emacs' built-in TLS support which
537 uses the GnuTLS library. (It is possible to build emacs without
538 GnuTLS, in which case encryption is not supported.)
540 To retrieve documents using TLS, Elpher's TLS mode must be enabled.
541 This can be directly toggled using @key{T}, but note that just as with
542 the character encoding, changing this mode only affects subsequent
545 Alternatively, TLS mode is @emph{automatically} enabled whenever
546 gopher URLs starting with @code{gophers://} are followed.
548 The mode is sticky, so it remains active until switched off.
549 It can also be automatically switched off when a TLS connection fails.
550 In this case Elpher will prompt for your confirmation to ensure that
551 you can't accidentally make a non-TLS connection.
553 @node Gemini support, Finger support, Encrypted gopher connections, Top
554 @chapter Gemini support
556 @uref{gopher://gemini.circumlunar.space, Gemini}
557 is a new protocol being developed by several members of
558 gopherspace. It aims to solve some of the long-standing technical
559 issues associated with gopher as a protocol, while keeping the major benefits.
560 For instance, it _requires_ encrypted connections, it does away with
561 the selector type, and allows servers to explicitly specify the
562 character coding scheme used for text documents.
564 The latest versions of Elpher aim to provide seamless transitions between
565 gemini and gopher documents. Basically you should be able to open,
566 bookmark, download and otherwise interact with gemini pages in exactly
567 the same way as you do with other non-gemini pages. The only major
568 difference from your perspective as a user is that you should no longer
569 have to worry about manually toggling TLS on or off (for gemini it's
570 always on), and you should never have to manually set a character coding
573 The gemini protocol specification recommends a Trust on First Use (TOFU)
574 behaviour when validating gemini server TLS certificates. This is
575 because many gemini servers rely on self-signed certificates rather
576 than certificates signed by a CA. Sadly however, this TOFU behaviour is
577 far from straight-forward to configure using Emacs' existing Network
578 Security Manager. For this reason, elpher defaults to performing no
579 certificate verification by default. This behaviour can be easily
580 customized by setting the @code{elpher-gemini-TLS-cert-checks}
581 customization variable to non-nil.
583 The gemini specification concerns both the protocol and a simple text
584 document format (mimetype text/gemini) which is like a mixture between
585 gophermap files and markdown-formatted files but simpler than both.
586 Elpher renders gemini responses which are provided in this format in
587 line with the rules in the spec. This includes wrapping long lines at
588 word boundaries. The specific column at which this text is wrapped is
589 defined by the customization variable
590 @code{elpher-gemini-max-fill-width}, which is set to 80 columns by
591 default. (This is slightly wider than Emacs' default fill width of 70
592 columns due to the fact that there are a significant amount of older
593 gemini content which, against the advice of the current spec, hard wraps
594 at <80 columns. The larger default allows this to still look okay,
595 while still keeping content without hard wraps looking pleasant.)
597 The text/gemini format also possesses a section header syntax similar to
598 markdown. Elpher allows different header levels to be drawn with
599 different, customizable, faces. By default, on graphically-capable
600 emacs systems, these faces are given different heights to distinguish
601 among levels. On terminal systems, the level is indicated by the
602 number of preceding # symbols.
605 * Client Certificates for Gemini:: Accessing secure gemini pages
606 * Hiding preformatted text in text/gemini documents:: An accessibility option
609 @node Client Certificates for Gemini, Hiding preformatted text in text/gemini documents, Gemini support, Gemini support
610 @section Client Certificates for Gemini
612 Gemini makes explicit use of the client certificate mechanism that TLS
613 provides for allowing clients to authenticate themselves with servers.
614 The Gemini specification suggests two distinct classes of client
615 certificates: short-lived certificates used to identify you for a single
616 session, and more permanent certificates used to identify you over a
619 When Elpher receives a request for a client certificate from a server,
620 it will present you with the option to create and use a single-use
621 ``throwaway'' certificate, or to use a ``persistent''
622 certificate (optionally creating it or installing pre-existing key and
625 Certificate creation in Elpher requires an installation of OpenSSL, and
626 ---in particular---that Elpher be able to run the @command{openssl} command-line
627 utility. By default, Elpher assumes that the @command{openssl} is on the
628 system path, but the precise location can be set by customizing the
629 @code{elpher-openssl-command} variable.
631 Each generated certificate results in the creation of a .key file and
632 a .crt file. In the case of a throwaway certificate, these files are
633 stored in the temporary directory indicated by the Emacs variable
634 @code{temporary-file-directory} and are deleted when ``forgotten''
635 (as described below).
637 In the case of persistent certificates, these files are stored in the
638 folder defined by the Elpher variable
639 @code{elpher-certificate-directory}, and are never deleted by Elpher.
640 (Of course you can delete them yourself whenever you like.)
641 The base name of the files (i.e. sans extension) is what Elpher uses
642 to identify the certificate.
644 Using throwaway certificates is as simple as pressing the @key{t}
645 key at the prompt which appears following a certificate request from
646 a server. There is nothing more to do.
648 Using a persistent certificate requires instead selecting @key{p} from the same
649 menu. This will result in Elpher asking you for the name identifying
650 the certificate. This entry autocompletes to the list of known certificate
651 names, so you can use @key{TAB} to display the list.
653 In the case that you choose a name that does not belong to the list of
654 known certificates, Elpher will offer to create one for you or to
655 ``install'' one from existing key and certificate files.
656 Pressing the @key{n} key will cause Elpher to begin the process of
657 creating a new persistent certificate, using some additional
658 details for which you will be prompted.
659 Alternatively, pressing the @key{i} key will cause Elpher to ask for the
660 locations of existing key and certificate files to add to
661 @code{elpher-certificate-directory} under the chosen name.
663 Once a certificate is selected, it will be used for all subsequent
664 gemini requests involving URLs begining with the URL for for which the
665 certificate was created. It is immediately ``forgotten'' when a TLS
666 connection to a non-matching URL is attempted, or the following command
670 @keycmd{@key{F},elpher-forget-certificate}
671 Causes Elpher to immediately forget any currently-loaded client certificate.
674 In either case, ``forgetting'' means that the details of the key and
675 certificate file pair are erased from memory. Furthermore, in the case
676 of throw-away certificates, the corresponding files are deleted.
678 Persistant client certificates can be added to the alist contained in the
679 customization variable @code{elpher-certificate-map} so that they are
680 automatically activated whenever a gemini page with the matching URL
683 @node Hiding preformatted text in text/gemini documents, , Client Certificates for Gemini, Gemini support
684 @section Hiding preformatted text in text/gemini documents
686 Preformatted text is often used to display ``ASCII art'' or other
687 similar text-based artwork. While for many this is a fun way to
688 introduce personality into their gemini documents, such text can
689 pose difficulties for screen readers.
691 Setting the @code{elpher-gemini-hide-preformatted} customization option
692 to non-nil causes Elpher to hide all preformatted text blocks by
693 default. In place of the preformatted text, Elpher instead displays the
694 ``alt text'' (if any is available), along with a button which can be
695 used to make specific blocks visible as required.
697 Other related customization options are
698 @code{elpher-gemini-preformatted-toggle-label}, which is the label used
699 for the toggle button, and
700 @code{elpher-gemini-preformatted-toggle-bullet}, which is the margin
701 string used to distinguish the line replacing the preformatted text.
703 @node Finger support, Local files, Gemini support, Top
704 @chapter Finger support
706 Incidentally, Elpher has native support for querying finger servers.
707 Of course, one could argue that this functionality is more easily
708 provided by one's local telnet client. However finger URLs do appear
709 on occasion in gopherspace, and it's nice to be able to open them
712 Elpher interprets @code{finger://} URLs as follows:
717 The host is determined by the host name portion of the URL.
720 In the case that the @emph{file name} portion of the URL is non-empty (besides
721 the leading slash), this is interpreted as the user to finger.
724 Otherwise, the @emph{user} portion of the URL is interpreted as the user to finger.
727 If no user is provided, the root directory of the finger server is requested.
731 Thus @code{finger://user@@hostname} and @code{finger://hostname/user} are both equivalent.
733 (The precedence of the /user notation over the user@ notation reflects a
734 preference of the community.)
736 @node Local files, About pages, Finger support, Top
739 Elpher supports opening local files via @samp{file:} URLs.
741 For instance, pressing @key{g} and entering @code{file:~/document.gmi}
742 will load the file named @samp{document.gmi} in your home directory,
743 provided this file exists.
745 Files opened in this way are rendered according to their name, and in
746 particular their extension. The current mappings are as follows:
752 Plain text documents. All local text files are assumed to be
755 @item @samp{gophermap},@samp{gopher}
757 Gophermap files, i.e. files containing a valid directory list as specified
760 @item @samp{gemini},@samp{gmi}
762 Gemini documents (i.e. documents of MIME type ``text/gemini''). All
763 local gemini files are assumed to be UTF-8-encoded.
765 @item @samp{html},@samp{htm}
767 HTML documents. All local HTML files are assumed to be UTF-8-encoded.
769 @item @samp{png},@samp{jpg},@samp{jpeg},@samp{gif},@samp{bmp},@samp{tif},@samp{tiff}
774 A binary document, which elpher will simply offer to save somewhere
775 else. (Obviously this is not useful in its own right, but there's not
776 much that elpher can sensibly do with unknown binary files.)
781 @node About pages, ANSI support, Local files, Top
784 Like other browsers, elpher makes certain internally-generated pages
785 such as the initial welcome page, the bookmarks page, the history
786 stack and the list of visited pages pages accessible as URLs with
789 This means that these pages can be bookmarked and, more usefully,
790 added to a local file to be rendered as a user-defined start page.
792 To see the address of a special page, simply visit the page and
795 @node ANSI support, Customization, About pages, Top
796 @chapter ANSI support
798 Depending on which parts of the gopher/gemini universe you frequent,
799 you may occasionally stumble on sites which use ANSI escape codes to
800 either produce specific characters or to colour text.
802 By default, elpher uses Emacs' built-in ANSI rendering library,
803 @samp{ansi-color}, to process ANSI codes. This robustly interprets
804 the escape codes but only supports 8 colours. Any colours unsupported
805 by the library are simply stripped, leaving uncoloured text in the
808 To drastically improve the number of colours produced, install the
809 @samp{xterm-color} package from MELPA. This package will be automatically
810 used by elpher if it is available, and supports 256 colours.
811 This should be sufficient to properly render many ANSI colour
812 gopher holes and gemini capsules quite nicely.
814 In case you prefer to completely strip out the ANSI escape codes entirely
815 by customizing the @code{elpher-filter-ansi-from-text} variable.
818 @node Customization, Command Index, ANSI support, Top
819 @chapter Customization
821 Various parts of Elpher can be customized via the
822 variables belonging to the elpher customization group, accessible
826 @kbd{M-x customize-group elpher @key{RET}}
829 @noindent This group contains a number of faces that can be modified to change
830 the appearance of Elpher, including one face per menu item type.
832 The group also contains variables for customizing the behaviour of
833 Elpher. This includes how to open arbitrary (non-gopher) URLs, whether
834 to display buffer headers, how to deal with ANSI escape sequences in
835 text, the timeout to impose on network connections, and whether to
836 prompt for confirmation when switching away from TLS.
838 One particularly important customization is the @code{elpher-start-page-url}
839 variable, which holds the URL of the page displayed initially when
840 elpher starts, and when @key{U} is pressed. By default this is set to
841 @samp{about:welcome}, but any URL can be substituted. For example, you
842 might want to create a text/gemini file named
843 @samp{~/.emacs/start-page.gmi} containing useful links and set the value
844 of @code{elpher-start-page-url} to @samp{file:~/.emacs/start-page.gmi} to have
845 these links displayed at startup. Alternatively, you might prefer
846 to set the value to @samp{about:bookmarks} so that the bookmarks page
847 is used as the start page instead.
849 See the customization group itself for details.
851 @node Command Index, News, Customization, Top
852 @unnumbered Command Index
856 @node News, Contributors, Command Index, Top
859 This chapter documents the major changes introduced by Elpher releases.
871 @node v3.6.0, v3.5.0, News, News
874 @subsection Easily open links in new buffer
876 This version includes the ability to open all link types in
877 Elpher documents in a new buffer. By default, this is bound
878 to S-@key{RET} and S-@key{mouse-1}, but this can be modified
879 by adding adjusting the bindings in @code{elpher-link-keymap}.
881 @node v3.5.0, v3.4.0, v3.6.0, News
884 @subsection Automatic activation of client certificates in gemini
886 This version introduces a new customization variable
887 @code{elpher-certificate-map} which allows you to pre-specify
888 a set of gemini URLs and the client certificates which should
889 be used when accessing them.
891 @xref{Client Certificates for Gemini} for more details.
893 @node v3.4.0, v3.3.0, v3.5.0, News
896 @subsection Toggling preformatted text visibility
898 This version introduces the ability to hide preformatted text in
899 text/gemini documents by default. To enable this, set the customization
900 variable @code{elpher-gemini-hide-preformatted} to non-nil. This causes
901 all preformated text blocks to be replaced with their ``alt-text'' (if
902 any is available) and a button for toggling the visibility of the text
905 This feature is intended to make it easier for people using screen
906 readers to read text/gemini documents.
908 @node v3.3.0, v3.2.0, v3.4.0, News
911 This version includes lots of bug fixes, as well as a couple of new
914 @subsection Local gophermaps
916 Local gophermaps can now be displayed using @samp{file:}. To render
917 correctly, they must have the suffix @samp{.gopher} or @samp{.gophermap}.
919 @subsection IRI support
921 Internationalized Resource Identifiers (IRI) are an extension of URLs
922 (or, more accurately, URIs) to support a larger set of characters beyond
923 those in the US-ASCII character set. They map directly onto URIs for
924 backwards compatibility, but look like gibberish if not properly
925 decoded. When displaying URLs, Elpher now automatically decodes any IRI
926 characters and displays the decoded IRI. (For security reasons, the
927 @code{elpher-info-current} command (@kbd{I}) always displays both the
928 decoded IRI and the URI when they differ.)
930 @node v3.2.0, v3.1.0, v3.3.0, News
933 This version introduces several minor changes which, together, make it
934 possible to set up alternative start pages configured to your liking.
936 @subsection About pages
938 Special elpher pages such as the welcome page (previously ``start''
939 page), the bookmarks page, the browsing history stack and list of
940 visited pages are now addressable via @samp{about:} URLs. For instance,
941 the standard welcome page has the address @samp{about:welcome}.
943 @subsection Local files
945 Local files can now be opened in elpher using @samp{file:} URLs. For
946 example, @kbd{g @samp{file:~/my-start.gmi}} will open
947 @samp{~/my-start.gmi} as a text/gemini document. @pxref{Local files}
950 @subsection Customizable start pages
952 The new customization variable @code{elpher-start-page-url} contains the URL
953 of the document to be loaded as elpher's ``start page''. By default
954 this is set to @samp{about:welcome}, but any elpher-accessible URL is
955 valid. @pxref{Customization} for suggestions.
957 @node v3.1.0, v3.0.0, v3.2.0, News
960 @subsection Bookmarks system
962 While Elpher bookmarks are still handled by the Emacs bookmark
963 system, this release introduces the option to retain the
964 original elpher bookmark page for the purpose of visiting those
965 bookmarks. In v3.1.0, @key{B} visits this page (and adds it to
966 the history stack, as in previous versions), which can be interacted
967 with using the standard elpher key bindings.
969 Of course you can still view the bookmarks in the Emacs bookmark
970 menu, which you can access from anywhere using the default
971 binding @kbd{C-x r l} (or by following the link from the Elpher bookmarks
972 page). Indeed you will need to use this to rename, delete or otherwise
975 If you prefer to avoid using the Elpher bookmark page entirely, you
976 use the customization variable @code{elpher-use-emacs-bookmark-menu}
977 to have the @key{B} key open the Emacs bookmark menu directly, as in
978 the previous release.
980 @node v3.0.0, , v3.1.0, News
983 @subsection Bookmarks system
985 Bookmarks are now handled by Emacs' own bookmark management system,
986 instead of Elpher's own system.
987 (For details, @xref{Bookmarks, , , emacs, The Emacs Editor}.)
988 This means two things. Firstly,
989 the bookmarks file (elpher-bookmarks by default) and format used by
990 previous versions are now deprecated. If these are detected, Elpher
991 will offer to import your old bookmarks when you first accessing the
992 bookmark list with the new version. A suffix will be added to your
993 old bookmarks file so that Elpher knows that the import is complete.
995 Secondly, the old Elpher bookmark menu has been removed in the new
996 version. Instead, @key{B} brings up the menu provided by the Emacs
997 function @code{bookmark-bmenu-list}. This has different key and mouse
998 bindings to Elpher's old menu, but is much more functional. Bookmarks
999 can be renamed, deleted in groups, and much more. (Use @kbd{C-h m} with
1000 the menu open to see the complete list.)
1004 Browsing history can now be accessed via new bindings to @key{s} and @key{S}.
1005 The former shows the current history ``stack'' (pages accessible with
1006 the @key{u} key), while the latter shows a list of all pages which have
1007 been visited in the current session.
1009 @subsection Socks connections
1011 Elpher can now use socks connections to browse via TOR.
1013 @subsection browse-url, Org and mu4e integration
1015 These integrations provide support for elpher-handling of gemini, gopher
1016 and finger URLs using @code{browse-url}, in Org documents, and the mu4e
1019 @subsection imenu integration
1021 Gemini document headers are now navigable via imenu.
1022 For details, @xref{Imenu, , , emacs, The Emacs Editor}.
1024 @node Contributors, , News, Top
1025 @chapter Contributors
1027 Elpher was originally written and is currently maintained by Tim Vaughan
1028 @email{plugd@@thelambdalab.xyz}. Significant improvements and
1029 maintenance have also been contributed by and with the help of Alex
1030 Schroeder @email{alex@@gnu.org}. In addition, the following people have
1031 all generously provided assistance and/or patches:
1034 @item Jens Östlund @email{jostlund@@gmail.com}
1035 @item F. Jason Park @email{jp@@neverwas.me}
1036 @item Christopher Brannon @email{chris@@the-brannons.com}
1037 @item Omar Polo @email{op@@omarpolo.com}
1038 @item Noodles! @email{nnoodle@@chiru.no}
1039 @item Abhiseck Paira @email{abhiseckpaira@@disroot.org}
1040 @item Zhiwei Chen @email{chenzhiwei03@@kuaishou.com}
1041 @item condy0919 @email{condy0919@@gmail.com}
1042 @item Alexis @email{flexibeast@@gmail.com}
1043 @item Étienne Deparis @email{etienne@@depar.is}
1044 @item Simon Nicolussi @email{sinic@@sinic.name}
1045 @item Michel Alexandre Salim @email{michel@@michel-slm.name}
1046 @item Koushk Roy @email{kroy@@twilio.com}
1047 @item Vee @email{vee@@vnsf.xyz}
1048 @item Simon South @email{simon@@simonsouth.net}
1049 @item Daniel Semyonov @email{daniel@@dsemy.com}
1050 @item Bradley Thornton @email{bradley@@northtech.us}