Display both URL and IRI for page info when they differ.

[elpher.git] / elpher.texi

diff --git a/elpher.texi b/elpher.texi
index 10ac96a..3b54a31 100644 (file)
--- a/elpher.texi
+++ b/elpher.texi
@@ -1,7 +1,7 @@
 \input texinfo @c -*-texinfo-*-
 
 @setfilename elpher.info
 \input texinfo @c -*-texinfo-*-
 
 @setfilename elpher.info

-@settitle Elpher Manual v3.0.0
+@settitle Elpher Manual v3.2.2

 
 @dircategory Emacs
 @direntry
 
 @dircategory Emacs
 @direntry


@@ -52,11 +52,15 @@ the file COPYING in the same directory as this file for more details.
 * Navigation::                  Fundamentals of Elpher navigation
 * Bookmarks::                   How to record and visit bookmarks
 * Gopher character encodings::  How Elpher selects encodings for gopher pages
 * Navigation::                  Fundamentals of Elpher navigation
 * Bookmarks::                   How to record and visit bookmarks
 * Gopher character encodings::  How Elpher selects encodings for gopher pages

-* Encrypted gopher connections::       How and when TLS is enabled for gopher
+* Encrypted gopher connections::  How and when TLS is enabled for gopher

 * Gemini support::              Support for the Gemini protocol
 * Finger support::              Support for the Finger protocol
 * Gemini support::              Support for the Gemini protocol
 * Finger support::              Support for the Finger protocol

+* Local files::                 Opening local files in elpher
+* About pages::                 Special pages and how to reference them

 * Customization::               How to customize various aspects of Elpher
 * Command Index::
 * Customization::               How to customize various aspects of Elpher
 * Command Index::

+* News::                        Changes introduced by major releases
+* Acknowledgements::            Contributors to Elpher

 
 @detailmenu
  --- The Detailed Node Listing ---
 
 @detailmenu
  --- The Detailed Node Listing ---


@@ -69,6 +73,7 @@ Navigation
 
 @end detailmenu
 @end menu
 
 @end detailmenu
 @end menu

+

 @end ifnottex
 
 @macro keycmd{key,cmd}
 @end ifnottex
 
 @macro keycmd{key,cmd}


