\input texinfo @c -*-texinfo-*-
@setfilename elpher.info
-@settitle Elpher Manual v1.0.0
+@settitle Elpher Manual v2.0.0
@dircategory Emacs
@direntry
* Bookmarks:: How to record and visit bookmarks
* Character encodings:: How Elpher handles different character encodings
* Encrypted connections:: How and when TLS is enabled
+* Gemini support:: Support for the Gemini protocol
+* Finger support:: Support for the Finger protocol
* Customization:: How to customize various aspects of Elpher
* Command Index::
+
+@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
@node Introduction, Installation, Top, Top
@item
direct visualization of image files where supported (no writing to
-disk), and
+disk),
@item
-a simple bookmark management system.
+a bookmark management system,
+
+@item
+basic support for the new ``heavier than gopher, lighter than the web'' Gemini protocol,
+
+@item
+support for the Finger protocol.
+
@end itemize
Elpher is still under active development. Although we try very hard to
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
+@url{gopher://thelambdalab.xyz/1/projects/elpher/}, adding it to a directory in
your @code{load-path}, and then adding
@example
This is similar to @code{elpher-download}, but instead applies to the
current page rather than a link.
-@keycmd{@key{w}, 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.
cached for the duration of the Emacs session.
@keycmd{@key{g}, elpher-go}
-Open a particular page by specifying either its URL or directly entering
-a host, port and selector.
+Open a particular page by specifying either its full URL or just entering
+a gopher host name.
+
+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.
+
+@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 no guarantees about the
+structure of selectors.
@keycmd{@key{O}, elpher-root-dir}
Open the root page (empty selector) on the current host.
-@keycmd{@key{u}, elpher-back}
+@keycmd{@key{u}\, @kbd{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
@key{R}.
-@node Encrypted connections, Customization, Character encodings, Top
+@node Encrypted connections, Gemini support, Character encodings, Top
@chapter Encrypted connections
While RFC 1436 does not broach the topic of encryption at all, several
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 connections, Top
+@chapter Gemini support
+
+@uref{gopher://gemini.circumlunar.space, Gemini}
+is a new protocol being devloped 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 benifits.
+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 seemless navigation 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.
+
+Like gopher, the gemini specification concerns both the protocol
+ 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 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 posesses 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
+amongst levels. On terminal systems, the level is indicated by the
+number of preceeding # 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. Additionally, the use of
+client TLS certicificates is still not yet supported.
+
+@node Finger support, Customization, 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, Command Index, Encrypted connections, Top
+@node Customization, Command Index, Finger support, Top
@chapter Customization
Various parts of Elpher can be customized via the
the appearance of Elpher, including one face per menu item type.
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, whether to look for naked URLs in
-gopher menus (as opposed to just plain text files), and whether
-to prompt for confirmation when switching away from TLS.
+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.
See the customization group itself for details.
The Lambda Lab / projects / elpher.git / blobdiff