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.
604 I should emphasize however that, while it is definitely functional,
605 Elpher's gemini support is still experimental, and various aspects will
606 change as the protocol develops further.
609 * Client Certificates for Gemini:: Accessing secure gemini pages
610 * Hiding preformatted text in text/gemini documents:: An accessibility option
613 @node Client Certificates for Gemini, Hiding preformatted text in text/gemini documents, Gemini support, Gemini support
614 @section Client Certificates for Gemini
616 Gemini makes explicit use of the client certificate mechanism that TLS
617 provides for allowing clients to authenticate themselves with servers.
618 The Gemini specification suggests two distinct classes of client
619 certificates: short-lived certificates used to identify you for a single
620 session, and more permanent certificates used to identify you over a
623 When Elpher receives a request for a client certificate from a server,
624 it will present you with the option to create and use a single-use
625 ``throwaway'' certificate, or to use a ``persistent''
626 certificate (optionally creating it or installing pre-existing key and
629 Certificate creation in Elpher requires an installation of OpenSSL, and
630 ---in particular---that Elpher be able to run the @command{openssl} command-line
631 utility. By default, Elpher assumes that the @command{openssl} is on the
632 system path, but the precise location can be set by customizing the
633 @code{elpher-openssl-command} variable.
635 Each generated certificate results in the creation of a .key file and
636 a .crt file. In the case of a throwaway certificate, these files are
637 stored in the temporary directory indicated by the Emacs variable
638 @code{temporary-file-directory} and are deleted when ``forgotten''
639 (as described below).
641 In the case of persistent certificates, these files are stored in the
642 folder defined by the Elpher variable
643 @code{elpher-certificate-directory}, and are never deleted by Elpher.
644 (Of course you can delete them yourself whenever you like.)
645 The base name of the files (i.e. sans extension) is what Elpher uses
646 to identify the certificate.
648 Using throwaway certificates is as simple as pressing the @key{t}
649 key at the prompt which appears following a certificate request from
650 a server. There is nothing more to do.
652 Using a persistent certificate requires instead selecting @key{p} from the same
653 menu. This will result in Elpher asking you for the name identifying
654 the certificate. This entry autocompletes to the list of known certificate
655 names, so you can use @key{TAB} to display the list.
657 In the case that you choose a name that does not belong to the list of
658 known certificates, Elpher will offer to create one for you or to
659 ``install'' one from existing key and certificate files.
660 Pressing the @key{n} key will cause Elpher to begin the process of
661 creating a new persistent certificate, using some additional
662 details for which you will be prompted.
663 Alternatively, pressing the @key{i} key will cause Elpher to ask for the
664 locations of existing key and certificate files to add to
665 @code{elpher-certificate-directory} under the chosen name.
667 Once a certificate is selected, it will be used for all subsequent
668 gemini requests involving URLs begining with the URL for for which the
669 certificate was created. It is immediately ``forgotten'' when a TLS
670 connection to a non-matching URL is attempted, or the following command
674 @keycmd{@key{F},elpher-forget-certificate}
675 Causes Elpher to immediately forget any currently-loaded client certificate.
678 In either case, ``forgetting'' means that the details of the key and
679 certificate file pair are erased from memory. Furthermore, in the case
680 of throw-away certificates, the corresponding files are deleted.
682 Persistant client certificates can be added to the alist contained in the
683 customization variable @code{elpher-certificate-map} so that they are
684 automatically activated whenever a gemini page with the matching URL
687 @node Hiding preformatted text in text/gemini documents, , Client Certificates for Gemini, Gemini support
688 @section Hiding preformatted text in text/gemini documents
690 Preformatted text is often used to display ``ASCII art'' or other
691 similar text-based artwork. While for many this is a fun way to
692 introduce personality into their gemini documents, such text can
693 pose difficulties for screen readers.
695 Setting the @code{elpher-gemini-hide-preformatted} customization option
696 to non-nil causes Elpher to hide all preformatted text blocks by
697 default. In place of the preformatted text, Elpher instead displays the
698 ``alt text'' (if any is available), along with a button which can be
699 used to make specific blocks visible as required.
701 Other related customization options are
702 @code{elpher-gemini-preformatted-toggle-label}, which is the label used
703 for the toggle button, and
704 @code{elpher-gemini-preformatted-toggle-bullet}, which is the margin
705 string used to distinguish the line replacing the preformatted text.
707 @node Finger support, Local files, Gemini support, Top
708 @chapter Finger support
710 Incidentally, Elpher has native support for querying finger servers.
711 Of course, one could argue that this functionality is more easily
712 provided by one's local telnet client. However finger URLs do appear
713 on occasion in gopherspace, and it's nice to be able to open them
716 Elpher interprets @code{finger://} URLs as follows:
721 The host is determined by the host name portion of the URL.
724 In the case that the @emph{file name} portion of the URL is non-empty (besides
725 the leading slash), this is interpreted as the user to finger.
728 Otherwise, the @emph{user} portion of the URL is interpreted as the user to finger.
731 If no user is provided, the root directory of the finger server is requested.
735 Thus @code{finger://user@@hostname} and @code{finger://hostname/user} are both equivalent.
737 (The precedence of the /user notation over the user@ notation reflects a
738 preference of the community.)
740 @node Local files, About pages, Finger support, Top
743 Elpher supports opening local files via @samp{file:} URLs.
745 For instance, pressing @key{g} and entering @code{file:~/document.gmi}
746 will load the file named @samp{document.gmi} in your home directory,
747 provided this file exists.
749 Files opened in this way are rendered according to their name, and in
750 particular their extension. The current mappings are as follows:
756 Plain text documents. All local text files are assumed to be
759 @item @samp{gophermap},@samp{gopher}
761 Gophermap files, i.e. files containing a valid directory list as specified
764 @item @samp{gemini},@samp{gmi}
766 Gemini documents (i.e. documents of MIME type ``text/gemini''). All
767 local gemini files are assumed to be UTF-8-encoded.
769 @item @samp{html},@samp{htm}
771 HTML documents. All local HTML files are assumed to be UTF-8-encoded.
773 @item @samp{png},@samp{jpg},@samp{jpeg},@samp{gif},@samp{bmp},@samp{tif},@samp{tiff}
778 A binary document, which elpher will simply offer to save somewhere
779 else. (Obviously this is not useful in its own right, but there's not
780 much that elpher can sensibly do with unknown binary files.)
785 @node About pages, ANSI support, Local files, Top
788 Like other browsers, elpher makes certain internally-generated pages
789 such as the initial welcome page, the bookmarks page, the history
790 stack and the list of visited pages pages accessible as URLs with
793 This means that these pages can be bookmarked and, more usefully,
794 added to a local file to be rendered as a user-defined start page.
796 To see the address of a special page, simply visit the page and
799 @node ANSI support, Customization, About pages, Top
800 @chapter ANSI support
802 Depending on which parts of the gopher/gemini universe you frequent,
803 you may occasionally stumble on sites which use ANSI escape codes to
804 either produce specific characters or to colour text.
806 By default, elpher uses Emacs' built-in ANSI rendering library,
807 @samp{ansi-color}, to process ANSI codes. This robustly interprets
808 the escape codes but only supports 8 colours. Any colours unsupported
809 by the library are simply stripped, leaving uncoloured text in the
812 To drastically improve the number of colours produced, install the
813 @samp{xterm-color} package from MELPA. This package will be automatically
814 used by elpher if it is available, and supports 256 colours.
815 This should be sufficient to properly render many ANSI colour
816 gopher holes and gemini capsules quite nicely.
818 In case you prefer to completely strip out the ANSI escape codes entirely
819 by customizing the @code{elpher-filter-ansi-from-text} variable.
822 @node Customization, Command Index, ANSI support, Top
823 @chapter Customization
825 Various parts of Elpher can be customized via the
826 variables belonging to the elpher customization group, accessible
830 @kbd{M-x customize-group elpher @key{RET}}
833 @noindent This group contains a number of faces that can be modified to change
834 the appearance of Elpher, including one face per menu item type.
836 The group also contains variables for customizing the behaviour of
837 Elpher. This includes how to open arbitrary (non-gopher) URLs, whether
838 to display buffer headers, how to deal with ANSI escape sequences in
839 text, the timeout to impose on network connections, and whether to
840 prompt for confirmation when switching away from TLS.
842 One particularly important customization is the @code{elpher-start-page-url}
843 variable, which holds the URL of the page displayed initially when
844 elpher starts, and when @key{U} is pressed. By default this is set to
845 @samp{about:welcome}, but any URL can be substituted. For example, you
846 might want to create a text/gemini file named
847 @samp{~/.emacs/start-page.gmi} containing useful links and set the value
848 of @code{elpher-start-page-url} to @samp{file:~/.emacs/start-page.gmi} to have
849 these links displayed at startup. Alternatively, you might prefer
850 to set the value to @samp{about:bookmarks} so that the bookmarks page
851 is used as the start page instead.
853 See the customization group itself for details.
855 @node Command Index, News, Customization, Top
856 @unnumbered Command Index
860 @node News, Contributors, Command Index, Top
863 This chapter documents the major changes introduced by Elpher releases.
875 @node v3.6.0, v3.5.0, News, News
878 @subsection Easily open links in new buffer
880 This version includes the ability to open all link types in
881 Elpher documents in a new buffer. By default, this is bound
882 to S-@key{RET} and S-@key{mouse-1}, but this can be modified
883 by adding adjusting the bindings in @code{elpher-link-keymap}.
885 @node v3.5.0, v3.4.0, v3.6.0, News
888 @subsection Automatic activation of client certificates in gemini
890 This version introduces a new customization variable
891 @code{elpher-certificate-map} which allows you to pre-specify
892 a set of gemini URLs and the client certificates which should
893 be used when accessing them.
895 @xref{Client Certificates for Gemini} for more details.
897 @node v3.4.0, v3.3.0, v3.5.0, News
900 @subsection Toggling preformatted text visibility
902 This version introduces the ability to hide preformatted text in
903 text/gemini documents by default. To enable this, set the customization
904 variable @code{elpher-gemini-hide-preformatted} to non-nil. This causes
905 all preformated text blocks to be replaced with their ``alt-text'' (if
906 any is available) and a button for toggling the visibility of the text
909 This feature is intended to make it easier for people using screen
910 readers to read text/gemini documents.
912 @node v3.3.0, v3.2.0, v3.4.0, News
915 This version includes lots of bug fixes, as well as a couple of new
918 @subsection Local gophermaps
920 Local gophermaps can now be displayed using @samp{file:}. To render
921 correctly, they must have the suffix @samp{.gopher} or @samp{.gophermap}.
923 @subsection IRI support
925 Internationalized Resource Identifiers (IRI) are an extension of URLs
926 (or, more accurately, URIs) to support a larger set of characters beyond
927 those in the US-ASCII character set. They map directly onto URIs for
928 backwards compatibility, but look like gibberish if not properly
929 decoded. When displaying URLs, Elpher now automatically decodes any IRI
930 characters and displays the decoded IRI. (For security reasons, the
931 @code{elpher-info-current} command (@kbd{I}) always displays both the
932 decoded IRI and the URI when they differ.)
934 @node v3.2.0, v3.1.0, v3.3.0, News
937 This version introduces several minor changes which, together, make it
938 possible to set up alternative start pages configured to your liking.
940 @subsection About pages
942 Special elpher pages such as the welcome page (previously ``start''
943 page), the bookmarks page, the browsing history stack and list of
944 visited pages are now addressable via @samp{about:} URLs. For instance,
945 the standard welcome page has the address @samp{about:welcome}.
947 @subsection Local files
949 Local files can now be opened in elpher using @samp{file:} URLs. For
950 example, @kbd{g @samp{file:~/my-start.gmi}} will open
951 @samp{~/my-start.gmi} as a text/gemini document. @pxref{Local files}
954 @subsection Customizable start pages
956 The new customization variable @code{elpher-start-page-url} contains the URL
957 of the document to be loaded as elpher's ``start page''. By default
958 this is set to @samp{about:welcome}, but any elpher-accessible URL is
959 valid. @pxref{Customization} for suggestions.
961 @node v3.1.0, v3.0.0, v3.2.0, News
964 @subsection Bookmarks system
966 While Elpher bookmarks are still handled by the Emacs bookmark
967 system, this release introduces the option to retain the
968 original elpher bookmark page for the purpose of visiting those
969 bookmarks. In v3.1.0, @key{B} visits this page (and adds it to
970 the history stack, as in previous versions), which can be interacted
971 with using the standard elpher key bindings.
973 Of course you can still view the bookmarks in the Emacs bookmark
974 menu, which you can access from anywhere using the default
975 binding @kbd{C-x r l} (or by following the link from the Elpher bookmarks
976 page). Indeed you will need to use this to rename, delete or otherwise
979 If you prefer to avoid using the Elpher bookmark page entirely, you
980 use the customization variable @code{elpher-use-emacs-bookmark-menu}
981 to have the @key{B} key open the Emacs bookmark menu directly, as in
982 the previous release.
984 @node v3.0.0, , v3.1.0, News
987 @subsection Bookmarks system
989 Bookmarks are now handled by Emacs' own bookmark management system,
990 instead of Elpher's own system.
991 (For details, @xref{Bookmarks, , , emacs, The Emacs Editor}.)
992 This means two things. Firstly,
993 the bookmarks file (elpher-bookmarks by default) and format used by
994 previous versions are now deprecated. If these are detected, Elpher
995 will offer to import your old bookmarks when you first accessing the
996 bookmark list with the new version. A suffix will be added to your
997 old bookmarks file so that Elpher knows that the import is complete.
999 Secondly, the old Elpher bookmark menu has been removed in the new
1000 version. Instead, @key{B} brings up the menu provided by the Emacs
1001 function @code{bookmark-bmenu-list}. This has different key and mouse
1002 bindings to Elpher's old menu, but is much more functional. Bookmarks
1003 can be renamed, deleted in groups, and much more. (Use @kbd{C-h m} with
1004 the menu open to see the complete list.)
1008 Browsing history can now be accessed via new bindings to @key{s} and @key{S}.
1009 The former shows the current history ``stack'' (pages accessible with
1010 the @key{u} key), while the latter shows a list of all pages which have
1011 been visited in the current session.
1013 @subsection Socks connections
1015 Elpher can now use socks connections to browse via TOR.
1017 @subsection browse-url, Org and mu4e integration
1019 These integrations provide support for elpher-handling of gemini, gopher
1020 and finger URLs using @code{browse-url}, in Org documents, and the mu4e
1023 @subsection imenu integration
1025 Gemini document headers are now navigable via imenu.
1026 For details, @xref{Imenu, , , emacs, The Emacs Editor}.
1028 @node Contributors, , News, Top
1029 @chapter Contributors
1031 Elpher was originally written and is currently maintained by Tim Vaughan
1032 @email{plugd@@thelambdalab.xyz}. Significant improvements and
1033 maintenance have also been contributed by and with the help of Alex
1034 Schroeder @email{alex@@gnu.org}. In addition, the following people have
1035 all generously provided assistance and/or patches:
1038 @item Jens Östlund @email{jostlund@@gmail.com}
1039 @item F. Jason Park @email{jp@@neverwas.me}
1040 @item Christopher Brannon @email{chris@@the-brannons.com}
1041 @item Omar Polo @email{op@@omarpolo.com}
1042 @item Noodles! @email{nnoodle@@chiru.no}
1043 @item Abhiseck Paira @email{abhiseckpaira@@disroot.org}
1044 @item Zhiwei Chen @email{chenzhiwei03@@kuaishou.com}
1045 @item condy0919 @email{condy0919@@gmail.com}
1046 @item Alexis @email{flexibeast@@gmail.com}
1047 @item Étienne Deparis @email{etienne@@depar.is}
1048 @item Simon Nicolussi @email{sinic@@sinic.name}
1049 @item Michel Alexandre Salim @email{michel@@michel-slm.name}
1050 @item Koushk Roy @email{kroy@@twilio.com}
1051 @item Vee @email{vee@@vnsf.xyz}
1052 @item Simon South @email{simon@@simonsouth.net}
1053 @item Daniel Semyonov @email{daniel@@dsemy.com}
1054 @item Bradley Thornton @email{bradley@@northtech.us}