* Planned improvements
+** TODO Allow multiple elpher buffers
+
+ Shouldn't be too hard, just need elpher-current-node to be
+buffer-local and allow various buffer-switching procedures to
+do something sensible.
+
+** TODO Turn on lexical scoping
+
+ A branch exists for this, but there are some compilation kinks
+to iron out.
+
+** TODO Remove "redraw" command
+This is only necessary for returning from displaying the raw
+server response. If I can provide a better way of doing that
+then we can get rid of redraw entirely.
+
+** TODO Replace support for user-specified starting pages
+This used to be available, but was removed during a refactor.
+
+* Current issues
+
+* Completed improvements
+
** DONE Implement support for telnet entries
Similar to http entries, telnet entries will be handled by code
I always update node.parent unless parent is already an ancestor of
node?)
-** TODO Allow multiple elpher buffers
+
+** DONE Support character encoding diversity
- Shouldn't be too hard, just need elpher-current-node to be
-buffer-local and allow various buffer-switching procedures to
-do something sensible.
-
-** TODO Turn on lexical scoping
-
- A branch exists for this, but there are some compilation kinks
-to iron out.
-
-* Current issues
+* Old issues
** DONE Org mode faces are not present in recent emacs versions
Even 26.1 doesn't seem to have these. This means that, for many
;;; Commentary:
-;; Elpher aims to provide a practical gopher client for GNU Emacs.
-;; It supports:
+;; Elpher aims to provide a practical and friendly gopher client
+;; for GNU Emacs. It supports:
-;; - intuitive keyboard and mouse-driven interface,
+;; - an intuitive keyboard and mouse-driven interface,
;; - caching of visited sites (both content and cursor position),
;; - pleasant and configurable colouring of Gopher directories,
;; - direct visualisation of image files,
;; Faces, caching and other options can be configured via
;; the Elpher customization group in Applications.
+;; Elpher is under active development, and any suggestions for
+;; improvements are welcome!
+
;;; Code:
(provide 'elpher)
(error "No link selected"))))
(defun elpher-bookmarks ()
- "Visit bookmarks."
+ "Visit bookmarks page."
(interactive)
(switch-to-buffer "*elpher*")
(elpher-visit-node
"Keymap for gopher client.")
(define-derived-mode elpher-mode special-mode "elpher"
- "Major mode for elpher, an elisp gopher client.")
+ "Major mode for elpher, an elisp gopher client.
+
+This mode is automatically enabled by the interactive
+functions which initialize the gopher client, namely
+`elpher', `elpher-go' and `elpher-bookmarks'.")
(when (fboundp 'evil-set-initial-state)
(evil-set-initial-state 'elpher-mode 'motion))
--- /dev/null
+\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?
+* 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
+* Hacking:: Contributing changes to Elpher
+* Index::
+@end menu
+
+@node Introduction, Navigation, 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 Navigation, Bookmarks, Introduction, Top
+@chapter Navigation
+
+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, Hacking, Character encodings, Top
+@chapter Customization
+
+@node Hacking, Index, Customization, Top
+@chapter Hacking
+
+@node Index, , Hacking, Top
+@unnumbered Index
+
+@printindex cp
+
+@bye
The Lambda Lab / projects / elpher.git / commitdiff