@@ -133,10 +138,10 @@ to follow the instructions at @url{https://melpa.org/#/getting-started}.
 @kbd{M-x package-delete @key{RET} elpher @key{RET}}.
 @end 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://alexschroeder.ch/cgit/elpher}, adding it to a directory
-in your @code{load-path}, and then adding
+It is also possible to install Elpher directly by downloading the file
+@file{elpher.el} from @url{gopher://thelambdalab.xyz/1/projects/elpher}
+(you'll need to download the ``source archive'' and extract it), adding
+it to a directory in your @code{load-path}, and then adding

 
 @example
 (require 'elpher)
 
 @example
 (require 'elpher)


@@ -199,7 +204,7 @@ a prefix:
 @chapter Navigation
 Throughout this manual, we use the word ``page'' to refer to any
 visualization of a response from a gopher or gemini server, be it a
 @chapter Navigation
 Throughout this manual, we use the word ``page'' to refer to any
 visualization of a response from a gopher or gemini server, be it a

-menu/directory, query result, text file or image.  We use
+menu/directory, query result, text file or image.

 
 Elpher's navigation interface is inspired by the Emacs Info mode.
 Movement within a page is essentially the same as moving
 
 Elpher's navigation interface is inspired by the Emacs Info mode.
 Movement within a page is essentially the same as moving


@@ -280,7 +285,7 @@ Moving to a different page can be accomplished in several ways,
 described by the following command:
 
 @table @asis
 described by the following command:
 
 @table @asis

-@keycmd{@key{RET}\, @kbd{mouse-1}, elpher-follow-link}
+@keycmd{@key{RET}\, @key{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:
 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:


@@ -334,7 +339,7 @@ structure of selectors.
 @keycmd{@key{O}, elpher-root-dir}
 Open the root page (empty selector) on the current host.
 
 @keycmd{@key{O}, elpher-root-dir}
 Open the root page (empty selector) on the current host.
 

-@keycmd{@key{u}\, @key{-}\, @key{^}\, @kbd{mouse-3}, elpher-back}
+@keycmd{@key{u}\, @key{-}\, @key{^}\, @key{mouse-3}, 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
 Return to the previous page, where ``previous'' means the page where the
 page which was displayed immediately before the current page.
 @end table


@@ -380,48 +385,64 @@ Elpher actually maintains two histories, and there are two different
 commands to access them:
 
 @table @asis
 commands to access them:
 
 @table @asis

-@keycmd{@key{s}, elpher-history}
+@keycmd{@key{s}, elpher-show-history}

 This shows the history of the current buffer. This shows all the links
 you would visit if you were to use @key{u} again and again.
 
 This shows the history of the current buffer. This shows all the links
 you would visit if you were to use @key{u} again and again.
 

-@keycmd{@key{S}, elpher-history-all}
+@keycmd{@key{S}, elpher-show-visited-pages}

 This shows the entire Elpher browsing history. It includes all the
 This shows the entire Elpher browsing history. It includes all the

-pages you visited using other Elpher buffers, and it includes buffers
-you later killed.
+pages you visited in your current Emacs session.

 
 @end table
 
 @node Bookmarks, Gopher character encodings, Navigation, Top
 @chapter Bookmarks
 
 
 @end table
 
 @node Bookmarks, Gopher character encodings, Navigation, Top
 @chapter Bookmarks
 

-Elpher makes use of standard Emacs bookmarks. @xref{Bookmarks, , ,
-emacs, The Emacs Editor}. The following commands are perhaps the most
-useful ones:
+Elpher makes use of standard Emacs bookmarks.
+@xref{Bookmarks, , , emacs, The Emacs Editor}.
+The following commands are used to add new bookmarks:

 
 @table @asis
 
 @table @asis

-@keycmd{@key{a}, elpher-set-bookmark-no-overwrite}
+@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.
 
 Add a bookmark for the link at point.  The minibuffer will prompt for
 a name for the bookmark, which defaults to the display string.
 

-@keycmd{@key{A}, bookmark-set-no-overwrite}
+@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.
 
 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.
 

-@keycmd{@key{B}, bookmark-bmenu-list}
-Open a page displaying all current bookmarks. This is where you can
-delete and search bookmarks, for example.
+
+@keycmd{@key{B}, elpher-open-bookmarks}
+Visit a page displaying all elpher bookmarks. 
+The behaviour of the this function depends on the customization variable
+@code{elpher-use-emacs-bookmark-menu}.  If nil (the default), the
+command will visit a special elpher page listing all elpher-specific
+bookmarks.  If non-nil, the command will simply open the standard Emacs
+bookmark list displaying all current bookmarks (including non-elpher
+bookmarks).
+
+@keycmd{@kbd{C-x r l}, bookmark-bmenu-list}
+This command opens the standard Emacs bookmark menu, with which bookmarks
+can be renamed, deleted or annotated.

 
 @end table
 
 
 @end table
 

-If all your bookmarks disappeared in an upgrade from 2.10 to 2.11, you
-can import your old Elpher bookmarks into your Emacs bookmarks using
+On opening the bookmarks page, elpher will offer to import any legacy
+(2.x) bookmarks files into the new system. Once the import is complete,
+the original bookmarks file will have ``-legacy'' appended to it, so
+so that elpher knows not to import it again.
+
+If you have any other legacy bookmark files (besides the one in the
+original location, or specified in the @code{elpher-bookmarks-file}
+customization variable, which should be automatically detected), you can
+can import these using

 
 @example
 @kbd{M-x elpher-bookmark-import @key{RET}}
 @end example
 
 
 @example
 @kbd{M-x elpher-bookmark-import @key{RET}}
 @end example
 

-Once this is done, you can delete the file with the Elpher bookmarks.
+Once this is done, you may delete these legacy bookmarks files.

 
 @node Gopher character encodings, Encrypted gopher connections, Bookmarks, Top
 @chapter Gopher character encodings
 
 @node Gopher character encodings, Encrypted gopher connections, Bookmarks, Top
 @chapter Gopher character encodings


@@ -434,8 +455,8 @@ characters.  To do this properly requires knowledge of the encoding
 system used by whoever authored the document.
 
 Unfortunately gopher lacks a systematic way of acquiring this necessary
 system used by whoever authored the document.
 
 Unfortunately gopher lacks a systematic way of acquiring this necessary

-information. Thus, the details of the coding system must be either inferred from the binary data,
-or must be specified by the user.
+information. Thus, the details of the coding system must be either
+inferred from the binary data, or must be specified by the user.

 
 By default, Elpher applies Emacs' built-in character encoding detection
 system to the full (undecoded) response data and uses this to attempt to
 
 By default, Elpher applies Emacs' built-in character encoding detection
 system to the full (undecoded) response data and uses this to attempt to


@@ -610,7 +631,7 @@ certificate file pair are erased from memory.  Furthermore, in the case
 of throw-away certificates, the corresponding files are deleted.
 
 
 of throw-away certificates, the corresponding files are deleted.
 
 

-@node Finger support, Customization, Gemini support, Top
+@node Finger support, Local files, Gemini support, Top

 @chapter Finger support
 
 Incidentally, Elpher has native support for querying finger servers.
 @chapter Finger support
 
 Incidentally, Elpher has native support for querying finger servers.


@@ -643,7 +664,63 @@ Thus @code{finger://user@@hostname} and @code{finger://hostname/user} are both e
 (The precedence of the /user notation over the user@ notation reflects a
 preference of the community.)
 
 (The precedence of the /user notation over the user@ notation reflects a
 preference of the community.)
 

-@node Customization, Command Index, Finger support, Top
+@node Local files, About pages, Finger support, Top
+@chapter Local files
+
+Elpher supports opening local files via @samp{file:} URLs.
+
+For instance, pressing @key{g} and entering @code{file:~/document.gmi}
+will load the file named @samp{document.gmi} in your home directory,
+provided this file exists.
+
+Files opened in this way are rendered according to their name, and in
+particular their extension.  The current mappings are as follows:
+
+@table @asis
+
+@item @samp{txt}
+
+Plain text documents.  All local text files are assumed to be
+UTF-8-encoded.
+
+@item @samp{gophermap},@samp{gopher}
+
+Gophermap files, i.e. files containing a valid directory list as specified
+by RFC 1436.
+
+@item @samp{gemini},@samp{gmi}
+
+Gemini documents (i.e. documents of MIME type ``text/gemini'').  All
+local gemini files are assumed to be UTF-8-encoded.
+
+@item @samp{html},@samp{htm}
+
+HTML documents.  All local HTML files are assumed to be UTF-8-encoded.
+
+@item @samp{png},@samp{jpg},@samp{jpeg},@samp{gif},@samp{bmp},@samp{tif},@samp{tiff}
+
+Image files.
+
+@item Anything else
+A binary document, which elpher will simply offer to save somewhere
+else. (Obviously this is not useful in its own right, but there's not
+much that elpher can sensibly do with unknown binary files.)
+
+@end table
+
+
+@node About pages, Customization, Local files, Top
+@chapter About pages
+
+Like other browsers, elpher makes certain internally-generated pages
+such as the initial welcome page, the bookmarks page, the history
+stack and the list of visited pages pages accessible as URLs with
+the ``about:'' type.
+
+This means that these pages can be bookmarked and, more usefully,
+added to a local file to be rendered as a user-defined start page.
+
+@node Customization, Command Index, About pages, Top

 @chapter Customization
 
 Various parts of Elpher can be customized via the 
 @chapter Customization
 
 Various parts of Elpher can be customized via the 


@@ -663,11 +740,149 @@ to display buffer headers, how to deal with ANSI escape sequences in
 text, the timeout to impose on network connections, and whether to
 prompt for confirmation when switching away from TLS.
 
 text, the timeout to impose on network connections, and whether to
 prompt for confirmation when switching away from TLS.
 

+One particularly important customization is the @code{elpher-start-page-url}
+variable, which holds the URL of the page displayed initially when
+elpher starts, and when @key{U} is pressed.  By default this is set to
+@samp{about:welcome}, but any URL can be substituted.  For example, you
+might want to create a text/gemini file named
+@samp{~/.emacs/start-page.gmi} containing useful links and set the value
+of @code{elpher-start-page-url} to @samp{file:~/.emacs/start-page.gmi} to have
+these links displayed at startup.  Alternatively, you might prefer
+to set the value to @samp{about:bookmarks} so that the bookmarks page
+is used as the start page instead.
+

 See the customization group itself for details.
 
 See the customization group itself for details.
 

-@node Command Index,  , Customization, Top
+@node Command Index, News, Customization, Top

 @unnumbered Command Index
 
 @printindex fn
 
 @unnumbered Command Index
 
 @printindex fn
 

+@node News, Acknowledgements, Command Index, Top
+@chapter News
+
+This chapter documents the major changes introduced by Elpher releases.
+
+@section v3.2.0
+
+This version introduces several minor changes which, together, make it
+possible to set up alternative start pages configured to your liking.
+
+@subsection About pages
+
+Special elpher pages such as the welcome page (previously ``start''
+page), the bookmarks page, the browsing history stack and list of
+visited pages are now addressible via @samp{about:} URLs.  For instance,
+the standard welcome page has the address @samp{about:welcome}.
+
+@subsection Local files
+
+Local files can now be opened in elpher using @samp{file:} URLs. For
+example, @kbd{g @samp{file:~/my-start.gmi}} will open
+@samp{~/my-start.gmi} as a text/gemini document. @pxref{Local files}
+for details.
+
+@subsection Customizable start pages
+
+The new customization variable @code{elpher-start-page-url} contains the URL
+of the document to be loaded as elpher's ``start page''.  By default
+this is set to @samp{about:welcome}, but any elpher-accessible URL is
+valid. @pxref{Customization} for suggestions.
+
+@section v3.1.0
+
+@subsection Bookmarks system
+
+While Elpher bookmarks are still handled by the Emacs bookmark
+system, this release introduces the option to retain the
+original elpher bookmark page for the purpose of visiting those
+bookmarks.  In v3.1.0, @key{B} visits this page (and adds it to
+the history stack, as in previous versions), which can be interacted
+with using the standard elpher key bindings.
+
+Of course you can still view the bookmarks in the Emacs bookmark
+menu, which you can access from anywhere using the default
+binding @kbd{C-x r l} (or by following the link from the Elpher bookmarks
+page).  Indeed you will need to use this to rename, delete or otherwise
+edit your bookmarks.
+
+If you prefer to avoid using the Elpher bookmark page entirely, you
+use the customization variable @code{elpher-use-emacs-bookmark-menu}
+to have the @key{B} key open the Emacs bookmark menu directly, as in
+the previous release.
+
+@section v3.0.0
+
+@subsection Bookmarks system
+
+Bookmarks are now handled by Emacs' own bookmark management system,
+instead of Elpher's own system.
+(For details, @xref{Bookmarks, , , emacs, The Emacs Editor}.)
+This means two things.  Firstly,
+the bookmarks file (elpher-bookmarks by default) and format used by
+previous versions are now deprecated.  If these are detected, Elpher
+will offer to import your old bookmarks when you first accessing the
+bookmark list with the new version.  A suffix will be added to your
+old bookmarks file so that Elpher knows that the import is complete.
+
+Secondly, the old Elpher bookmark menu has been removed in the new
+version.  Instead, @key{B} brings up the menu provided by the Emacs
+function @code{bookmark-bmenu-list}. This has different key and mouse
+bindings to Elpher's old menu, but is much more functional.  Bookmarks
+can be renamed, deleted in groups, and much more.  (Use @kbd{C-h m} with
+the menu open to see the complete list.)
+
+@subsection History
+
+Browsing history can now be accessed via new bindings to @key{s} and @key{S}.
+The former shows the current history ``stack'' (pages accessible with
+the @key{u} key), while the latter shows a list of all pages which have
+been visited in the current session.
+
+@subsection Socks connections
+
+Elpher can now use socks connections to browse via TOR.
+
+@subsection browse-url, Org and mu4e integration
+
+These integrations provide support for elpher-handling of gemini, gopher
+and finger URLs using @code{browse-url}, in Org documents, and the mu4e
+mail system.
+
+@subsection imenu integration
+
+Gemini document headers are now navigable via imenu.
+For details, @xref{Imenu, , , emacs, The Emacs Editor}.
+
+@node Acknowledgements,  , News, Top
+@chapter Acknowledgements
+
+Elpher was originally written by Tim Vaughan. Recent maintenance has
+been done by and with the help of Alex Schroeder. In addition, the
+following people (in alphabetical order) have generously provided
+assistance and/or patches:
+
+@itemize
+@item Alexis
+@item Christopher Brannon
+@item Zhiwei Chen
+@item condy0919
+@item Étienne Deparis
+@item Roy Koushik
+@item Simon Nicolussi
+@item Noodles!
+@item Jens Östlund
+@item Abhiseck Paira
+@item F. Jason Park
+@item Omar Polo
+@item Koushk Roy
+@item Michel Alexandre Salim
+@item Alex Schroeder
+@item Daniel Semyonov
+@item Simon South
+@item Bradley Thornton
+@item Vee
+@end itemize
+
+

 @bye
 @bye