\input texinfo @c -*-texinfo-*-
@setfilename elpher.info
-@settitle Elpher Manual v2.10.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, 2020 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}
Jump directly to a link within a file by specifying its display string
or link text. (Unlike the previous two commands, this immediately opens
the selected link.
+
+@keycmd{@key{M}, elpher-jump-to-number}
+Jump directly to a link within a file by specifying the number of the
+link, where the first link on the page is link number 1.
+(These indices can be shown next to the links by setting the customization
+option elpher-number-links to non-nil.)
@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-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-history-all}
+This shows the entire Elpher browsing history. It includes all the
+pages you visited using other Elpher buffers, and it includes buffers
+you later killed.
+
+@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