Improved behaviour of history-all/visited-pages.

[elpher.git] / elpher.texi

diff --git a/elpher.texi b/elpher.texi
index 475dd19..87caaf7 100644 (file)
--- a/elpher.texi
+++ b/elpher.texi
@@ -1,17 +1,19 @@
 \input texinfo @c -*-texinfo-*-
 
 @setfilename elpher.info
 \input texinfo @c -*-texinfo-*-
 
 @setfilename elpher.info

-@settitle Elpher Manual v2.7.0
+@settitle Elpher Manual v3.0.0

 
 @dircategory Emacs
 @direntry
 
 @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.
 
 @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
 
 @quotation
 The source and documentation of Elpher is free software.  You can


@@ -42,12 +44,6 @@ the file COPYING in the same directory as this file for more details.
 @top Elpher
 
 @insertcopying
 @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?
 
 @menu
 * Introduction::                Elpher Overview: what's this all about?


@@ -73,6 +69,12 @@ Navigation
 
 @end detailmenu
 @end menu
 
 @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
 
 @node Introduction, Installation, Top, Top
 @chapter Introduction


@@ -98,9 +100,6 @@ auto-completing menu item navigation,
 direct visualization of image files where supported (no writing to
 disk),
 
 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,
 
 @item
 basic support for the new ``heavier than gopher, lighter than the web'' Gemini protocol,
 


@@ -134,10 +133,10 @@ to follow the instructions at @url{https://melpa.org/#/getting-started}.
 @kbd{M-x package-delete @key{RET} elpher @key{RET}}.
 @end example
 
 @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)
 
 @example
 (require 'elpher)


@@ -183,12 +182,19 @@ rather than stick with the cached version.  To do this use @key{R}.
 (This is particularly useful for search query results, where this
 allows you to perform a different search.)
 
 (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.
 
 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
 @node Navigation, Bookmarks, Quick Start, Top
 @chapter Navigation
 Throughout this manual, we use the word ``page'' to refer to any


@@ -223,7 +229,8 @@ links and menu items.
 @keycmd{@key{TAB}, elpher-next-link}
 Move to the next link or menu item in the file.
 
 @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}
 Move to the previous link or menu item in the file.
 
 @keycmd{@key{m}, elpher-jump}


@@ -232,6 +239,7 @@ or link text.  (Unlike the previous two commands, this immediately opens
 the selected link.
 @end table
 
 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:
 
 The following commands can be used to retrieve information about the
 current page, or the address of the link at point:
 


@@ -308,8 +316,9 @@ Once a text, menu or query response page has been displayed, its contents are
 cached for the duration of the Emacs session. 
 
 @keycmd{@key{g}, elpher-go}
 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.
 
 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.


@@ -325,7 +334,7 @@ structure of selectors.
 @keycmd{@key{O}, elpher-root-dir}
 Open the root page (empty selector) on the current host.
 
 @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
 Return to the previous page, where ``previous'' means the page where the
 page which was displayed immediately before the current page.
 @end table


@@ -367,42 +376,51 @@ this will be automatically positioned on the link that was most recently followe
 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}.
 
 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
 
 
 @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
 
 @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.
 
 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.
 
 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
 
 @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
 
 @node Gopher character encodings, Encrypted gopher connections, Bookmarks, Top
 @chapter Gopher character encodings


@@ -430,7 +448,7 @@ The alternative is to explicitly set the coding system used for decoding
 using the following command:
 
 @table @asis
 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
 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


@@ -534,8 +552,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
 
 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
 
 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 +575,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.
 
 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.
 
 Once a certificate is selected, it will be used for all subsequent TLS
 transactions to the host for which the certificate was created.