Added quick start section.

[elpher.git] / elpher.texi

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename elpher.info
@settitle Elpher Manual v1.0.0
@c %**end of header

@copying
This manual documents Elpher, a gopher client for Emacs.

Copyright @copyright{} 2019 Tim Vaughan

@quotation
The source and documentation of Elpher is free software.  You can
redistribute it and/or modify it under the terms of the GNU General
Public License as published by the Free Software Foundation; either
version 3, or (at your option) any later version.

Elpher is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNElpher FOR A PARTICULAR PURPOSE. See the GNU General Public License in
the file COPYING in the same directory as this file for more details.
@end quotation
@end copying

@titlepage
@title Elpher Gopher Client Manual
@author Tim Vaughan

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top, Introduction, (dir), (dir)
@top Elpher

@insertcopying
@end ifnottex

@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
* Index::
@end menu

@node Introduction, Installation, Top, Top
@chapter Introduction

Elpher aims to be a capable and practical gopher client for Emacs.  Its
focus is on easy keyboard-driven navigation based on sensible default
bindings (with out-of-the-box support for Evil).  It is intended to be
robust and behave in non-surprising ways at all times.  Additionally,
Elpher provides the following bells and whistles:

@itemize
@item
an easily navigable history, sporting caching of visited pages (both
content and cursor position),

@item
auto-completing menu item navigation,

@item
followable web and gopher links in plain text,

@item
direct visualization of image files where supported (no writing to
disk), and

@item
a simple bookmark management system.
@end itemize

Elpher is still under active development.  Although we try very hard to
ensure that releases are bug-free, this cannot be guaranteed.  However,
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 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

Elpher's navigation interface is inspired by the Emacs Info mode.
Movement within a page is essentially the same as moving
around any other text file in Emacs, but with special keys
for quickly jumping between menu items and URLs in text files.
Movement between pages is facilitated by a simple linear history
coupled with caching of pages and cursor position.

@menu
* Within-page navigation::      Moving about within a page
* 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

To move about within a page, you should be able use the same keys you usually
use to browse files in Emacs.  This is even true when Evil mode is
enabled. Paragraph hopping, searching etc should work as usual.

In addition, the following commands are provided for quickly moving between
links and menu items.

@table @asis
@item @kbd{tab}  (@code{elpher-next-link})
Move to the next link or menu item in the file.

@item @kbd{<S-tab>}/@kbd{<backtab>}  (@code{elpher-prev-link})
Move to the previous link or menu item in the file.

@item @kbd{m}  (@code{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.
@end table

The following commands can be used to retrieve information about the
current page, or the address of the link at point:

@table @asis
@item @kbd{i}  (@code{elpher-info-link})
Display host, port and selector information for the link at point.

@item @kbd{I}  (@code{elpher-info-current})
Display host, port and selector information for the current page.

@item @kbd{c}  (@code{elpher-copy-link-url})
Add URL representing address of link at point 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


@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 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).

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.  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. 

@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

@node Character encodings, Customization, Bookmarks, Top
@chapter Character encodings

@node Customization, Index, Character encodings, Top
@chapter Customization

@node Index,  , Customization, Top
@unnumbered Index

@printindex cp

@bye