X-Git-Url: https://thelambdalab.xyz/gitweb/index.cgi?p=elpher.git;a=blobdiff_plain;f=elpher.texi;h=87caaf71ca5f9283b53cba13e3320a61c92e5ccf;hp=7229c9998324678055f736173601e4a6b4696628;hb=185db89b91b00332731882dfe08ffe344089ecee;hpb=b4450244a5e23605f80b2179ce7d4dbaff56d927 diff --git a/elpher.texi b/elpher.texi index 7229c99..87caaf7 100644 --- a/elpher.texi +++ b/elpher.texi @@ -1,17 +1,19 @@ \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 @@ -42,12 +44,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 +69,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 +100,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 +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 -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) @@ -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.) -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 @@ -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{@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} @@ -232,6 +239,7 @@ or link text. (Unlike the previous two commands, this immediately opens 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: @@ -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} -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. @@ -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{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 @@ -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}. +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 @@ -430,7 +448,7 @@ The alternative is to explicitly set the coding system used for decoding 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