X-Git-Url: https://thelambdalab.xyz/gitweb/index.cgi?a=blobdiff_plain;f=elpher.texi;h=725f927df10f46250ecb271c5d0f13e398e6ba7e;hb=2db3b66f49cda835a2b07dd6c93d3abb46920e2b;hp=8c5983dc92c43c08fec65039ac2561491c5a9d90;hpb=fe79e5cd6a8b8d0f7ef431ce3294b85a5f9f617e;p=elpher.git diff --git a/elpher.texi b/elpher.texi index 8c5983d..725f927 100644 --- a/elpher.texi +++ b/elpher.texi @@ -42,15 +42,16 @@ the file COPYING in the same directory as this file for more details. @menu * Introduction:: Elpher Overview: what's this all about? +* Installation:: Installing Elpher +* Quick Start:: Get up and running quickly * Navigation:: Fundamentals of Elpher navigation * Bookmarks:: How to record and visit bookmarks * Character encodings:: How Elpher handles different character encodings * Customization:: How to customize various aspects of Elpher -* Hacking:: Contributing changes to Elpher * Index:: @end menu -@node Introduction, Navigation, Top, Top +@node Introduction, Installation, Top, Top @chapter Introduction Elpher aims to be a capable and practical gopher client for Emacs. Its @@ -84,9 +85,83 @@ this also means that any usability features that you feel are missing can likely by incoroporated quickly, so please get in touch if you have some ideas. -@node Navigation, Bookmarks, Introduction, Top -@chapter Navigation +@node Installation, Quick Start, Introduction, Top +@chapter Installation + +Elpher is available from the MELPA package repository. If you have +never installed packages from this repository before, you'll need +to follow the instructions at @url{https://melpa.org/#/getting-started}. + +@noindent To install Elpher, enter the following: + +@example +@kbd{M-x package-install @key{RET} elpher @key{RET}} +@end example + +@noindent To uninstall, use + +@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{https://github.com/tgvaughan/elpher}, adding it to a directory in +your @code{load-path}, and then adding + +@example +(require 'elpher) +@end example + +@noindent to your Emacs initialization file. + +@node Quick Start, Navigation, Installation, Top +@chapter Quick Start + +Before diving into the minutiae of the different commands available, +we will quickly describe how to get up and running with Elpher. + +Once installed, you can launch Elpher using + +@example +@kbd{M-x elpher @key{RET}} +@end example + +@noindent This will switch to the *Elpher* buffer and display a start +page, with information on each of the default keyboard bindings. + +From here you can move point between links (which may be menu items or +inline URLs in text files) by using @key{TAB} and @kbd{Shift-TAB} keys, +as in Info. You can also jump directly to a menu item using @key{m}, or +use the standard Emacs or Evil motion and search commands to find your +way around. To open a link, press @key{RET}. (Where a mouse is +available, Clicking on a link with the mouse cursor has the same +effect.) + +To return to the page you just followed the link from, press @key{u}. + +Elpher caches (for the duration of an Emacs session) both page contents +and the position of point on each of the pages (gopher menus, query +results, or text pages) you visit, restoring these when you next visit +the same page. Thus, pressing @key{u} displays the previous page in +exactly the same state as when you left, meaning that you can quickly +and visually explore the different documents in a menu without having to +wait for anything to reload. + +Of course, sometimes you'll @emph{want} to reload the current page +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 +navigation experience as intuitive and responsive as possible. +@node Navigation, Bookmarks, Quick Start, Top +@chapter Navigation +by Throughout this manual, we use the word ``page'' to refer to any visualization of a response from a gopher server, be it a menu/directory, query result, text file or image. We use @@ -103,6 +178,7 @@ coupled with caching of pages and cursor position. * Between-page navigation:: Concepts and commands for moving between pages @end menu + @node Within-page navigation, Between-page navigation, Navigation, Navigation @section Within-page navigation @@ -117,7 +193,7 @@ links and menu items. @item @kbd{tab} (@code{elpher-next-link}) Move to the next link or menu item in the file. -@item @kbd{}/@kbd{}/@kbd{} (@code{elpher-prev-link}) Move to the previous link or menu item in the file. @item @kbd{m} (@code{elpher-jump}) @@ -145,23 +221,51 @@ Add URL representing address of the current page to the kill-ring and the system clipboard (if available). @end table + @node Between-page navigation, , Within-page navigation, Navigation @section Between-page navigation Moving to a different page can be accomplished in several ways, -described by the following commands: +described by the following command: @table @asis @item @kbd{RET}, @kbd{mouse-1} (@code{elpher-follow-link}) Follow the menu item or link at point (or selected with the mouse). -@end table -Exactly what is meant by ``follow'' depends on the kind of item selected. +Exactly what is meant by ``follow'' depends on the kind of item selected: + +@itemize +@item For text or menu type items or links, the curent page text is replaced -by the text of this item. +by the text of this item. Unless the customization variable +@code{elpher-use-header} (@pxref{Customization}) is +@code{nil}, the display string of the link is displayed in the buffer header. +Links to images behave similarly on Emacs systems supporting the display of +bitmap graphics, however their content is not cached in memory by default. + +@item +When followed, links to search/query items (type 7) prompt for input in +the minibuffer then display the results in the same way as for text and menu +items. + +@item +Following links to binary files (and image files on unsupported systems) +causes Elpher to prompt for a filename in which to save the content. +@end itemize Once a text, menu or query response page is retrieved, its contents are -cached for the duration of the Emacs session. +cached for the duration of the Emacs session. + +@item @kbd{d} (@code{elpher-download}) + +@item @kbd{g} (@code{elpher-go}) + +@item @kbd{O} (@code{elpher-root-dir}) + +@item @kbd{u} (@code{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 @node Bookmarks, Character encodings, Navigation, Top @chapter Bookmarks @@ -169,13 +273,10 @@ cached for the duration of the Emacs session. @node Character encodings, Customization, Bookmarks, Top @chapter Character encodings -@node Customization, Hacking, Character encodings, Top +@node Customization, Index, Character encodings, Top @chapter Customization -@node Hacking, Index, Customization, Top -@chapter Hacking - -@node Index, , Hacking, Top +@node Index, , Customization, Top @unnumbered Index @printindex cp