X-Git-Url: https://thelambdalab.xyz/gitweb/index.cgi?p=elpher.git;a=blobdiff_plain;f=elpher.texi;h=e7a03a919aec9747e32bb4ed0d0e8f2c9c744521;hp=475dd191c17c9ac6eaf4e32522e36c5942817cd7;hb=5f7b2a6ed52621ea1bd983428428d5d513b2405e;hpb=21e2cea71c8ebd94689c0243c07817b7c6c59f83 diff --git a/elpher.texi b/elpher.texi index 475dd19..e7a03a9 100644 --- a/elpher.texi +++ b/elpher.texi @@ -1,17 +1,17 @@ \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 @@ -42,12 +42,6 @@ the file COPYING in the same directory as this file for more details. @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? @@ -73,6 +67,12 @@ Navigation @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 @@ -98,9 +98,6 @@ auto-completing menu item navigation, 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, @@ -134,10 +131,10 @@ to follow the instructions at @url{https://melpa.org/#/getting-started}. @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) @@ -223,7 +220,8 @@ links and menu items. @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} @@ -371,38 +369,35 @@ and text files, the inverse of @key{u} is actually just @key{RET}. @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 @@ -534,8 +529,9 @@ 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, 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 @@ -556,8 +552,24 @@ folder defined by the Elpher variable 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.