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 * Navigation::                  Fundamentals of Elpher navigation
  46 * Bookmarks::                   How to record and visit bookmarks
  47 * Character encodings::         How Elpher handles different character encodings
  48 * Customization::               How to customize various aspects of Elpher
  49 * Hacking::                     Contributing changes to Elpher
  50 * Index::
  51 @end menu
  52
  53 @node Introduction, Navigation, Top, Top
  54 @chapter Introduction
  55
  56 Elpher aims to be a capable and practical gopher client for Emacs.  Its
  57 focus is on easy keyboard-driven navigation based on sensible default
  58 bindings (with out-of-the-box support for Evil).  It is intended to be
  59 robust and behave in non-surprising ways at all times.  Additionally,
  60 Elpher provides the following bells and whistles:
  61
  62 @itemize
  63 @item
  64 an easily navigable history, sporting caching of visited pages (both
  65 content and cursor position),
  66
  67 @item
  68 auto-completing menu item navigation,
  69
  70 @item
  71 followable web and gopher links in plain text,
  72
  73 @item
  74 direct visualization of image files where supported (no writing to
  75 disk), and
  76
  77 @item
  78 a simple bookmark management system.
  79 @end itemize
  80
  81 Elpher is still under active development.  Although we try very hard to
  82 ensure that releases are bug-free, this cannot be guaranteed.  However,
  83 this also means that any usability features that you feel are missing
  84 can likely by incoroporated quickly, so please get in touch if you
  85 have some ideas.
  86
  87 @node Navigation, Bookmarks, Introduction, Top
  88 @chapter Navigation
  89
  90 Throughout this manual, we use the word ``page'' to refer to any
  91 visualization of a response from a gopher server, be it a
  92 menu/directory, query result, text file or image.  We use
  93
  94 Elpher's navigation interface is inspired by the Emacs Info mode.
  95 Movement within a page is essentially the same as moving
  96 around any other text file in Emacs, but with special keys
  97 for quickly jumping between menu items and URLs in text files.
  98 Movement between pages is facilitated by a simple linear history
  99 coupled with caching of pages and cursor position.
 100
 101 @menu
 102 * Within-page navigation::      Moving about within a page
 103 * Between-page navigation::     Concepts and commands for moving between pages
 104 @end menu
 105
 106
 107 @node Within-page navigation, Between-page navigation, Navigation, Navigation
 108 @section Within-page navigation
 109
 110 To move about within a page, you should be able use the same keys you usually
 111 use to browse files in Emacs.  This is even true when Evil mode is
 112 enabled. Paragraph hopping, searching etc should work as usual.
 113
 114 In addition, the following commands are provided for quickly moving between
 115 links and menu items.
 116
 117 @table @asis
 118 @item @kbd{tab}  (@code{elpher-next-link})
 119 Move to the next link or menu item in the file.
 120
 121 @item @kbd{<S-tab>}/@kbd{<backtab>}  (@code{elpher-prev-link})
 122 Move to the previous link or menu item in the file.
 123
 124 @item @kbd{m}  (@code{elpher-jump})
 125 Jump directly to a link within a file by specifying its display string
 126 or link text.  (Unlike the previous two commands, this immediately opens
 127 the selected link.
 128 @end table
 129
 130 The following commands can be used to retrieve information about the
 131 current page, or the address of the link at point:
 132
 133 @table @asis
 134 @item @kbd{i}  (@code{elpher-info-link})
 135 Display host, port and selector information for the link at point.
 136
 137 @item @kbd{I}  (@code{elpher-info-current})
 138 Display host, port and selector information for the current page.
 139
 140 @item @kbd{c}  (@code{elpher-copy-link-url})
 141 Add URL representing address of link at point to the kill-ring and the
 142 system clipboard (if available).
 143
 144 @item @kbd{C}  (@code{elpher-copy-current-url})
 145 Add URL representing address of the current page to the kill-ring and
 146 the system clipboard (if available).
 147 @end table
 148
 149
 150 @node Between-page navigation,  , Within-page navigation, Navigation
 151 @section Between-page navigation
 152
 153 Moving to a different page can be accomplished in several ways,
 154 described by the following command:
 155
 156 @table @asis
 157 @item @kbd{RET}, @kbd{mouse-1}  (@code{elpher-follow-link})
 158 Follow the menu item or link at point (or selected with the mouse).
 159
 160 Exactly what is meant by ``follow'' depends on the kind of item selected:
 161
 162 @itemize
 163 @item
 164 For text or menu type items or links, the curent page text is replaced
 165 by the text of this item.  Unless the customization variable
 166 @code{elpher-use-header} (@pxref{Customization}) is
 167 @code{nil}, the display string of the link is displayed in the buffer header.
 168 Links to images behave similarly on Emacs systems supporting the display of
 169 bitmap graphics, however their content is not cached in memory by default.
 170
 171 @item
 172 When followed, links to search/query items (type 7) prompt for input in
 173 the minibuffer then display the results in the same way as for text and menu
 174 items.
 175
 176 @item
 177 Following links to binary files (and image files on unsupported systems)
 178 causes Elpher to prompt for a filename in which to save the content.
 179 @end itemize
 180
 181 Once a text, menu or query response page is retrieved, its contents are
 182 cached for the duration of the Emacs session.
 183
 184 @item @kbd{d}  (@code{elpher-download})
 185
 186 @item @kbd{g}  (@code{elpher-go})
 187
 188 @item @kbd{O}  (@code{elpher-root-dir})
 189
 190 @item @kbd{u}  (@code{elpher-back})
 191 Return to the previous page, where ``previous'' means the page where the
 192 page which was displayed immediately before the current page.
 193 @end table
 194
 195 @node Bookmarks, Character encodings, Navigation, Top
 196 @chapter Bookmarks
 197
 198 @node Character encodings, Customization, Bookmarks, Top
 199 @chapter Character encodings
 200
 201 @node Customization, Hacking, Character encodings, Top
 202 @chapter Customization
 203
 204 @node Hacking, Index, Customization, Top
 205 @chapter Hacking
 206
 207 @node Index,  , Hacking, Top
 208 @unnumbered Index
 209
 210 @printindex cp
 211
 212 @bye