Release to allow opening links in new buffer.

[elpher.git] / elpher.texi

diff --git a/elpher.texi b/elpher.texi
index 564e390..56a5fcc 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.2.1
+@settitle Elpher Manual v3.6.0

 
 @dircategory Emacs
 @direntry
 
 @dircategory Emacs
 @direntry


@@ -11,7 +11,7 @@
 @copying
 This manual documents Elpher, a gopher and gemini client for Emacs.
 
 @copying
 This manual documents Elpher, a gopher and gemini client for Emacs.
 

-Copyright @copyright{} 2019, 2020, 2021 Tim Vaughan@*
+Copyright @copyright{} 2019-2023  Tim Vaughan@*

 Copyright @copyright{} 2021 Daniel Semyonov@*
 Copyright @copyright{} 2021 Alex Schroeder
 
 Copyright @copyright{} 2021 Daniel Semyonov@*
 Copyright @copyright{} 2021 Alex Schroeder
 


@@ -23,7 +23,7 @@ version 3, or (at your option) any later version.
 
 Elpher is distributed in the hope that it will be useful, but WITHOUT
 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 
 Elpher is distributed in the hope that it will be useful, but WITHOUT
 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

-FITNElpher FOR A PARTICULAR PURPOSE. See the GNU General Public License in
+FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License in

 the file COPYING in the same directory as this file for more details.
 @end quotation
 @end copying
 the file COPYING in the same directory as this file for more details.
 @end quotation
 @end copying


@@ -57,20 +57,41 @@ the file COPYING in the same directory as this file for more details.
 * Finger support::              Support for the Finger protocol
 * Local files::                 Opening local files in elpher
 * About pages::                 Special pages and how to reference them
 * Finger support::              Support for the Finger protocol
 * Local files::                 Opening local files in elpher
 * About pages::                 Special pages and how to reference them

+* ANSI support::                Notes in Elpher's ANSI support

 * Customization::               How to customize various aspects of Elpher
 * Command Index::
 * News::                        Changes introduced by major releases
 * Customization::               How to customize various aspects of Elpher
 * Command Index::
 * News::                        Changes introduced by major releases

-* Acknowledgements::            Contributors to Elpher
+* Contributors::                Contributors to Elpher

 
 @detailmenu
  --- The Detailed Node Listing ---
 
 
 @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
 
 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
 
 @end detailmenu
 @end menu
 


@@ -122,11 +143,25 @@ have some ideas.
 @node Installation, Quick Start, Introduction, Top
 @chapter Installation
 
 @node Installation, Quick Start, Introduction, Top
 @chapter Installation
 

-Elpher is available from the MELPA package repository.  If you have
+@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
+using Emacs 28 or later, this archive should be available on your system
+by default.  For Emacs 27, you'll need to follow the instructions at
+@url{https://elpa.nongnu.org} to make the archive accessible.
+
+Alternatively, Elpher is available from the MELPA package archive.  If you have

 never installed packages from this repository before, you'll need
 to follow the instructions at @url{https://melpa.org/#/getting-started}.
 
 never installed packages from this repository before, you'll need
 to follow the instructions at @url{https://melpa.org/#/getting-started}.
 

-@noindent To install Elpher, enter the following:
+Once one of these package archives is installed, enter the following to
+install Elpher:

 
 @example
 @kbd{M-x package-install @key{RET} elpher @key{RET}}
 
 @example
 @kbd{M-x package-install @key{RET} elpher @key{RET}}


@@ -138,6 +173,9 @@ 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
 

+@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
 @file{elpher.el} from @url{gopher://thelambdalab.xyz/1/projects/elpher}
 (you'll need to download the ``source archive'' and extract it), 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


@@ -285,7 +323,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}\, @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:
 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:


@@ -310,7 +348,7 @@ causes Elpher to prompt for a filename in which to save the content.
 
 @item
 Following links of type `h' with a selector having the `URL:' prefix, or
 
 @item
 Following links of type `h' with a selector having the `URL:' prefix, or

-unsuported URLs in text files, will result in Elpher using an external
+unsupported 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}.) 
 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}.) 


@@ -320,6 +358,10 @@ 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. 
 
 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
 @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


@@ -563,6 +605,12 @@ 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.
 
 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
 @section Client Certificates for Gemini
 
 Gemini makes explicit use of the client certificate mechanism that TLS


@@ -613,13 +661,14 @@ 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
 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
+locations of existing key and certificate files to add to

 @code{elpher-certificate-directory} under the chosen name.
 
 @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}
 
 @table @asis
 @keycmd{@key{F},elpher-forget-certificate}


@@ -630,6 +679,30 @@ 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.
 
 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
 
 @node Finger support, Local files, Gemini support, Top
 @chapter Finger support


@@ -683,6 +756,11 @@ particular their extension.  The current mappings are as follows:
 Plain text documents.  All local text files are assumed to be
 UTF-8-encoded.
 
 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
 @item @samp{gemini},@samp{gmi}
 
 Gemini documents (i.e. documents of MIME type ``text/gemini'').  All


@@ -703,12 +781,8 @@ much that elpher can sensibly do with unknown binary files.)
 
 @end table
 
 
 @end table
 

-Gophermap files (i.e. files containing literally the intended output of
-querying a directory selector according to RFC 1436) cannot yet rendered
-using @samp{file:}.
-

 
 

