\input texinfo @c -*-texinfo-*-
-@c %**start of header
+
@setfilename elpher.info
@settitle Elpher Manual v1.0.0
-@c %**end of header
+
+@dircategory Emacs
+@direntry
+* Elpher: (elpher). A gopher client for Emacs.
+@end direntry
@copying
This manual documents Elpher, a gopher client for Emacs.
@insertcopying
@end ifnottex
+@macro keycmd{key,cmd}
+@item \key\ (@code{\cmd\})
+@findex \cmd\
+@end macro
+
@menu
* Introduction:: Elpher Overview: what's this all about?
* Installation:: Installing Elpher
* Character encodings:: How Elpher handles different character encodings
* Encrypted connections:: How and when TLS is enabled
* Customization:: How to customize various aspects of Elpher
-* Index::
+* Command Index::
@end menu
@node Introduction, Installation, Top, Top
Elpher provides the following bells and whistles:
@itemize
+@item
+followable web and gopher links in plain text,
+
@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
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
+can likely by incorporated quickly, so please get in touch if you
have some ideas.
@node Installation, Quick Start, Introduction, Top
links and menu items.
@table @asis
-@item @key{TAB} (@code{elpher-next-link})
+@keycmd{@key{TAB}, elpher-next-link}
Move to the next link or menu item in the file.
-@item @kbd{Shift-@key{TAB}}/@key{backtab} (@code{elpher-prev-link})
+@keycmd{@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})
+@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.
current page, or the address of the link at point:
@table @asis
-@item @kbd{i} (@code{elpher-info-link})
+@keycmd{@key{i}, elpher-info-link}
Display host, port and selector information for the link at point.
-@item @kbd{I} (@code{elpher-info-current})
+@keycmd{@key{I}, elpher-info-current}
Display host, port and selector information for the current page.
-@item @kbd{c} (@code{elpher-copy-link-url})
+@keycmd{@key{c}, 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})
+@keycmd{@key{C}, elpher-copy-current-url}
Add URL representing address of the current page to the kill-ring and
the system clipboard (if available).
-@item @kbd{d} (@code{elpher-download})
+@keycmd{@key{d}, 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
+@keycmd{@key{D}, elpher-download-current}
+This is similar to @code{elpher-download}, but instead applies to the
current page rather than a link.
-@item @kbd{w} (@code{elpher-view-raw})
+@keycmd{@key{.}, 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.
described by the following command:
@table @asis
-@item @kbd{RET}, @kbd{mouse-1} (@code{elpher-follow-link})
+@keycmd{@key{RET}\, @kbd{mouse-1}, 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
+For text or menu type items or links, the current 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.
Once a text, menu or query response page has been displayed, its contents are
cached for the duration of the Emacs session.
-@item @kbd{g} (@code{elpher-go})
+@keycmd{@key{g}, 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.
+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.
+
+@keycmd{@key{o}, elpher-go-current}
+Prompts for a URL similar to @code{elpher-go}, but initialized to the URL
+of the current page. This allows you to easily try other selectors for the
+same server.
-@item @kbd{O} (@code{elpher-root-dir})
+Remember however, that the Gopher RFC 1436 provides no guarantees about the
+structure of selectors.
+
+@keycmd{@key{O}, elpher-root-dir}
Open the root page (empty selector) on the current host.
-@item @kbd{u} (@code{elpher-back})
+@keycmd{@key{u}, 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
following commands:
@table @asis
-@item @key{a} (@code{elpher-bookmark-link})
+@keycmd{@key{a}, elpher-bookmark-link}
Add a bookmark for the link at point. The minibuffer will prompt for
a name for the bookmark, which defaults to the display string.
-@item @key{A} (@code{elpher-bookmark-current})
+@keycmd{@key{A}, elpher-bookmark-current}
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.
-@item @key{x} (@code{elpher-unbookmark-link})
+@keycmd{@key{x}, elpher-unbookmark-link}
Immediately remove the bookmark (if one exists) to the link at point.
-@item @key{X} (@code{elpher-unbookmark-current})
+@keycmd{@key{X}, elpher-unbookmark-current}
Immediately remove the bookmark (if one exists) to the current page.
-@item @key{B} (@code{elpher-bookmarks})
+@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
system to the full (undecoded) response data and uses this to attempt to
convert it into a character string.
(See @pxref{Recognize coding, Recognizing coding systems, ,emacs}.) While
-this approach can be okay, it is important to realise that its inference
+this approach can be okay, it is important to realize that its inference
algorithm is extremely primitive and depends heavily on assumptions based
on the language settings of your emacs system.
using the following command:
@table @asis
-@item @key{S} (@code{elpher-set-coding-system})
+@keycmd{@key{S},elpher-set-coding-system}
Causes a elpher to prompt for a coding system to use for decoding
future text. The @key{TAB} key can be used at this prompt to display a
-list of alternatives (which is extensive) and to autocomplete. An empty
-response will cause Elpher to return to its default autodetection
+list of alternatives (which is extensive) and to auto-complete. An empty
+response will cause Elpher to return to its default auto-detection
behaviour.
@end table
you can't accidentally make a non-TLS connection.
-@node Customization, Index, Encrypted connections, Top
+@node Customization, Command Index, Encrypted connections, Top
@chapter Customization
+Various parts of Elpher can be customized via the
+variables belonging to the elpher customization group, accessible
+using
+@example
+@kbd{M-x customize-group elpher @key{RET}}
+@end example
+@noindent This group contains a number of faces that can be modified to change
+the appearance of Elpher, including one face per menu item type.
-@menu
-* Faces::
-* Other cutomizations::
-@end menu
-
-@node Faces, Other cutomizations, Customization, Customization
-@section Faces
+The group also contains variables for customizing the behaviour of
+Elpher. This includes how to open arbitrary (non-gopher) URLs,
+whether to display buffer headers, whether to look for naked URLs in
+gopher menus (as opposed to just plain text files), and whether
+to prompt for confirmation when switching away from TLS.
-@node Other cutomizations, , Faces, Customization
-@section Other customizations
+See the customization group itself for details.
-@node Index, , Customization, Top
-@unnumbered Index
+@node Command Index, , Customization, Top
+@unnumbered Command Index
-@printindex cp
+@printindex fn
@bye
The Lambda Lab / projects / elpher.git / blobdiff