1 \input texinfo @c -*-texinfo-*-
3 @setfilename elpher.info
4 @settitle Elpher Manual v3.2.2
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, 2020, 2021 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 FITNElpher 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 * Customization:: How to customize various aspects of Elpher
62 * News:: Changes introduced by major releases
63 * Acknowledgements:: Contributors to Elpher
66 --- The Detailed Node Listing ---
70 * Within-page navigation:: Moving about within a page
71 * Between-page navigation:: Commands for moving between pages
72 * History and Caching:: Explanation of how Elpher represents history
79 @macro keycmd{key,cmd}
80 @item \key\ (@code{\cmd\})
84 @node Introduction, Installation, Top, Top
87 Elpher aims to be a capable and practical gopher and gemini client for
88 Emacs. Its focus is on easy keyboard-driven navigation based on
89 sensible default bindings (with out-of-the-box support for Evil). It is
90 intended to be robust and behave in non-surprising ways at all times.
91 Additionally, Elpher provides the following bells and whistles:
95 followable web and gopher links in plain text,
98 an easily navigable history, sporting caching of visited pages (both
99 content and cursor position),
102 auto-completing menu item navigation,
105 direct visualization of image files where supported (no writing to
109 basic support for the new ``heavier than gopher, lighter than the web'' Gemini protocol,
112 support for the Finger protocol.
116 Elpher is still under active development. Although we try very hard to
117 ensure that releases are bug-free, this cannot be guaranteed. However,
118 this also means that any usability features that you feel are missing
119 can likely by incorporated quickly, so please get in touch if you
122 @node Installation, Quick Start, Introduction, Top
123 @chapter Installation
125 Elpher is available from the MELPA package repository. If you have
126 never installed packages from this repository before, you'll need
127 to follow the instructions at @url{https://melpa.org/#/getting-started}.
129 @noindent To install Elpher, enter the following:
132 @kbd{M-x package-install @key{RET} elpher @key{RET}}
135 @noindent To uninstall, use
138 @kbd{M-x package-delete @key{RET} elpher @key{RET}}.
141 It is also possible to install Elpher directly by downloading the file
142 @file{elpher.el} from @url{gopher://thelambdalab.xyz/1/projects/elpher}
143 (you'll need to download the ``source archive'' and extract it), adding
144 it to a directory in your @code{load-path}, and then adding
150 @noindent to your Emacs initialization file.
152 @node Quick Start, Navigation, Installation, Top
155 Before diving into the minutiae of the different commands available,
156 we will quickly describe how to get up and running with Elpher.
158 Once installed, you can launch Elpher using
161 @kbd{M-x elpher @key{RET}}
164 @noindent This will switch to the *Elpher* buffer and display a start
165 page, with information on each of the default keyboard bindings.
167 From here you can move point between links (which may be menu items or
168 inline URLs in text files) by using @key{TAB} and @kbd{S-@key{TAB}},
169 as in Info. You can also jump directly to a menu item using @key{m}, or
170 use the standard Emacs or Evil motion and search commands to find your
171 way around. To open a link, press @key{RET}. (Where a mouse is
172 available, Clicking on a link with the mouse cursor has the same
175 To return to the page you just followed the link from, press @key{u}.
177 Elpher caches (for the duration of an Emacs session) both page contents
178 and the position of point on each of the pages (gopher menus, gemini
179 pages, query results, or text pages) you visit, restoring these when you
180 next visit the same page. Thus, pressing @key{u} displays the previous
181 page in exactly the same state as when you left, meaning that you can
182 quickly and visually explore the different documents in a menu without
183 having to wait for anything to reload.
185 Of course, sometimes you'll @emph{want} to reload the current page
186 rather than stick with the cached version. To do this use @key{R}.
187 (This is particularly useful for search query results, where this
188 allows you to perform a different search.)
190 That's more-or-less it. Elpher supports a number of other features,
191 such a support for different coding schemes and TLS encryption, and a
192 variety of customization options, all of which are explained in the
193 rest of this document. However the emphasis is on keeping the basic
194 navigation experience as intuitive and responsive as possible.
196 Note that you can launch multiple Elpher sessions in parallel by using
200 @kbd{C-u M-x elpher @key{RET}}
203 @node Navigation, Bookmarks, Quick Start, Top
205 Throughout this manual, we use the word ``page'' to refer to any
206 visualization of a response from a gopher or gemini server, be it a
207 menu/directory, query result, text file or image.
209 Elpher's navigation interface is inspired by the Emacs Info mode.
210 Movement within a page is essentially the same as moving
211 around any other text file in Emacs, but with special keys
212 for quickly jumping between menu items and URLs in text files.
213 Movement between pages is facilitated by a simple linear history
214 coupled with caching of pages and cursor position.
217 * Within-page navigation:: Moving about within a page
218 * Between-page navigation:: Commands for moving between pages
219 * History and Caching:: Explanation of how Elpher represents history
223 @node Within-page navigation, Between-page navigation, Navigation, Navigation
224 @section Within-page navigation
226 To move about within a page, you should be able use the same keys you usually
227 use to browse files in Emacs. This is even true when Evil mode is
228 enabled. Paragraph hopping, searching etc should work as usual.
230 In addition, the following commands are provided for quickly moving between
231 links and menu items.
234 @keycmd{@key{TAB}, elpher-next-link}
235 Move to the next link or menu item in the file.
237 @item @kbd{Shift-@key{TAB}} or @key{BACKTAB} (@code{elpher-prev-link})
238 @findex elpher-prev-link
239 Move to the previous link or menu item in the file.
241 @keycmd{@key{m}, elpher-jump}
242 Jump directly to a link within a file by specifying its display string
243 or link text. (Unlike the previous two commands, this immediately opens
248 The following commands can be used to retrieve information about the
249 current page, or the address of the link at point:
252 @keycmd{@key{i}, elpher-info-link}
253 Display host, port and selector information for the link at point.
255 @keycmd{@key{I}, elpher-info-current}
256 Display host, port and selector information for the current page.
258 @keycmd{@key{c}, elpher-copy-link-url}
259 Add URL representing address of link at point to the kill-ring and the
260 system clipboard (if available).
262 @keycmd{@key{C}, elpher-copy-current-url}
263 Add URL representing address of the current page to the kill-ring and
264 the system clipboard (if available).
266 @keycmd{@key{d}, elpher-download}
267 Download link at point and save the result as a file. The minibuffer
268 will prompt for the name of the file to write, with the default name being
269 the display string (if available) associated with the link.
271 @keycmd{@key{D}, elpher-download-current}
272 This is similar to @code{elpher-download}, but instead applies to the
273 current page rather than a link.
275 @keycmd{@key{.}, elpher-view-raw}
276 This displays the raw server response for the current page. While not
277 useful for general browsing, it is useful for debugging incorrect rendering
278 or out-of-spec server responses.
281 @node Between-page navigation, History and Caching, Within-page navigation, Navigation
282 @section Between-page navigation
284 Moving to a different page can be accomplished in several ways,
285 described by the following command:
288 @keycmd{@key{RET}\, @key{mouse-1}, elpher-follow-link}
289 Follow the menu item or link at point (or selected with the mouse).
291 Exactly what is meant by ``follow'' depends on the kind of item selected:
295 For text or menu type items or links, the current page text is replaced
296 by the text of this item. Unless the customization variable
297 @code{elpher-use-header} (@pxref{Customization}) is
298 @code{nil}, the display string of the link is displayed in the buffer header.
299 Links to images behave similarly on Emacs systems supporting the display of
300 bitmap graphics, however their content is not cached in memory by default.
303 When followed, links to search/query items (type 7) prompt for input in
304 the minibuffer then display the results in the same way as for text and menu
308 Following links to binary files (and image files on unsupported systems)
309 causes Elpher to prompt for a filename in which to save the content.
312 Following links of type `h' with a selector having the `URL:' prefix, or
313 unsuported URLs in text files, will result in Elpher using an external
314 programme to open the URL. This will be either the default system browser
315 or, if the @code{elpher-open-urls-with-eww} customization variable is non-nil,
316 Emacs' own EWW browser. (See @pxref{Customization}.)
320 Once a text, menu or query response page has been displayed, its contents are
321 cached for the duration of the Emacs session.
323 @keycmd{@key{g}, elpher-go}
324 Open a particular page by specifying either its full URL or just
325 entering a gopher host name. (The protocol defaults to gopher, so gemini
326 links must include the @code{gemini://} prefix.
328 If a unsupported protocol is used in the URL the result will be the same
329 as following a URL link of the same type from a link in a page.
331 @keycmd{@key{o}, elpher-go-current}
332 Prompts for a URL similar to @code{elpher-go}, but initialized to the URL
333 of the current page. This allows you to easily try other selectors for the
336 Remember however, that the Gopher RFC 1436 provides @emph{no} guarantees about the
337 structure of selectors.
339 @keycmd{@key{O}, elpher-root-dir}
340 Open the root page (empty selector) on the current host.
342 @keycmd{@key{u}\, @key{-}\, @key{^}\, @key{mouse-3}, elpher-back}
343 Return to the previous page, where ``previous'' means the page where the
344 page which was displayed immediately before the current page.
348 @node History and Caching, , Between-page navigation, Navigation
349 @section History and Caching
351 The history and caching strategy in Elpher is extremely simple, but
352 may be confusing without a good mental model of how it works. That
353 is what this section attempts to provide.
355 Essentially, @strong{every} time you navigate to a new page, either
356 by clicking or pressing @key{RET} on a link, using @key{g} to jump
357 to a new page by its address, or using @key{O} to open the root selector,
358 the following two things occur:
362 the cursor position and content for the original page are recorded in an
366 the original page is set as the ``parent'' of the new page.
369 The only way to return to pages in this history is by using @key{u},
370 which returns to the previous of the current page. @footnote{The
371 addition of the new page to the history happens even if the new page is
372 one that has been seen before. This is mostly the desired behaviour.
373 However, opening an explicit ``back'' link provided by a gopher menu or
374 gemini page will also add a new entry to the history. Unless you
375 haven't yet visited that menu, it's therefore better to use @key{u} to
376 go back in this case.}
378 One aspect that may seem peculiar is that Elpher lacks a corresponding ``next'' or
379 ``forward'' command. However, since Elpher caches the position of point,
380 this will be automatically positioned on the link that was most recently followed
381 from a given page. This means that, at least for links followed from menus
382 and text files, the inverse of @key{u} is actually just @key{RET}.
384 Elpher actually maintains two histories, and there are two different
385 commands to access them:
388 @keycmd{@key{s}, elpher-show-history}
389 This shows the history of the current buffer. This shows all the links
390 you would visit if you were to use @key{u} again and again.
392 @keycmd{@key{S}, elpher-show-visited-pages}
393 This shows the entire Elpher browsing history. It includes all the
394 pages you visited in your current Emacs session.
398 @node Bookmarks, Gopher character encodings, Navigation, Top
401 Elpher makes use of standard Emacs bookmarks.
402 @xref{Bookmarks, , , emacs, The Emacs Editor}.
403 The following commands are used to add new bookmarks:
406 @keycmd{@key{a}, elpher-bookmark-link}
407 Add a bookmark for the link at point. The minibuffer will prompt for
408 a name for the bookmark, which defaults to the display string.
410 @keycmd{@key{A}, elpher-bookmark-current}
411 Add a bookmark for the current page. The minibuffer will prompt for
412 a name for the bookmark, defaulting to the display string associated
413 with the link that was followed to reach the current page.
416 @keycmd{@key{B}, elpher-open-bookmarks}
417 Visit a page displaying all elpher bookmarks.
418 The behaviour of the this function depends on the customization variable
419 @code{elpher-use-emacs-bookmark-menu}. If nil (the default), the
420 command will visit a special elpher page listing all elpher-specific
421 bookmarks. If non-nil, the command will simply open the standard Emacs
422 bookmark list displaying all current bookmarks (including non-elpher
425 @keycmd{@kbd{C-x r l}, bookmark-bmenu-list}
426 This command opens the standard Emacs bookmark menu, with which bookmarks
427 can be renamed, deleted or annotated.
431 On opening the bookmarks page, elpher will offer to import any legacy
432 (2.x) bookmarks files into the new system. Once the import is complete,
433 the original bookmarks file will have ``-legacy'' appended to it, so
434 so that elpher knows not to import it again.
436 If you have any other legacy bookmark files (besides the one in the
437 original location, or specified in the @code{elpher-bookmarks-file}
438 customization variable, which should be automatically detected), you can
439 can import these using
442 @kbd{M-x elpher-bookmark-import @key{RET}}
445 Once this is done, you may delete these legacy bookmarks files.
447 @node Gopher character encodings, Encrypted gopher connections, Bookmarks, Top
448 @chapter Gopher character encodings
450 Responses Elpher retrieves from servers are initially read as pure
451 binary data. When the data is intended to be interpreted as textual (as
452 determined by the type parameter of the gopher menu item or the gopher
453 URL), this data needs to be @emph{decoded} into a sequence of
454 characters. To do this properly requires knowledge of the encoding
455 system used by whoever authored the document.
457 Unfortunately gopher lacks a systematic way of acquiring this necessary
458 information. Thus, the details of the coding system must be either
459 inferred from the binary data, or must be specified by the user.
461 By default, Elpher applies Emacs' built-in character encoding detection
462 system to the full (undecoded) response data and uses this to attempt to
463 convert it into a character string.
464 (See @pxref{Recognize coding, Recognizing coding systems, ,emacs}.) While
465 this approach can be okay, it is important to realize that its inference
466 algorithm is extremely primitive and depends heavily on assumptions based
467 on the language settings of your emacs system.
469 The alternative is to explicitly set the coding system used for decoding
470 using the following command:
473 @keycmd{@key{!},elpher-set-coding-system}
474 Causes a elpher to prompt for a coding system to use for decoding
475 future gopher text. The @key{TAB} key can be used at this prompt to display a
476 list of alternatives (which is extensive) and to auto-complete. An empty
477 response will cause Elpher to return to its default auto-detection
481 Note that changing the coding system only affects newly loaded text.
482 Thus, if text has already been decoded using an incorrect system, you
483 will need to select the correct coding and then reload the text using
487 @node Encrypted gopher connections, Gemini support, Gopher character encodings, Top
488 @chapter Encrypted gopher connections
490 While RFC 1436 does not broach the topic of encryption at all, several
491 modern gopher servers can serve content over encrypted connections,
492 and a common choice for this is TLS.
494 Elpher can retrieve selectors using Emacs' built-in TLS support which
495 uses the GnuTLS library. (It is possible to build emacs without
496 GnuTLS, in which case encryption is not supported.)
498 To retrieve documents using TLS, Elpher's TLS mode must be enabled.
499 This can be directly toggled using @key{T}, but note that just as with
500 the character encoding, changing this mode only affects subsequent
503 Alternatively, TLS mode is @emph{automatically} enabled whenever
504 gopher URLs starting with @code{gophers://} are followed.
506 The mode is sticky, so it remains active until switched off.
507 It can also be automatically switched off when a TLS connection fails.
508 In this case Elpher will prompt for your confirmation to ensure that
509 you can't accidentally make a non-TLS connection.
511 @node Gemini support, Finger support, Encrypted gopher connections, Top
512 @chapter Gemini support
514 @uref{gopher://gemini.circumlunar.space, Gemini}
515 is a new protocol being developed by several members of
516 gopherspace. It aims to solve some of the long-standing technical
517 issues associated with gopher as a protocol, while keeping the major benefits.
518 For instance, it _requires_ encrypted connections, it does away with
519 the selector type, and allows servers to explicitly specify the
520 character coding scheme used for text documents.
522 The latest versions of Elpher aim to provide seamless transitions between
523 gemini and gopher documents. Basically you should be able to open,
524 bookmark, download and otherwise interact with gemini pages in exactly
525 the same way as you do with other non-gemini pages. The only major
526 difference from your perspective as a user is that you should no longer
527 have to worry about manually toggling TLS on or off (for gemini it's
528 always on), and you should never have to manually set a character coding
531 The gemini protocol specification recommends a Trust on First Use (TOFU)
532 behaviour when validating gemini server TLS certificates. This is
533 because many gemini servers rely on self-signed certificates rather
534 than certificates signed by a CA. Sadly however, this TOFU behaviour is
535 far from straight-forward to configure using Emacs' existing Network
536 Security Manager. For this reason, elpher defaults to performing no
537 certificate verification by default. This behaviour can be easily
538 customized by setting the @code{elpher-gemini-TLS-cert-checks}
539 customization variable to non-nil.
541 The gemini specification concerns both the protocol and a simple text
542 document format (mimetype text/gemini) which is like a mixture between
543 gophermap files and markdown-formatted files but simpler than both.
544 Elpher renders gemini responses which are provided in this format in
545 line with the rules in the spec. This includes wrapping long lines at
546 word boundaries. The specific column at which this text is wrapped is
547 defined by the customization variable
548 @code{elpher-gemini-max-fill-width}, which is set to 80 columns by
549 default. (This is slightly wider than Emacs' default fill width of 70
550 columns due to the fact that there are a significant amount of older
551 gemini content which, against the advice of the current spec, hard wraps
552 at <80 columns. The larger default allows this to still look okay,
553 while still keeping content without hard wraps looking pleasant.)
555 The text/gemini format also possesses a section header syntax similar to
556 markdown. Elpher allows different header levels to be drawn with
557 different, customizable, faces. By default, on graphically-capable
558 emacs systems, these faces are given different heights to distinguish
559 among levels. On terminal systems, the level is indicated by the
560 number of preceding # symbols.
562 I should emphasize however that, while it is definitely functional,
563 Elpher's gemini support is still experimental, and various aspects will
564 change as the protocol develops further.
566 @section Client Certificates for Gemini
568 Gemini makes explicit use of the client certificate mechanism that TLS
569 provides for allowing clients to authenticate themselves with servers.
570 The Gemini specification suggests two distinct classes of client
571 certificates: short-lived certificates used to identify you for a single
572 session, and more permanent certificates used to identify you over a
575 When Elpher receives a request for a client certificate from a server,
576 it will present you with the option to create and use a single-use
577 ``throwaway'' certificate, or to use a ``persistent''
578 certificate (optionally creating it or installing pre-existing key and
581 Certificate creation in Elpher requires an installation of OpenSSL, and
582 ---in particular---that Elpher be able to run the @command{openssl} command-line
583 utility. By default, Elpher assumes that the @command{openssl} is on the
584 system path, but the precise location can be set by customizing the
585 @code{elpher-openssl-command} variable.
587 Each generated certificate results in the creation of a .key file and
588 a .crt file. In the case of a throwaway certificate, these files are
589 stored in the temporary directory indicated by the Emacs variable
590 @code{temporary-file-directory} and are deleted when ``forgotten''
591 (as described below).
593 In the case of persistent certificates, these files are stored in the
594 folder defined by the Elpher variable
595 @code{elpher-certificate-directory}, and are never deleted by Elpher.
596 (Of course you can delete them yourself whenever you like.)
597 The base name of the files (i.e. sans extension) is what Elpher uses
598 to identify the certificate.
600 Using throwaway certificates is as simple as pressing the @key{t}
601 key at the prompt which appears following a certificate request from
602 a server. There is nothing more to do.
604 Using a persistent certificate requires instead selecting @key{p} from the same
605 menu. This will result in Elpher asking you for the name identifying
606 the certificate. This entry autocompletes to the list of known certificate
607 names, so you can use @key{TAB} to display the list.
609 In the case that you choose a name that does not belong to the list of
610 known certificates, Elpher will offer to create one for you or to
611 ``install'' one from existing key and certificate files.
612 Pressing the @key{n} key will cause Elpher to begin the process of
613 creating a new persistent certificate, using some additional
614 details for which you will be prompted.
615 Alternatively, pressing the @key{i} key will cause Elpher to ask for the
616 locations of edisting key and certificate files to add to
617 @code{elpher-certificate-directory} under the chosen name.
619 Once a certificate is selected, it will be used for all subsequent TLS
620 transactions to the host for which the certificate was created.
621 It is immediately ``forgotten'' when a TLS connection to another host
622 is attempted, or the following command is issued:
625 @keycmd{@key{F},elpher-forget-certificate}
626 Causes Elpher to immediately forget any currently-loaded client certificate.
629 In either case, ``forgetting'' means that the details of the key and
630 certificate file pair are erased from memory. Furthermore, in the case
631 of throw-away certificates, the corresponding files are deleted.
634 @node Finger support, Local files, Gemini support, Top
635 @chapter Finger support
637 Incidentally, Elpher has native support for querying finger servers.
638 Of course, one could argue that this functionality is more easily
639 provided by one's local telnet client. However finger URLs do appear
640 on occasion in gopherspace, and it's nice to be able to open them
643 Elpher interprets @code{finger://} URLs as follows:
648 The host is determined by the host name portion of the URL.
651 In the case that the @emph{file name} portion of the URL is non-empty (besides
652 the leading slash), this is interpreted as the user to finger.
655 Otherwise, the @emph{user} portion of the URL is interpreted as the user to finger.
658 If no user is provided, the root directory of the finger server is requested.
662 Thus @code{finger://user@@hostname} and @code{finger://hostname/user} are both equivalent.
664 (The precedence of the /user notation over the user@ notation reflects a
665 preference of the community.)
667 @node Local files, About pages, Finger support, Top
670 Elpher supports opening local files via @samp{file:} URLs.
672 For instance, pressing @key{g} and entering @code{file:~/document.gmi}
673 will load the file named @samp{document.gmi} in your home directory,
674 provided this file exists.
676 Files opened in this way are rendered according to their name, and in
677 particular their extension. The current mappings are as follows:
683 Plain text documents. All local text files are assumed to be
686 @item @samp{gophermap},@samp{gopher}
688 Gophermap files, i.e. files containing a valid directory list as specified
691 @item @samp{gemini},@samp{gmi}
693 Gemini documents (i.e. documents of MIME type ``text/gemini''). All
694 local gemini files are assumed to be UTF-8-encoded.
696 @item @samp{html},@samp{htm}
698 HTML documents. All local HTML files are assumed to be UTF-8-encoded.
700 @item @samp{png},@samp{jpg},@samp{jpeg},@samp{gif},@samp{bmp},@samp{tif},@samp{tiff}
705 A binary document, which elpher will simply offer to save somewhere
706 else. (Obviously this is not useful in its own right, but there's not
707 much that elpher can sensibly do with unknown binary files.)
712 @node About pages, Customization, Local files, Top
715 Like other browsers, elpher makes certain internally-generated pages
716 such as the initial welcome page, the bookmarks page, the history
717 stack and the list of visited pages pages accessible as URLs with
720 This means that these pages can be bookmarked and, more usefully,
721 added to a local file to be rendered as a user-defined start page.
723 @node Customization, Command Index, About pages, Top
724 @chapter Customization
726 Various parts of Elpher can be customized via the
727 variables belonging to the elpher customization group, accessible
731 @kbd{M-x customize-group elpher @key{RET}}
734 @noindent This group contains a number of faces that can be modified to change
735 the appearance of Elpher, including one face per menu item type.
737 The group also contains variables for customizing the behaviour of
738 Elpher. This includes how to open arbitrary (non-gopher) URLs, whether
739 to display buffer headers, how to deal with ANSI escape sequences in
740 text, the timeout to impose on network connections, and whether to
741 prompt for confirmation when switching away from TLS.
743 One particularly important customization is the @code{elpher-start-page-url}
744 variable, which holds the URL of the page displayed initially when
745 elpher starts, and when @key{U} is pressed. By default this is set to
746 @samp{about:welcome}, but any URL can be substituted. For example, you
747 might want to create a text/gemini file named
748 @samp{~/.emacs/start-page.gmi} containing useful links and set the value
749 of @code{elpher-start-page-url} to @samp{file:~/.emacs/start-page.gmi} to have
750 these links displayed at startup. Alternatively, you might prefer
751 to set the value to @samp{about:bookmarks} so that the bookmarks page
752 is used as the start page instead.
754 See the customization group itself for details.
756 @node Command Index, News, Customization, Top
757 @unnumbered Command Index
761 @node News, Acknowledgements, Command Index, Top
764 This chapter documents the major changes introduced by Elpher releases.
768 This version introduces several minor changes which, together, make it
769 possible to set up alternative start pages configured to your liking.
771 @subsection About pages
773 Special elpher pages such as the welcome page (previously ``start''
774 page), the bookmarks page, the browsing history stack and list of
775 visited pages are now addressible via @samp{about:} URLs. For instance,
776 the standard welcome page has the address @samp{about:welcome}.
778 @subsection Local files
780 Local files can now be opened in elpher using @samp{file:} URLs. For
781 example, @kbd{g @samp{file:~/my-start.gmi}} will open
782 @samp{~/my-start.gmi} as a text/gemini document. @pxref{Local files}
785 @subsection Customizable start pages
787 The new customization variable @code{elpher-start-page-url} contains the URL
788 of the document to be loaded as elpher's ``start page''. By default
789 this is set to @samp{about:welcome}, but any elpher-accessible URL is
790 valid. @pxref{Customization} for suggestions.
794 @subsection Bookmarks system
796 While Elpher bookmarks are still handled by the Emacs bookmark
797 system, this release introduces the option to retain the
798 original elpher bookmark page for the purpose of visiting those
799 bookmarks. In v3.1.0, @key{B} visits this page (and adds it to
800 the history stack, as in previous versions), which can be interacted
801 with using the standard elpher key bindings.
803 Of course you can still view the bookmarks in the Emacs bookmark
804 menu, which you can access from anywhere using the default
805 binding @kbd{C-x r l} (or by following the link from the Elpher bookmarks
806 page). Indeed you will need to use this to rename, delete or otherwise
809 If you prefer to avoid using the Elpher bookmark page entirely, you
810 use the customization variable @code{elpher-use-emacs-bookmark-menu}
811 to have the @key{B} key open the Emacs bookmark menu directly, as in
812 the previous release.
816 @subsection Bookmarks system
818 Bookmarks are now handled by Emacs' own bookmark management system,
819 instead of Elpher's own system.
820 (For details, @xref{Bookmarks, , , emacs, The Emacs Editor}.)
821 This means two things. Firstly,
822 the bookmarks file (elpher-bookmarks by default) and format used by
823 previous versions are now deprecated. If these are detected, Elpher
824 will offer to import your old bookmarks when you first accessing the
825 bookmark list with the new version. A suffix will be added to your
826 old bookmarks file so that Elpher knows that the import is complete.
828 Secondly, the old Elpher bookmark menu has been removed in the new
829 version. Instead, @key{B} brings up the menu provided by the Emacs
830 function @code{bookmark-bmenu-list}. This has different key and mouse
831 bindings to Elpher's old menu, but is much more functional. Bookmarks
832 can be renamed, deleted in groups, and much more. (Use @kbd{C-h m} with
833 the menu open to see the complete list.)
837 Browsing history can now be accessed via new bindings to @key{s} and @key{S}.
838 The former shows the current history ``stack'' (pages accessible with
839 the @key{u} key), while the latter shows a list of all pages which have
840 been visited in the current session.
842 @subsection Socks connections
844 Elpher can now use socks connections to browse via TOR.
846 @subsection browse-url, Org and mu4e integration
848 These integrations provide support for elpher-handling of gemini, gopher
849 and finger URLs using @code{browse-url}, in Org documents, and the mu4e
852 @subsection imenu integration
854 Gemini document headers are now navigable via imenu.
855 For details, @xref{Imenu, , , emacs, The Emacs Editor}.
857 @node Acknowledgements, , News, Top
858 @chapter Acknowledgements
860 Elpher was originally written by Tim Vaughan. Recent maintenance has
861 been done by and with the help of Alex Schroeder. In addition, the
862 following people (in alphabetical order) have generously provided
863 assistance and/or patches:
867 @item Christopher Brannon
870 @item Étienne Deparis
872 @item Simon Nicolussi
879 @item Michel Alexandre Salim
881 @item Daniel Semyonov
883 @item Bradley Thornton