-@node About pages, Customization, Local files, Top
+@node About pages, ANSI support, Local files, Top

 @chapter About pages
 
 Like other browsers, elpher makes certain internally-generated pages
 @chapter About pages
 
 Like other browsers, elpher makes certain internally-generated pages


@@ -719,7 +793,33 @@ 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.
 
 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
+To see the address of a special page, simply visit the page and
+press @key{I}.
+
+@node ANSI support, Customization, About pages, Top
+@chapter ANSI support
+
+Depending on which parts of the gopher/gemini universe you frequent,
+you may occasionally stumble on sites which use ANSI escape codes to
+either produce specific characters or to colour text.
+
+By default, elpher uses Emacs' built-in ANSI rendering library,
+@samp{ansi-color}, to process ANSI codes.  This robustly interprets
+the escape codes but only supports 8 colours.  Any colours unsupported
+by the library are simply stripped, leaving uncoloured text in the
+majority of cases.
+
+To drastically improve the number of colours produced, install the
+@samp{xterm-color} package from MELPA.  This package will be automatically
+used by elpher if it is available, and supports 256 colours.
+This should be sufficient to properly render many ANSI colour
+gopher holes and gemini capsules quite nicely.
+
+In case you prefer to completely strip out the ANSI escape codes entirely
+by customizing the @code{elpher-filter-ansi-from-text} variable.
+
+
+@node Customization, Command Index, ANSI support, Top

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


@@ -739,13 +839,13 @@ 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}
+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
 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
+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.
 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.


@@ -757,11 +857,81 @@ See the customization group itself for details.
 
 @printindex fn
 
 
 @printindex fn
 

-@node News, Acknowledgements, Command Index, Top
+@node News, Contributors, Command Index, Top

 @chapter News
 
 This chapter documents the major changes introduced by Elpher releases.
 
 @chapter News
 
 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
+features.
+
+@subsection Local gophermaps
+
+Local gophermaps can now be displayed using @samp{file:}. To render
+correctly, they must have the suffix @samp{.gopher} or @samp{.gophermap}.
+
+@subsection IRI support
+
+Internationalized Resource Identifiers (IRI) are an extension of URLs
+(or, more accurately, URIs) to support a larger set of characters beyond
+those in the US-ASCII character set.  They map directly onto URIs for
+backwards compatibility, but look like gibberish if not properly
+decoded.  When displaying URLs, Elpher now automatically decodes any IRI
+characters and displays the decoded IRI.  (For security reasons, the
+@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
 @section v3.2.0
 
 This version introduces several minor changes which, together, make it


@@ -771,7 +941,7 @@ possible to set up alternative start pages configured to your liking.
 
 Special elpher pages such as the welcome page (previously ``start''
 page), the bookmarks page, the browsing history stack and list of
 
 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,
+visited pages are now addressable via @samp{about:} URLs.  For instance,

 the standard welcome page has the address @samp{about:welcome}.
 
 @subsection Local files
 the standard welcome page has the address @samp{about:welcome}.
 
 @subsection Local files


@@ -783,11 +953,12 @@ for details.
 
 @subsection Customizable start pages
 
 
 @subsection Customizable start pages
 

-The new customization variable @code{elpher-start-page} contains the URL
+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.
 
 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.
 

+@node v3.1.0, v3.0.0, v3.2.0, News

 @section v3.1.0
 
 @subsection Bookmarks system
 @section v3.1.0
 
 @subsection Bookmarks system


@@ -810,6 +981,7 @@ 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.
 
 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
 @section v3.0.0
 
 @subsection Bookmarks system


@@ -853,35 +1025,33 @@ mail system.
 Gemini document headers are now navigable via imenu.
 For details, @xref{Imenu, , , emacs, The Emacs Editor}.
 
 Gemini document headers are now navigable via imenu.
 For details, @xref{Imenu, , , emacs, The Emacs Editor}.
 

-@node Acknowledgements,  , News, Top
-@chapter Acknowledgements
+@node Contributors,  , News, Top
+@chapter Contributors

 
 

-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:
+Elpher was originally written and is currently maintained by Tim Vaughan
+@email{plugd@@thelambdalab.xyz}.  Significant improvements and
+maintenance have also been contributed by and with the help of Alex
+Schroeder @email{alex@@gnu.org}.  In addition, the following people have
+all generously provided assistance and/or patches:

 
 @itemize
 
 @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
+@item Jens Östlund @email{jostlund@@gmail.com}
+@item F. Jason Park @email{jp@@neverwas.me}
+@item Christopher Brannon @email{chris@@the-brannons.com}
+@item Omar Polo @email{op@@omarpolo.com}
+@item Noodles! @email{nnoodle@@chiru.no}
+@item Abhiseck Paira @email{abhiseckpaira@@disroot.org}
+@item Zhiwei Chen @email{chenzhiwei03@@kuaishou.com}
+@item condy0919 @email{condy0919@@gmail.com}
+@item Alexis @email{flexibeast@@gmail.com}
+@item Étienne Deparis @email{etienne@@depar.is}
+@item Simon Nicolussi @email{sinic@@sinic.name}
+@item Michel Alexandre Salim @email{michel@@michel-slm.name}
+@item Koushk Roy @email{kroy@@twilio.com}
+@item Vee @email{vee@@vnsf.xyz}
+@item Simon South @email{simon@@simonsouth.net}
+@item Daniel Semyonov @email{daniel@@dsemy.com}
+@item Bradley Thornton @email{bradley@@northtech.us}

 @end itemize
 
 @end itemize
 

-

 @bye
 @bye