\input texinfo @c -*-texinfo-*-
@setfilename elpher.info
-@settitle Elpher Manual v2.7.0
+@settitle Elpher Manual v3.0.0
@dircategory Emacs
@direntry
-* Elpher: (elpher). A gopher and gemini client for Emacs.
+* Elpher: (elpher). A gopher and gemini client for Emacs.
@end direntry
@copying
This manual documents Elpher, a gopher and gemini client for Emacs.
-Copyright @copyright{} 2019 Tim Vaughan
+Copyright @copyright{} 2019, 2020, 2021 Tim Vaughan@*
+Copyright @copyright{} 2021 Daniel Semyonov@*
+Copyright @copyright{} 2021 Alex Schroeder
@quotation
The source and documentation of Elpher is free software. You can
@top Elpher
@insertcopying
-@end ifnottex
-
-@macro keycmd{key,cmd}
-@item \key\ (@code{\cmd\})
-@findex \cmd\
-@end macro
@menu
* Introduction:: Elpher Overview: what's this all about?
@end detailmenu
@end menu
+@end ifnottex
+
+@macro keycmd{key,cmd}
+@item \key\ (@code{\cmd\})
+@findex \cmd\
+@end macro
@node Introduction, Installation, Top, Top
@chapter Introduction
direct visualization of image files where supported (no writing to
disk),
-@item
-a bookmark management system,
-
@item
basic support for the new ``heavier than gopher, lighter than the web'' Gemini protocol,
@kbd{M-x package-delete @key{RET} elpher @key{RET}}.
@end example
-While not recommended, it is also possible to install Elpher directly by
-downloading the file @file{elpher.el} from
-@url{gopher://thelambdalab.xyz/1/projects/elpher/}, adding it to a directory in
-your @code{load-path}, and then adding
+While not recommended, it is also possible to install Elpher directly
+by downloading the file @file{elpher.el} from
+@url{https://alexschroeder.ch/cgit/elpher}, adding it to a directory
+in your @code{load-path}, and then adding
@example
(require 'elpher)
(This is particularly useful for search query results, where this
allows you to perform a different search.)
-That's more-or-less it. Elpher supports a number of other features, such
-as bookmarking, support for different coding schemes and TLS encryption,
-and a variety of customization options, all of which are explained in
-the rest of this document. However the emphasis is on keeping the basic
+That's more-or-less it. Elpher supports a number of other features,
+such a support for different coding schemes and TLS encryption, and a
+variety of customization options, all of which are explained in the
+rest of this document. However the emphasis is on keeping the basic
navigation experience as intuitive and responsive as possible.
+Note that you can launch multiple Elpher sessions in parallel by using
+a prefix:
+
+@example
+@kbd{C-u M-x elpher @key{RET}}
+@end example
+
@node Navigation, Bookmarks, Quick Start, Top
@chapter Navigation
Throughout this manual, we use the word ``page'' to refer to any
@keycmd{@key{TAB}, elpher-next-link}
Move to the next link or menu item in the file.
-@keycmd{@kbd{Shift-@key{TAB}}/@key{backtab}, @code{elpher-prev-link}}
+@item @kbd{Shift-@key{TAB}} or @key{BACKTAB} (@code{elpher-prev-link})
+@findex elpher-prev-link
Move to the previous link or menu item in the file.
@keycmd{@key{m}, elpher-jump}
the selected link.
@end table
+
The following commands can be used to retrieve information about the
current page, or the address of the link at point:
cached for the duration of the Emacs session.
@keycmd{@key{g}, elpher-go}
-Open a particular page by specifying either its full URL or just entering
-a gopher host name. (The protocol defaults to gopher, so gemini links must include the @code{gemini://} prefix.
+Open a particular page by specifying either its full URL or just
+entering a gopher host name. (The protocol defaults to gopher, so gemini
+links must include the @code{gemini://} prefix.
If a unsupported protocol is used in the URL the result will be the same
as following a URL link of the same type from a link in a page.
@keycmd{@key{O}, elpher-root-dir}
Open the root page (empty selector) on the current host.
-@keycmd{@key{u}\, @kbd{mouse-3}, elpher-back}
+@keycmd{@key{u}\, @key{-}\, @key{^}\, @kbd{mouse-3}, elpher-back}
Return to the previous page, where ``previous'' means the page where the
page which was displayed immediately before the current page.
@end table
from a given page. This means that, at least for links followed from menus
and text files, the inverse of @key{u} is actually just @key{RET}.
+Elpher actually maintains two histories, and there are two different
+commands to access them:
+
+@table @asis
+@keycmd{@key{s}, elpher-show-history}
+This shows the history of the current buffer. This shows all the links
+you would visit if you were to use @key{u} again and again.
+
+@keycmd{@key{S}, elpher-show-visited-pages}
+This shows the entire Elpher browsing history. It includes all the
+pages you visited in your current Emacs session.
+
+@end table
@node Bookmarks, Gopher character encodings, Navigation, Top
@chapter Bookmarks
-Elpher has a very simple link bookmarking system involving the
-following commands:
+Elpher makes use of standard Emacs bookmarks. @xref{Bookmarks, , ,
+emacs, The Emacs Editor}. The following commands are perhaps the most
+useful ones:
@table @asis
-@keycmd{@key{a}, elpher-bookmark-link}
+@keycmd{@key{a}, elpher-set-bookmark-no-overwrite}
Add a bookmark for the link at point. The minibuffer will prompt for
a name for the bookmark, which defaults to the display string.
-@keycmd{@key{A}, elpher-bookmark-current}
+@keycmd{@key{A}, bookmark-set-no-overwrite}
Add a bookmark for the current page. The minibuffer will prompt for
a name for the bookmark, defaulting to the display string associated
with the link that was followed to reach the current page.
-@keycmd{@key{x}, elpher-unbookmark-link}
-Immediately remove the bookmark (if one exists) to the link at point.
+@keycmd{@key{B}, bookmark-bmenu-list}
+Open a page displaying all current bookmarks. This is where you can
+delete and search bookmarks, for example.
-@keycmd{@key{X}, elpher-unbookmark-current}
-Immediately remove the bookmark (if one exists) to the current page.
-
-@keycmd{@key{B}, elpher-bookmarks}
-Open a page displaying all current bookmarks. Note that this bookmark
-page is added to the history just as if you had opened it using a link.
-Thus to return to the previous page, use @kbd{u}. This also means
-that you can peruse the various bookmarks by visiting them in turn,
-using @kbd{u} to return to the bookmark page (where the position of point
-is cached), then moving to another bookmarked link and so on.
@end table
-Bookmarks are stored as a s-exp in the file @file{elpher-bookmarks}
-in the user emacs directory (usually @file{~/.emacs.d/}).
-Any command which modifies the list of bookmarks immediately updates
-this file.
+If all your bookmarks disappeared in an upgrade from 2.10 to 2.11, you
+can import your old Elpher bookmarks into your Emacs bookmarks using
+
+@example
+@kbd{M-x elpher-bookmark-import @key{RET}}
+@end example
+
+Once this is done, you can delete the file with the Elpher bookmarks.
@node Gopher character encodings, Encrypted gopher connections, Bookmarks, Top
@chapter Gopher character encodings
using the following command:
@table @asis
-@keycmd{@key{S},elpher-set-coding-system}
+@keycmd{@key{!},elpher-set-coding-system}
Causes a elpher to prompt for a coding system to use for decoding
future gopher text. The @key{TAB} key can be used at this prompt to display a
list of alternatives (which is extensive) and to auto-complete. An empty
When Elpher receives a request for a client certificate from a server,
it will present you with the option to create and use a single-use
-``throwaway'' certificate, to create and use a new ``persistent''
-certificate, or to use an existing (persistent) certificate.
+``throwaway'' certificate, or to use a ``persistent''
+certificate (optionally creating it or installing pre-existing key and
+certificate files).
Certificate creation in Elpher requires an installation of OpenSSL, and
---in particular---that Elpher be able to run the @command{openssl} command-line
The base name of the files (i.e. sans extension) is what Elpher uses
to identify the certificate.
-To make externally-created certificate and key files accessible from
-Elpher, simply copy them to @code{elpher-certificate-directory}.
+Using throwaway certificates is as simple as pressing the @key{t}
+key at the prompt which appears following a certificate request from
+a server. There is nothing more to do.
+
+Using a persistent certificate requires instead selecting @key{p} from the same
+menu. This will result in Elpher asking you for the name identifying
+the certificate. This entry autocompletes to the list of known certificate
+names, so you can use @key{TAB} to display the list.
+
+In the case that you choose a name that does not belong to the list of
+known certificates, Elpher will offer to create one for you or to
+``install'' one from existing key and certificate files.
+Pressing the @key{n} key will cause Elpher to begin the process of
+creating a new persistent certificate, using some additional
+details for which you will be prompted.
+Alternatively, pressing the @key{i} key will cause Elpher to ask for the
+locations of edisting key and certificate files to add to
+@code{elpher-certificate-directory} under the chosen name.
Once a certificate is selected, it will be used for all subsequent TLS
transactions to the host for which the certificate was created.
The Lambda Lab / projects / elpher.git / blobdiff