\input texinfo @c -*-texinfo-*-
-@c %**start of header
+
@setfilename elpher.info
-@settitle Elpher Manual v1.0.0
-@c %**end of header
+@settitle Elpher Manual v3.2.2
+
+@dircategory Emacs
+@direntry
+* Elpher: (elpher). A gopher and gemini client for Emacs.
+@end direntry
@copying
-This manual documents Elpher, a gopher client for Emacs.
+This manual documents Elpher, a gopher and gemini client for Emacs.
-Copyright @copyright{} 2019 Tim Vaughan
+Copyright @copyright{} 2019, 2020, 2021 Tim Vaughan@*
+Copyright @copyright{} 2021 Daniel Semyonov@*
+Copyright @copyright{} 2021 Alex Schroeder
@quotation
The source and documentation of Elpher is free software. You can
@end copying
@titlepage
-@title Elpher Gopher Client Manual
+@title Elpher Gopher and Gemini Client Manual
@author Tim Vaughan
@page
@top Elpher
@insertcopying
-@end ifnottex
@menu
* Introduction:: Elpher Overview: what's this all about?
* Quick Start:: Get up and running quickly
* Navigation:: Fundamentals of Elpher navigation
* Bookmarks:: How to record and visit bookmarks
-* Character encodings:: How Elpher handles different character encodings
-* Encrypted connections:: How and when TLS is enabled
+* Gopher character encodings:: How Elpher selects encodings for gopher pages
+* 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
-* Index::
+* Command Index::
+* News:: Changes introduced by major releases
+* Acknowledgements:: Contributors to Elpher
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Navigation
+
+* Within-page navigation:: Moving about within a page
+* Between-page navigation:: Commands for moving between pages
+* History and Caching:: Explanation of how Elpher represents history
+
+@end detailmenu
@end menu
+@end ifnottex
+
+@macro keycmd{key,cmd}
+@item \key\ (@code{\cmd\})
+@findex \cmd\
+@end macro
+
@node Introduction, Installation, 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:
+Elpher aims to be a capable and practical gopher and gemini 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
+followable web and gopher links in plain text,
+
@item
an easily navigable history, sporting caching of visited pages (both
content and cursor position),
auto-completing menu item navigation,
@item
-followable web and gopher links in plain text,
+direct visualization of image files where supported (no writing to
+disk),
@item
-direct visualization of image files where supported (no writing to
-disk), and
+basic support for the new ``heavier than gopher, lighter than the web'' Gemini protocol,
@item
-a simple bookmark management system.
+support for the Finger protocol.
+
@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
+can likely by incorporated quickly, so please get in touch if you
have some ideas.
@node Installation, Quick Start, Introduction, Top
@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://github.com/tgvaughan/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)
To return to the page you just followed the link from, press @key{u}.
Elpher caches (for the duration of an Emacs session) both page contents
-and the position of point on each of the pages (gopher menus, query
-results, or text pages) you visit, restoring these when you next visit
-the same page. Thus, pressing @key{u} displays the previous page in
-exactly the same state as when you left, meaning that you can quickly
-and visually explore the different documents in a menu without having to
-wait for anything to reload.
+and the position of point on each of the pages (gopher menus, gemini
+pages, query results, or text pages) you visit, restoring these when you
+next visit the same page. Thus, pressing @key{u} displays the previous
+page in exactly the same state as when you left, meaning that you can
+quickly and visually explore the different documents in a menu without
+having to wait for anything to reload.
Of course, sometimes you'll @emph{want} to reload the current page
rather than stick with the cached version. To do this use @key{R}.
(This is particularly useful for search query results, where this
allows you to perform a different search.)
-That's more-or-less it. Elpher supports a number of other features, such
-as bookmarking, support for different coding schemes and TLS encryption,
-and a variety of customization options, all of which are explained in
-the rest of this document. However the emphasis is on keeping the basic
+That's more-or-less it. Elpher supports a number of other features,
+such a support for different coding schemes and TLS encryption, and a
+variety of customization options, all of which are explained in the
+rest of this document. However the emphasis is on keeping the basic
navigation experience as intuitive and responsive as possible.
+Note that you can launch multiple Elpher sessions in parallel by using
+a prefix:
+
+@example
+@kbd{C-u M-x elpher @key{RET}}
+@end example
+
@node Navigation, Bookmarks, Quick Start, Top
@chapter Navigation
-by
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
+visualization of a response from a gopher or gemini server, be it a
+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
links and menu items.
@table @asis
-@item @key{TAB} (@code{elpher-next-link})
+@keycmd{@key{TAB}, elpher-next-link}
Move to the next link or menu item in the file.
-@item @kbd{Shift-@key{TAB}}/@key{backtab} (@code{elpher-prev-link})
+@item @kbd{Shift-@key{TAB}} or @key{BACKTAB} (@code{elpher-prev-link})
+@findex elpher-prev-link
Move to the previous link or menu item in the file.
-@item @kbd{m} (@code{elpher-jump})
+@keycmd{@key{m}, 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})
+@keycmd{@key{i}, elpher-info-link}
Display host, port and selector information for the link at point.
-@item @kbd{I} (@code{elpher-info-current})
+@keycmd{@key{I}, elpher-info-current}
Display host, port and selector information for the current page.
-@item @kbd{c} (@code{elpher-copy-link-url})
+@keycmd{@key{c}, 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})
+@keycmd{@key{C}, elpher-copy-current-url}
Add URL representing address of the current page to the kill-ring and
the system clipboard (if available).
-@item @kbd{d} (@code{elpher-download})
+@keycmd{@key{d}, elpher-download}
Download link at point and save the result as a file. The minibuffer
will prompt for the name of the file to write, with the default name being
the display string (if available) associated with the link.
-@item @kbd{D} (@code{elpher-download-current})
-This is similar to @code{elpher-downlowd}, but instead applies to the
+@keycmd{@key{D}, elpher-download-current}
+This is similar to @code{elpher-download}, but instead applies to the
current page rather than a link.
-@item @kbd{w} (@code{elpher-view-raw})
+@keycmd{@key{.}, elpher-view-raw}
This displays the raw server response for the current page. While not
useful for general browsing, it is useful for debugging incorrect rendering
or out-of-spec server responses.
described by the following command:
@table @asis
-@item @kbd{RET}, @kbd{mouse-1} (@code{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:
@itemize
@item
-For text or menu type items or links, the curent page text is replaced
+For text or menu type items or links, the current 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.
@item
Following links of type `h' with a selector having the `URL:' prefix, or
-non-gopher URLs in text files, will result in Elpher using an external
+unsuported URLs in text files, will result in Elpher using an external
programme to open the URL. This will be either the default system browser
or, if the @code{elpher-open-urls-with-eww} customization variable is non-nil,
Emacs' own EWW browser. (See @pxref{Customization}.)
Once a text, menu or query response page has been displayed, its contents are
cached for the duration of the Emacs session.
-@item @kbd{g} (@code{elpher-go})
-Open a particular page by specifying either its URL or directly entering
-a host, port and selector.
+@keycmd{@key{g}, elpher-go}
+Open a particular page by specifying either its full URL or just
+entering a gopher host name. (The protocol defaults to gopher, so gemini
+links must include the @code{gemini://} prefix.
+
+If a unsupported protocol is used in the URL the result will be the same
+as following a URL link of the same type from a link in a page.
+
+@keycmd{@key{o}, elpher-go-current}
+Prompts for a URL similar to @code{elpher-go}, but initialized to the URL
+of the current page. This allows you to easily try other selectors for the
+same server.
-Note that if a non-gopher protocol is used in the URL the result will be
-the same as following a URL link of the same type from a gopher menu.
+Remember however, that the Gopher RFC 1436 provides @emph{no} guarantees about the
+structure of selectors.
-@item @kbd{O} (@code{elpher-root-dir})
+@keycmd{@key{O}, elpher-root-dir}
Open the root page (empty selector) on the current host.
-@item @kbd{u} (@code{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
@end enumerate
The only way to return to pages in this history is by using @key{u},
-which returns to the previous of the current page.
-@footnote{The addition of the new page to the history happens even if
-the new page is one that has been seen before. This is mostly the
-desired behaviour. However, opening an explicit ``back'' link provided
-by a gopher menu will also add a new entry to the history. Unless you
+which returns to the previous of the current page. @footnote{The
+addition of the new page to the history happens even if the new page is
+one that has been seen before. This is mostly the desired behaviour.
+However, opening an explicit ``back'' link provided by a gopher menu or
+gemini page will also add a new entry to the history. Unless you
haven't yet visited that menu, it's therefore better to use @key{u} to
go back in this case.}
from a given page. This means that, at least for links followed from menus
and text files, the inverse of @key{u} is actually just @key{RET}.
+Elpher actually maintains two histories, and there are two different
+commands to access them:
+
+@table @asis
+@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.
+
+@keycmd{@key{S}, elpher-show-visited-pages}
+This shows the entire Elpher browsing history. It includes all the
+pages you visited in your current Emacs session.
-@node Bookmarks, Character encodings, Navigation, Top
+@end table
+
+@node Bookmarks, Gopher character encodings, Navigation, Top
@chapter Bookmarks
-Elpher has a very simple link bookmarking system involving the
-following commands:
+Elpher makes use of standard Emacs bookmarks.
+@xref{Bookmarks, , , emacs, The Emacs Editor}.
+The following commands are used to add new bookmarks:
@table @asis
-@item @key{a} (@code{elpher-bookmark-link})
+@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.
-@item @key{A} (@code{elpher-bookmark-current})
+@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.
-@item @key{x} (@code{elpher-unbookmark-link})
-Immediately remove the bookmark (if one exists) to the link at point.
-@item @key{X} (@code{elpher-unbookmark-current})
-Immediately remove the bookmark (if one exists) to the current page.
+@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.
-@item @key{B} (@code{elpher-bookmarks})
-Open a page displaying all current bookmarks. Note that this bookmark
-page is added to the history just as if you had opened it using a link.
-Thus to return to the previous page, use @kbd{u}. This also means
-that you can peruse the various bookmarks by visiting them in turn,
-using @kbd{u} to return to the bookmark page (where the position of point
-is cached), then moving to another bookmarked link and so on.
@end table
-Bookmarks are stored as a s-exp in the file @file{elpher-bookmarks}
-in the user emacs directory (usually @file{~/.emacs.d/}).
-Any command which modifies the list of bookmarks immediately updates
-this file.
+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
+
+Once this is done, you may delete these legacy bookmarks files.
-@node Character encodings, Encrypted connections, Bookmarks, Top
-@chapter Character encodings
+@node Gopher character encodings, Encrypted gopher connections, Bookmarks, Top
+@chapter Gopher character encodings
Responses Elpher retrieves from servers are initially read as pure
binary data. When the data is intended to be interpreted as textual (as
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
convert it into a character string.
(See @pxref{Recognize coding, Recognizing coding systems, ,emacs}.) While
-this approach can be okay, it is important to realise that its inference
+this approach can be okay, it is important to realize that its inference
algorithm is extremely primitive and depends heavily on assumptions based
on the language settings of your emacs system.
using the following command:
@table @asis
-@item @key{S} (@code{elpher-set-coding-system})
+@keycmd{@key{!},elpher-set-coding-system}
Causes a elpher to prompt for a coding system to use for decoding
-future text. The @key{TAB} key can be used at this prompt to display a
-list of alternatives (which is extensive) and to autocomplete. An empty
-response will cause Elpher to return to its default autodetection
+future gopher text. The @key{TAB} key can be used at this prompt to display a
+list of alternatives (which is extensive) and to auto-complete. An empty
+response will cause Elpher to return to its default auto-detection
behaviour.
@end table
@key{R}.
-@node Encrypted connections, Customization, Character encodings, Top
-@chapter Encrypted connections
+@node Encrypted gopher connections, Gemini support, Gopher character encodings, Top
+@chapter Encrypted gopher connections
While RFC 1436 does not broach the topic of encryption at all, several
modern gopher servers can serve content over encrypted connections,
In this case Elpher will prompt for your confirmation to ensure that
you can't accidentally make a non-TLS connection.
+@node Gemini support, Finger support, Encrypted gopher connections, Top
+@chapter Gemini support
+
+@uref{gopher://gemini.circumlunar.space, Gemini}
+is a new protocol being developed by several members of
+gopherspace. It aims to solve some of the long-standing technical
+issues associated with gopher as a protocol, while keeping the major benefits.
+For instance, it _requires_ encrypted connections, it does away with
+the selector type, and allows servers to explicitly specify the
+character coding scheme used for text documents.
+
+The latest versions of Elpher aim to provide seamless transitions between
+gemini and gopher documents. Basically you should be able to open,
+bookmark, download and otherwise interact with gemini pages in exactly
+the same way as you do with other non-gemini pages. The only major
+difference from your perspective as a user is that you should no longer
+have to worry about manually toggling TLS on or off (for gemini it's
+always on), and you should never have to manually set a character coding
+scheme.
+
+The gemini protocol specification recommends a Trust on First Use (TOFU)
+behaviour when validating gemini server TLS certificates. This is
+because many gemini servers rely on self-signed certificates rather
+than certificates signed by a CA. Sadly however, this TOFU behaviour is
+far from straight-forward to configure using Emacs' existing Network
+Security Manager. For this reason, elpher defaults to performing no
+certificate verification by default. This behaviour can be easily
+customized by setting the @code{elpher-gemini-TLS-cert-checks}
+customization variable to non-nil.
+
+The gemini specification concerns both the protocol and a simple text
+document format (mimetype text/gemini) which is like a mixture between
+gophermap files and markdown-formatted files but simpler than both.
+Elpher renders gemini responses which are provided in this format in
+line with the rules in the spec. This includes wrapping long lines at
+word boundaries. The specific column at which this text is wrapped is
+defined by the customization variable
+@code{elpher-gemini-max-fill-width}, which is set to 80 columns by
+default. (This is slightly wider than Emacs' default fill width of 70
+columns due to the fact that there are a significant amount of older
+gemini content which, against the advice of the current spec, hard wraps
+at <80 columns. The larger default allows this to still look okay,
+while still keeping content without hard wraps looking pleasant.)
+
+The text/gemini format also possesses a section header syntax similar to
+markdown. Elpher allows different header levels to be drawn with
+different, customizable, faces. By default, on graphically-capable
+emacs systems, these faces are given different heights to distinguish
+among levels. On terminal systems, the level is indicated by the
+number of preceding # symbols.
+
+I should emphasize however that, while it is definitely functional,
+Elpher's gemini support is still experimental, and various aspects will
+change as the protocol develops further.
+
+@section Client Certificates for Gemini
+
+Gemini makes explicit use of the client certificate mechanism that TLS
+provides for allowing clients to authenticate themselves with servers.
+The Gemini specification suggests two distinct classes of client
+certificates: short-lived certificates used to identify you for a single
+session, and more permanent certificates used to identify you over a
+longer time period.
+
+When Elpher receives a request for a client certificate from a server,
+it will present you with the option to create and use a single-use
+``throwaway'' certificate, or to use a ``persistent''
+certificate (optionally creating it or installing pre-existing key and
+certificate files).
+
+Certificate creation in Elpher requires an installation of OpenSSL, and
+---in particular---that Elpher be able to run the @command{openssl} command-line
+utility. By default, Elpher assumes that the @command{openssl} is on the
+system path, but the precise location can be set by customizing the
+@code{elpher-openssl-command} variable.
+
+Each generated certificate results in the creation of a .key file and
+a .crt file. In the case of a throwaway certificate, these files are
+stored in the temporary directory indicated by the Emacs variable
+@code{temporary-file-directory} and are deleted when ``forgotten''
+(as described below).
+
+In the case of persistent certificates, these files are stored in the
+folder defined by the Elpher variable
+@code{elpher-certificate-directory}, and are never deleted by Elpher.
+(Of course you can delete them yourself whenever you like.)
+The base name of the files (i.e. sans extension) is what Elpher uses
+to identify the certificate.
+
+Using throwaway certificates is as simple as pressing the @key{t}
+key at the prompt which appears following a certificate request from
+a server. There is nothing more to do.
+
+Using a persistent certificate requires instead selecting @key{p} from the same
+menu. This will result in Elpher asking you for the name identifying
+the certificate. This entry autocompletes to the list of known certificate
+names, so you can use @key{TAB} to display the list.
+
+In the case that you choose a name that does not belong to the list of
+known certificates, Elpher will offer to create one for you or to
+``install'' one from existing key and certificate files.
+Pressing the @key{n} key will cause Elpher to begin the process of
+creating a new persistent certificate, using some additional
+details for which you will be prompted.
+Alternatively, pressing the @key{i} key will cause Elpher to ask for the
+locations of edisting key and certificate files to add to
+@code{elpher-certificate-directory} under the chosen name.
+
+Once a certificate is selected, it will be used for all subsequent TLS
+transactions to the host for which the certificate was created.
+It is immediately ``forgotten'' when a TLS connection to another host
+is attempted, or the following command is issued:
+
+@table @asis
+@keycmd{@key{F},elpher-forget-certificate}
+Causes Elpher to immediately forget any currently-loaded client certificate.
+@end table
+
+In either case, ``forgetting'' means that the details of the key and
+certificate file pair are erased from memory. Furthermore, in the case
+of throw-away certificates, the corresponding files are deleted.
+
+
+@node Finger support, Local files, Gemini support, Top
+@chapter Finger support
+
+Incidentally, Elpher has native support for querying finger servers.
+Of course, one could argue that this functionality is more easily
+provided by one's local telnet client. However finger URLs do appear
+on occasion in gopherspace, and it's nice to be able to open them
+in place.
+
+Elpher interprets @code{finger://} URLs as follows:
+
+@itemize
+
+@item
+The host is determined by the host name portion of the URL.
+
+@item
+In the case that the @emph{file name} portion of the URL is non-empty (besides
+the leading slash), this is interpreted as the user to finger.
+
+@item
+Otherwise, the @emph{user} portion of the URL is interpreted as the user to finger.
+
+@item
+If no user is provided, the root directory of the finger server is requested.
+
+@end itemize
+
+Thus @code{finger://user@@hostname} and @code{finger://hostname/user} are both equivalent.
+
+(The precedence of the /user notation over the user@ notation reflects a
+preference of the community.)
-@node Customization, Index, Encrypted connections, 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
+variables belonging to the elpher customization group, accessible
+using
+@example
+@kbd{M-x customize-group elpher @key{RET}}
+@end example
+@noindent This group contains a number of faces that can be modified to change
+the appearance of Elpher, including one face per menu item type.
-@menu
-* Faces::
-* Other cutomizations::
-@end menu
+The group also contains variables for customizing the behaviour of
+Elpher. This includes how to open arbitrary (non-gopher) URLs, whether
+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-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.
+
+@node Command Index, News, Customization, Top
+@unnumbered Command Index
-@node Faces, Other cutomizations, Customization, Customization
-@section Faces
+@printindex fn
-@node Other cutomizations, , Faces, Customization
-@section Other customizations
+@node News, Acknowledgements, Command Index, Top
+@chapter News
-@node Index, , Customization, Top
-@unnumbered Index
+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
-@printindex cp
@bye
The Lambda Lab / projects / elpher.git / blobdiff