\input texinfo @c -*-texinfo-*-
@setfilename elpher.info
-@settitle Elpher Manual v2.7.0
+@settitle Elpher Manual v2.11.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 Tim Vaughan
@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)
@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}
@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{X}, elpher-unbookmark-current}
-Immediately remove the bookmark (if one exists) to the current page.
+@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{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
+need to import the 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
@chapter Gemini support
@uref{gopher://gemini.circumlunar.space, Gemini}
-is a new protocol being devloped by several members of
+is a new protocol being developed by several members of
gopherspace. It aims to solve some of the long-standing technical
-issues associated with gopher as a protocol, while keeping the major benifits.
+issues associated with gopher as a protocol, while keeping the major benefits.
For instance, it _requires_ encrypted connections, it does away with
the selector type, and allows servers to explicitly specify the
character coding scheme used for text documents.
-The latest versions of Elpher aim to provide seemless navigation between
+The latest versions of Elpher aim to provide seamless transitions between
gemini and gopher documents. Basically you should be able to open,
bookmark, download and otherwise interact with gemini pages in exactly
the same way as you do with other non-gemini pages. The only major
customized by setting the @code{elpher-gemini-TLS-cert-checks}
customization variable to non-nil.
-Like gopher, the gemini specification concerns both the protocol
- a simple text document format (mimetype text/gemini) which is
-like a mixture between gophermap files and markdown-formatted files but
-simpler than both. Elpher renders gemini responses which are provided
-in this format in line with the rules in the spec. This includes
-wrapping long lines at word boundaries. The specific column at which
-this text is wrapped is defined by the customization variable
+The gemini specification concerns both the protocol and a simple text
+document format (mimetype text/gemini) which is like a mixture between
+gophermap files and markdown-formatted files but simpler than both.
+Elpher renders gemini responses which are provided in this format in
+line with the rules in the spec. This includes wrapping long lines at
+word boundaries. The specific column at which this text is wrapped is
+defined by the customization variable
@code{elpher-gemini-max-fill-width}, which is set to 80 columns by
default. (This is slightly wider than Emacs' default fill width of 70
columns due to the fact that there are a significant amount of older
-gemini which, against the advice of the current spec, hard wraps at <80
-columns. The larger default allows this to still look okay, while
-still keeping content without hard wraps looking pleasant.)
+gemini content which, against the advice of the current spec, hard wraps
+at <80 columns. The larger default allows this to still look okay,
+while still keeping content without hard wraps looking pleasant.)
-The text/gemini format also posesses a section header syntax similar to
+The text/gemini format also possesses a section header syntax similar to
markdown. Elpher allows different header levels to be drawn with
different, customizable, faces. By default, on graphically-capable
emacs systems, these faces are given different heights to distinguish
-amongst levels. On terminal systems, the level is indicated by the
-number of preceeding # symbols.
+among levels. On terminal systems, the level is indicated by the
+number of preceding # symbols.
I should emphasize however that, while it is definitely functional,
Elpher's gemini support is still experimental, and various aspects will
-change as the protocol develops further. Additionally, the use of
-client TLS certicificates is still not yet supported.
+change as the protocol develops further.
+
+@section Client Certificates for Gemini
+
+Gemini makes explicit use of the client certificate mechanism that TLS
+provides for allowing clients to authenticate themselves with servers.
+The Gemini specification suggests two distinct classes of client
+certificates: short-lived certificates used to identify you for a single
+session, and more permanent certificates used to identify you over a
+longer time period.
+
+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, 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
+utility. By default, Elpher assumes that the @command{openssl} is on the
+system path, but the precise location can be set by customizing the
+@code{elpher-openssl-command} variable.
+
+Each generated certificate results in the creation of a .key file and
+a .crt file. In the case of a throwaway certificate, these files are
+stored in the temporary directory indicated by the Emacs variable
+@code{temporary-file-directory} and are deleted when ``forgotten''
+(as described below).
+
+In the case of persistent certificates, these files are stored in the
+folder defined by the Elpher variable
+@code{elpher-certificate-directory}, and are never deleted by Elpher.
+(Of course you can delete them yourself whenever you like.)
+The base name of the files (i.e. sans extension) is what Elpher uses
+to identify the certificate.
+
+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.
+It is immediately ``forgotten'' when a TLS connection to another host
+is attempted, or the following command is issued:
+
+@table @asis
+@keycmd{@key{F},elpher-forget-certificate}
+Causes Elpher to immediately forget any currently-loaded client certificate.
+@end table
+
+In either case, ``forgetting'' means that the details of the key and
+certificate file pair are erased from memory. Furthermore, in the case
+of throw-away certificates, the corresponding files are deleted.
+
@node Finger support, Customization, Gemini support, Top
@chapter Finger support
The Lambda Lab / projects / elpher.git / blobdiff