Finished between-page navigation section.
[elpher.git] / elpher.texi
index 5fb4882..24c38ca 100644 (file)
@@ -42,15 +42,17 @@ the file COPYING in the same directory as this file for more details.
 
 @menu
 * Introduction::                Elpher Overview: what's this all about?
 
 @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
 * Navigation::                  Fundamentals of Elpher navigation
 * Bookmarks::                   How to record and visit bookmarks
 * Character encodings::         How Elpher handles different character encodings
+* Encrypted connections::
 * Customization::               How to customize various aspects of Elpher
 * Customization::               How to customize various aspects of Elpher
-* Hacking::                     Contributing changes to Elpher
 * Index::
 @end menu
 
 * 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
 @chapter Introduction
 
 Elpher aims to be a capable and practical gopher client for Emacs.  Its
@@ -84,9 +86,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.
 
 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{S-@key{TAB}},
+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
 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
@@ -100,7 +176,8 @@ coupled with caching of pages and cursor position.
 
 @menu
 * Within-page navigation::      Moving about within a page
 
 @menu
 * Within-page navigation::      Moving about within a page
-* Between-page navigation::     Concepts and commands for moving between pages
+* Between-page navigation::     Commands for moving between pages
+* History and Caching::         Explanation of how Elpher represents history
 @end menu
 
 
 @end menu
 
 
@@ -115,10 +192,10 @@ In addition, the following commands are provided for quickly moving between
 links and menu items.
 
 @table @asis
 links and menu items.
 
 @table @asis
-@item @kbd{tab}  (@code{elpher-next-link})
+@item @key{TAB}  (@code{elpher-next-link})
 Move to the next link or menu item in the file.
 
 Move to the next link or menu item in the file.
 
-@item @kbd{<S-tab>}/@kbd{<backtab>}  (@code{elpher-prev-link})
+@item @kbd{Shift-@key{TAB}}/@key{backtab}  (@code{elpher-prev-link})
 Move to the previous link or menu item in the file.
 
 @item @kbd{m}  (@code{elpher-jump})
 Move to the previous link or menu item in the file.
 
 @item @kbd{m}  (@code{elpher-jump})
@@ -144,10 +221,23 @@ system clipboard (if available).
 @item @kbd{C}  (@code{elpher-copy-current-url})
 Add URL representing address of the current page to the kill-ring and
 the system clipboard (if available).
 @item @kbd{C}  (@code{elpher-copy-current-url})
 Add URL representing address of the current page to the kill-ring and
 the system clipboard (if available).
-@end table
 
 
+@item @kbd{d}  (@code{elpher-download})
+Download link at point and save the result as a file.  The minibuffer
+will prompt for the name of the file to write, with the default name being
+the display string (if available) associated with the link.
+
+@item @kbd{D}  (@code{elpher-download-current})
+This is similar to @code{elpher-downlowd}, but instead applies to the
+current page rather than a link.
+
+@item @kbd{w} (@code{elpher-view-raw})
+This displays the raw server response for the current page.  While not
+useful for general browsing, it is useful for debugging incorrect rendering
+or out-of-spec server responses.
+@end table
 
 
-@node Between-page navigation,  , Within-page navigation, Navigation
+@node Between-page navigation, History and Caching, Within-page navigation, Navigation
 @section Between-page navigation
 
 Moving to a different page can be accomplished in several ways,
 @section Between-page navigation
 
 Moving to a different page can be accomplished in several ways,
@@ -176,35 +266,50 @@ 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.
 @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.
+
+@item
+Following links of type `h' with a selector having the `URL:' prefix, or
+non-gopher URLs in text files, will result in Elpher using an external
+programme to open the URL.  This will be either the default system browser
+or, if the @code{elpher-open-urls-with-eww} customization variable is non-nil,
+Emacs' own EWW browser. (See @pxref{Customization}.) 
+
 @end itemize
 
 @end itemize
 
-Once a text, menu or query response page is retrieved, its contents are
+Once a text, menu or query response page has been displayed, 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{g}  (@code{elpher-go})
+Open a particular page by specifying either its URL or directly entering
+a host, port and selector.
+
+Note that if a non-gopher protocol is used in the URL the result will be 
+the same as following a URL link of the same type from a gopher menu.
 
 @item @kbd{O}  (@code{elpher-root-dir})
 
 @item @kbd{O}  (@code{elpher-root-dir})
+Open the root page (empty selector) on the current host.
 
 @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
 
 
 @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 History and Caching,  , Between-page navigation, Navigation
+@section History and Caching 
+
 @node Bookmarks, Character encodings, Navigation, Top
 @chapter Bookmarks
 
 @node Bookmarks, Character encodings, Navigation, Top
 @chapter Bookmarks
 
-@node Character encodings, Customization, Bookmarks, Top
+@node Character encodings, Encrypted connections, Bookmarks, Top
 @chapter Character encodings
 
 @chapter Character encodings
 
-@node Customization, Hacking, Character encodings, Top
-@chapter Customization
+@node Encrypted connections, Customization, Character encodings, Top
+@chapter Encrypted connections
 
 
-@node Hacking, Index, Customization, Top
-@chapter Hacking
+@node Customization, Index, Encrypted connections, Top
+@chapter Customization
 
 
-@node Index,  , Hacking, Top
+@node Index,  , Customization, Top
 @unnumbered Index
 
 @printindex cp
 @unnumbered Index
 
 @printindex cp