\input texinfo @c -*-texinfo-*-
@setfilename elpher.info
-@settitle Elpher Manual v3.3.0
+@settitle Elpher Manual v3.6.0
@dircategory Emacs
@direntry
@copying
This manual documents Elpher, a gopher and gemini client for Emacs.
-Copyright @copyright{} 2019-2022 Tim Vaughan@*
+Copyright @copyright{} 2019-2023 Tim Vaughan@*
Copyright @copyright{} 2021 Daniel Semyonov@*
Copyright @copyright{} 2021 Alex Schroeder
@detailmenu
--- The Detailed Node Listing ---
+Installation
+
+* Installing from ELPA or MELPA:: Installing from a package repository
+* Installing by hand:: Installing directly from the source
+
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
+Gemini support
+
+* Client Certificates for Gemini:: Accessing secure gemini pages
+* Hiding preformatted text in text/gemini documents:: An accessibility option
+
+News
+
+* v3.6.0::
+* v3.5.0::
+* v3.4.0::
+* v3.3.0::
+* v3.2.0::
+* v3.1.0::
+* v3.0.0::
+
@end detailmenu
@end menu
@node Installation, Quick Start, Introduction, Top
@chapter Installation
+@menu
+* Installing from ELPA or MELPA:: Installing from a package repository
+* Installing by hand:: Installing directly from the source
+@end menu
+
+@node Installing from ELPA or MELPA, Installing by hand, Installation, Installation
@section Installing from ELPA or MELPA
Elpher is available on the non-GNU ELPA package archive. If you are
@kbd{M-x package-delete @key{RET} elpher @key{RET}}.
@end example
+@node Installing by hand, , Installing from ELPA or MELPA, Installation
@section Installing by hand
It is also possible to install Elpher directly by downloading the file
described by the following command:
@table @asis
-@keycmd{@key{RET}\, @key{mouse-1}, elpher-follow-link}
+@keycmd{@key{RET}\, @key{mouse-1}, elpher-follow-current-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:
Once a text, menu or query response page has been displayed, its contents are
cached for the duration of the Emacs session.
+@keycmd{S-@key{RET}\, S-@key{mouse-1}, elpher-follow-current-link-new-buffer}
+Create a new Elpher buffer and follow the menu item or link at point
+in the new buffer.
+
@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
Elpher's gemini support is still experimental, and various aspects will
change as the protocol develops further.
+@menu
+* Client Certificates for Gemini:: Accessing secure gemini pages
+* Hiding preformatted text in text/gemini documents:: An accessibility option
+@end menu
+
+@node Client Certificates for Gemini, Hiding preformatted text in text/gemini documents, Gemini support, Gemini support
@section Client Certificates for Gemini
Gemini makes explicit use of the client certificate mechanism that TLS
locations of existing 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:
+Once a certificate is selected, it will be used for all subsequent
+gemini requests involving URLs begining with the URL for for which the
+certificate was created. It is immediately ``forgotten'' when a TLS
+connection to a non-matching URL is attempted, or the following command
+is issued:
@table @asis
@keycmd{@key{F},elpher-forget-certificate}
certificate file pair are erased from memory. Furthermore, in the case
of throw-away certificates, the corresponding files are deleted.
+Persistant client certificates can be added to the alist contained in the
+customization variable @code{elpher-certificate-map} so that they are
+automatically activated whenever a gemini page with the matching URL
+prefix is visited.
+
+@node Hiding preformatted text in text/gemini documents, , Client Certificates for Gemini, Gemini support
+@section Hiding preformatted text in text/gemini documents
+
+Preformatted text is often used to display ``ASCII art'' or other
+similar text-based artwork. While for many this is a fun way to
+introduce personality into their gemini documents, such text can
+pose difficulties for screen readers.
+
+Setting the @code{elpher-gemini-hide-preformatted} customization option
+to non-nil causes Elpher to hide all preformatted text blocks by
+default. In place of the preformatted text, Elpher instead displays the
+``alt text'' (if any is available), along with a button which can be
+used to make specific blocks visible as required.
+
+Other related customization options are
+@code{elpher-gemini-preformatted-toggle-label}, which is the label used
+for the toggle button, and
+@code{elpher-gemini-preformatted-toggle-bullet}, which is the margin
+string used to distinguish the line replacing the preformatted text.
@node Finger support, Local files, Gemini support, Top
@chapter Finger support
This chapter documents the major changes introduced by Elpher releases.
+@menu
+* v3.6.0::
+* v3.5.0::
+* v3.4.0::
+* v3.3.0::
+* v3.2.0::
+* v3.1.0::
+* v3.0.0::
+@end menu
+
+@node v3.6.0, v3.5.0, News, News
+@section v3.6.0
+
+@subsection Easily open links in new buffer
+
+This version includes the ability to open all link types in
+Elpher documents in a new buffer. By default, this is bound
+to S-@key{RET} and S-@key{mouse-1}, but this can be modified
+by adding adjusting the bindings in @code{elpher-link-keymap}.
+
+@node v3.5.0, v3.4.0, v3.6.0, News
+@section v3.5.0
+
+@subsection Automatic activation of client certificates in gemini
+
+This version introduces a new customization variable
+@code{elpher-certificate-map} which allows you to pre-specify
+a set of gemini URLs and the client certificates which should
+be used when accessing them.
+
+@xref{Client Certificates for Gemini} for more details.
+
+@node v3.4.0, v3.3.0, v3.5.0, News
+@section v3.4.0
+
+@subsection Toggling preformatted text visibility
+
+This version introduces the ability to hide preformatted text in
+text/gemini documents by default. To enable this, set the customization
+variable @code{elpher-gemini-hide-preformatted} to non-nil. This causes
+all preformated text blocks to be replaced with their ``alt-text'' (if
+any is available) and a button for toggling the visibility of the text
+block.
+
+This feature is intended to make it easier for people using screen
+readers to read text/gemini documents.
+
+@node v3.3.0, v3.2.0, v3.4.0, News
@section v3.3.0
This version includes lots of bug fixes, as well as a couple of new
@code{elpher-info-current} command (@kbd{I}) always displays both the
decoded IRI and the URI when they differ.)
+@node v3.2.0, v3.1.0, v3.3.0, News
@section v3.2.0
This version introduces several minor changes which, together, make it
this is set to @samp{about:welcome}, but any elpher-accessible URL is
valid. @pxref{Customization} for suggestions.
+@node v3.1.0, v3.0.0, v3.2.0, News
@section v3.1.0
@subsection Bookmarks system
to have the @key{B} key open the Emacs bookmark menu directly, as in
the previous release.
+@node v3.0.0, , v3.1.0, News
@section v3.0.0
@subsection Bookmarks system