X-Git-Url: https://thelambdalab.xyz/gitweb/index.cgi?p=elpher.git;a=blobdiff_plain;f=elpher.texi;h=406dd8b2ef18e2c55aabda19d59b1ec2a825e468;hp=54eea80bd772fee2bec42492b4257f21f5fca043;hb=aff8a4eeb2bcd7a2b23f8d1480eadc020aa77361;hpb=8c20802c5f2262440dadbdca60b7901d09ca022f

diff --git a/elpher.texi b/elpher.texi
index 54eea80..406dd8b 100644
--- a/elpher.texi
+++ b/elpher.texi
@@ -55,6 +55,8 @@ the file COPYING in the same directory as this file for more details.
 * 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
+* 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::
 * News::                        Changes introduced by major releases
@@ -629,7 +631,7 @@ certificate file pair are erased from memory.  Furthermore, in the case
 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.
@@ -662,7 +664,62 @@ 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.)
 
-@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{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
+
+Sadly, due to particulars of the format, gophermap files (i.e. files
+containing literally the intended output of querying a directory
+selector according to RFC 1436) cannot be rendered using @samp{file:}.
+
+
+@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 
@@ -682,6 +739,17 @@ 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.
 
+One particularly important customization is the @code{elpher-start-page}
+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} 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.
 
 @node Command Index, News, Customization, Top
@@ -694,6 +762,32 @@ See the customization group itself for details.
 
 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} 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
@@ -777,6 +871,7 @@ assistance and/or patches:
 @item Simon Nicolussi
 @item Noodles!
 @item Jens Östlund
+@item Abhiseck Paira
 @item F. Jason Park
 @item Omar Polo
 @item Koushk Roy