elpher.texi

   1 \input texinfo @c -*-texinfo-*-
   2 @c %**start of header
   3 @setfilename elpher.info
   4 @settitle Elpher Manual v1.0.0
   5 @c %**end of header
   6
   7 @copying
   8 This manual documents Elpher, a gopher client for Emacs.
   9
  10 Copyright @copyright{} 2019 Tim Vaughan
  11
  12 @quotation
  13 The source and documentation of Elpher is free software.  You can
  14 redistribute it and/or modify it under the terms of the GNU General
  15 Public License as published by the Free Software Foundation; either
  16 version 3, or (at your option) any later version.
  17
  18 Elpher is distributed in the hope that it will be useful, but WITHOUT
  19 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  20 FITNElpher FOR A PARTICULAR PURPOSE. See the GNU General Public License in
  21 the file COPYING in the same directory as this file for more details.
  22 @end quotation
  23 @end copying
  24
  25 @titlepage
  26 @title Elpher Gopher Client Manual
  27 @author Tim Vaughan
  28
  29 @page
  30 @vskip 0pt plus 1filll
  31 @insertcopying
  32 @end titlepage
  33
  34 @contents
  35
  36 @ifnottex
  37 @node Top, Introduction, (dir), (dir)
  38 @top Elpher
  39
  40 @insertcopying
  41 @end ifnottex
  42
  43 @menu
  44 * Introduction::                Elpher Overview: what's this all about?
  45 * Installation::                Installing Elpher
  46 * Quick Start::                 Get up and running quickly
  47 * Navigation::                  Fundamentals of Elpher navigation
  48 * Bookmarks::                   How to record and visit bookmarks
  49 * Character encodings::         How Elpher handles different character encodings
  50 * Customization::               How to customize various aspects of Elpher
  51 * Index::
  52 @end menu
  53
  54 @node Introduction, Installation, Top, Top
  55 @chapter Introduction
  56
  57 Elpher aims to be a capable and practical gopher client for Emacs.  Its
  58 focus is on easy keyboard-driven navigation based on sensible default
  59 bindings (with out-of-the-box support for Evil).  It is intended to be
  60 robust and behave in non-surprising ways at all times.  Additionally,
  61 Elpher provides the following bells and whistles:
  62
  63 @itemize
  64 @item
  65 an easily navigable history, sporting caching of visited pages (both
  66 content and cursor position),
  67
  68 @item
  69 auto-completing menu item navigation,
  70
  71 @item
  72 followable web and gopher links in plain text,
  73
  74 @item
  75 direct visualization of image files where supported (no writing to
  76 disk), and
  77
  78 @item
  79 a simple bookmark management system.
  80 @end itemize
  81
  82 Elpher is still under active development.  Although we try very hard to
  83 ensure that releases are bug-free, this cannot be guaranteed.  However,
  84 this also means that any usability features that you feel are missing
  85 can likely by incoroporated quickly, so please get in touch if you
  86 have some ideas.
  87
  88 @node Installation, Quick Start, Introduction, Top
  89 @chapter Installation
  90
  91 Elpher is available from the MELPA package repository.  If you have
  92 never installed packages from this repository before, you'll need
  93 to follow the instructions at @url{https://melpa.org/#/getting-started}.
  94
  95 @noindent To install Elpher, enter the following:
  96
  97 @example
  98 @kbd{M-x package-install @key{RET} elpher @key{RET}}
  99 @end example
 100
 101 @noindent To uninstall, use
 102
 103 @example
 104 @kbd{M-x package-delete @key{RET} elpher @key{RET}}.
 105 @end example
 106
 107
 108 @node Quick Start, Navigation, Installation, Top
 109 @chapter Quick Start
 110
 111 Before diving into the minutiae of the different commands available,
 112 we will quickly describe how to get up and running with Elpher.
 113
 114 Once installation is
 115
 116 @node Navigation, Bookmarks, Quick Start, Top
 117 @chapter Navigation
 118
 119 Throughout this manual, we use the word ``page'' to refer to any
 120 visualization of a response from a gopher server, be it a
 121 menu/directory, query result, text file or image.  We use
 122
 123 Elpher's navigation interface is inspired by the Emacs Info mode.
 124 Movement within a page is essentially the same as moving
 125 around any other text file in Emacs, but with special keys
 126 for quickly jumping between menu items and URLs in text files.
 127 Movement between pages is facilitated by a simple linear history
 128 coupled with caching of pages and cursor position.
 129
 130 @menu
 131 * Within-page navigation::      Moving about within a page
 132 * Between-page navigation::     Concepts and commands for moving between pages
 133 @end menu
 134
 135
 136 @node Within-page navigation, Between-page navigation, Navigation, Navigation
 137 @section Within-page navigation
 138
 139 To move about within a page, you should be able use the same keys you usually
 140 use to browse files in Emacs.  This is even true when Evil mode is
 141 enabled. Paragraph hopping, searching etc should work as usual.
 142
 143 In addition, the following commands are provided for quickly moving between
 144 links and menu items.
 145
 146 @table @asis
 147 @item @kbd{tab}  (@code{elpher-next-link})
 148 Move to the next link or menu item in the file.
 149
 150 @item @kbd{<S-tab>}/@kbd{<backtab>}  (@code{elpher-prev-link})
 151 Move to the previous link or menu item in the file.
 152
 153 @item @kbd{m}  (@code{elpher-jump})
 154 Jump directly to a link within a file by specifying its display string
 155 or link text.  (Unlike the previous two commands, this immediately opens
 156 the selected link.
 157 @end table
 158
 159 The following commands can be used to retrieve information about the
 160 current page, or the address of the link at point:
 161
 162 @table @asis
 163 @item @kbd{i}  (@code{elpher-info-link})
 164 Display host, port and selector information for the link at point.
 165
 166 @item @kbd{I}  (@code{elpher-info-current})
 167 Display host, port and selector information for the current page.
 168
 169 @item @kbd{c}  (@code{elpher-copy-link-url})
 170 Add URL representing address of link at point to the kill-ring and the
 171 system clipboard (if available).
 172
 173 @item @kbd{C}  (@code{elpher-copy-current-url})
 174 Add URL representing address of the current page to the kill-ring and
 175 the system clipboard (if available).
 176 @end table
 177
 178
 179 @node Between-page navigation,  , Within-page navigation, Navigation
 180 @section Between-page navigation
 181
 182 Moving to a different page can be accomplished in several ways,
 183 described by the following command:
 184
 185 @table @asis
 186 @item @kbd{RET}, @kbd{mouse-1}  (@code{elpher-follow-link})
 187 Follow the menu item or link at point (or selected with the mouse).
 188
 189 Exactly what is meant by ``follow'' depends on the kind of item selected:
 190
 191 @itemize
 192 @item
 193 For text or menu type items or links, the curent page text is replaced
 194 by the text of this item.  Unless the customization variable
 195 @code{elpher-use-header} (@pxref{Customization}) is
 196 @code{nil}, the display string of the link is displayed in the buffer header.
 197 Links to images behave similarly on Emacs systems supporting the display of
 198 bitmap graphics, however their content is not cached in memory by default.
 199
 200 @item
 201 When followed, links to search/query items (type 7) prompt for input in
 202 the minibuffer then display the results in the same way as for text and menu
 203 items.
 204
 205 @item
 206 Following links to binary files (and image files on unsupported systems)
 207 causes Elpher to prompt for a filename in which to save the content.
 208 @end itemize
 209
 210 Once a text, menu or query response page is retrieved, its contents are
 211 cached for the duration of the Emacs session.
 212
 213 @item @kbd{d}  (@code{elpher-download})
 214
 215 @item @kbd{g}  (@code{elpher-go})
 216
 217 @item @kbd{O}  (@code{elpher-root-dir})
 218
 219 @item @kbd{u}  (@code{elpher-back})
 220 Return to the previous page, where ``previous'' means the page where the
 221 page which was displayed immediately before the current page.
 222 @end table
 223
 224 @node Bookmarks, Character encodings, Navigation, Top
 225 @chapter Bookmarks
 226
 227 @node Character encodings, Customization, Bookmarks, Top
 228 @chapter Character encodings
 229
 230 @node Customization, Index, Character encodings, Top
 231 @chapter Customization
 232
 233 @node Index,  , Customization, Top
 234 @unnumbered Index
 235
 236 @printindex cp
 237
 238 @bye