Merge remote-tracking branch 'upstream/patch_disable-gnutls-verify' into main
[elpher.git] / elpher.texi
1 \input texinfo @c -*-texinfo-*-
2
3 @setfilename elpher.info
4 @settitle Elpher Manual v2.10.0
5
6 @dircategory Emacs
7 @direntry
8 * Elpher: (elpher).     A gopher and gemini client for Emacs.
9 @end direntry
10
11 @copying
12 This manual documents Elpher, a gopher and gemini client for Emacs.
13
14 Copyright @copyright{} 2019, 2020 Tim Vaughan
15
16 @quotation
17 The source and documentation of Elpher is free software.  You can
18 redistribute it and/or modify it under the terms of the GNU General
19 Public License as published by the Free Software Foundation; either
20 version 3, or (at your option) any later version.
21
22 Elpher is distributed in the hope that it will be useful, but WITHOUT
23 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
24 FITNElpher FOR A PARTICULAR PURPOSE. See the GNU General Public License in
25 the file COPYING in the same directory as this file for more details.
26 @end quotation
27 @end copying
28
29 @titlepage
30 @title Elpher Gopher and Gemini Client Manual
31 @author Tim Vaughan
32
33 @page
34 @vskip 0pt plus 1filll
35 @insertcopying
36 @end titlepage
37
38 @contents
39
40 @ifnottex
41 @node Top, Introduction, (dir), (dir)
42 @top Elpher
43
44 @insertcopying
45 @end ifnottex
46
47 @macro keycmd{key,cmd}
48 @item \key\  (@code{\cmd\})
49 @findex \cmd\
50 @end macro
51
52 @menu
53 * Introduction::                Elpher Overview: what's this all about?
54 * Installation::                Installing Elpher
55 * Quick Start::                 Get up and running quickly
56 * Navigation::                  Fundamentals of Elpher navigation
57 * Bookmarks::                   How to record and visit bookmarks
58 * Gopher character encodings::  How Elpher selects encodings for gopher pages
59 * Encrypted gopher connections::       How and when TLS is enabled for gopher
60 * Gemini support::              Support for the Gemini protocol
61 * Finger support::              Support for the Finger protocol
62 * Customization::               How to customize various aspects of Elpher
63 * Command Index::
64
65 @detailmenu
66  --- The Detailed Node Listing ---
67
68 Navigation
69
70 * Within-page navigation::      Moving about within a page
71 * Between-page navigation::     Commands for moving between pages
72 * History and Caching::         Explanation of how Elpher represents history
73
74 @end detailmenu
75 @end menu
76
77 @node Introduction, Installation, Top, Top
78 @chapter Introduction
79
80 Elpher aims to be a capable and practical gopher and gemini client for
81 Emacs.  Its focus is on easy keyboard-driven navigation based on
82 sensible default bindings (with out-of-the-box support for Evil).  It is
83 intended to be robust and behave in non-surprising ways at all times.
84 Additionally, Elpher provides the following bells and whistles:
85
86 @itemize
87 @item
88 followable web and gopher links in plain text,
89
90 @item
91 an easily navigable history, sporting caching of visited pages (both
92 content and cursor position),
93
94 @item
95 auto-completing menu item navigation,
96
97 @item
98 direct visualization of image files where supported (no writing to
99 disk),
100
101 @item
102 a bookmark management system,
103
104 @item
105 basic support for the new ``heavier than gopher, lighter than the web'' Gemini protocol,
106
107 @item
108 support for the Finger protocol.
109
110 @end itemize
111
112 Elpher is still under active development.  Although we try very hard to
113 ensure that releases are bug-free, this cannot be guaranteed.  However,
114 this also means that any usability features that you feel are missing
115 can likely by incorporated quickly, so please get in touch if you
116 have some ideas.
117
118 @node Installation, Quick Start, Introduction, Top
119 @chapter Installation
120
121 Elpher is available from the MELPA package repository.  If you have
122 never installed packages from this repository before, you'll need
123 to follow the instructions at @url{https://melpa.org/#/getting-started}.
124
125 @noindent To install Elpher, enter the following:
126
127 @example
128 @kbd{M-x package-install @key{RET} elpher @key{RET}}
129 @end example
130
131 @noindent To uninstall, use
132
133 @example
134 @kbd{M-x package-delete @key{RET} elpher @key{RET}}.
135 @end example
136
137 While not recommended, it is also possible to install Elpher directly by
138 downloading the file @file{elpher.el} from
139 @url{gopher://thelambdalab.xyz/1/projects/elpher/}, adding it to a directory in
140 your @code{load-path}, and then adding
141
142 @example
143 (require 'elpher)
144 @end example
145
146 @noindent to your Emacs initialization file.
147
148 @node Quick Start, Navigation, Installation, Top
149 @chapter Quick Start
150
151 Before diving into the minutiae of the different commands available,
152 we will quickly describe how to get up and running with Elpher.
153
154 Once installed, you can launch Elpher using
155
156 @example
157 @kbd{M-x elpher @key{RET}}
158 @end example
159
160 @noindent This will switch to the *Elpher* buffer and display a start
161 page, with information on each of the default keyboard bindings.
162
163 From here you can move point between links (which may be menu items or
164 inline URLs in text files) by using @key{TAB} and @kbd{S-@key{TAB}},
165 as in Info.  You can also jump directly to a menu item using @key{m}, or
166 use the standard Emacs or Evil motion and search commands to find your
167 way around.  To open a link, press @key{RET}.  (Where a mouse is
168 available, Clicking on a link with the mouse cursor has the same
169 effect.)
170
171 To return to the page you just followed the link from, press @key{u}.
172
173 Elpher caches (for the duration of an Emacs session) both page contents
174 and the position of point on each of the pages (gopher menus, gemini
175 pages, query results, or text pages) you visit, restoring these when you
176 next visit the same page.  Thus, pressing @key{u} displays the previous
177 page in exactly the same state as when you left, meaning that you can
178 quickly and visually explore the different documents in a menu without
179 having to wait for anything to reload.
180
181 Of course, sometimes you'll @emph{want} to reload the current page
182 rather than stick with the cached version.  To do this use @key{R}.
183 (This is particularly useful for search query results, where this
184 allows you to perform a different search.)
185
186 That's more-or-less it. Elpher supports a number of other features, such
187 as bookmarking, support for different coding schemes and TLS encryption,
188 and a variety of customization options, all of which are explained in
189 the rest of this document.  However the emphasis is on keeping the basic
190 navigation experience as intuitive and responsive as possible.
191
192 @node Navigation, Bookmarks, Quick Start, Top
193 @chapter Navigation
194 Throughout this manual, we use the word ``page'' to refer to any
195 visualization of a response from a gopher or gemini server, be it a
196 menu/directory, query result, text file or image.  We use
197
198 Elpher's navigation interface is inspired by the Emacs Info mode.
199 Movement within a page is essentially the same as moving
200 around any other text file in Emacs, but with special keys
201 for quickly jumping between menu items and URLs in text files.
202 Movement between pages is facilitated by a simple linear history
203 coupled with caching of pages and cursor position.
204
205 @menu
206 * Within-page navigation::      Moving about within a page
207 * Between-page navigation::     Commands for moving between pages
208 * History and Caching::         Explanation of how Elpher represents history
209 @end menu
210
211
212 @node Within-page navigation, Between-page navigation, Navigation, Navigation
213 @section Within-page navigation
214
215 To move about within a page, you should be able use the same keys you usually
216 use to browse files in Emacs.  This is even true when Evil mode is
217 enabled. Paragraph hopping, searching etc should work as usual.
218
219 In addition, the following commands are provided for quickly moving between
220 links and menu items.
221
222 @table @asis
223 @keycmd{@key{TAB}, elpher-next-link}
224 Move to the next link or menu item in the file.
225
226 @keycmd{@kbd{Shift-@key{TAB}}/@key{backtab}, @code{elpher-prev-link}}
227 Move to the previous link or menu item in the file.
228
229 @keycmd{@key{m}, elpher-jump}
230 Jump directly to a link within a file by specifying its display string
231 or link text.  (Unlike the previous two commands, this immediately opens
232 the selected link.
233 @end table
234
235 The following commands can be used to retrieve information about the
236 current page, or the address of the link at point:
237
238 @table @asis
239 @keycmd{@key{i}, elpher-info-link}
240 Display host, port and selector information for the link at point.
241
242 @keycmd{@key{I}, elpher-info-current}
243 Display host, port and selector information for the current page.
244
245 @keycmd{@key{c}, elpher-copy-link-url}
246 Add URL representing address of link at point to the kill-ring and the
247 system clipboard (if available).
248
249 @keycmd{@key{C}, elpher-copy-current-url}
250 Add URL representing address of the current page to the kill-ring and
251 the system clipboard (if available).
252
253 @keycmd{@key{d}, elpher-download}
254 Download link at point and save the result as a file.  The minibuffer
255 will prompt for the name of the file to write, with the default name being
256 the display string (if available) associated with the link.
257
258 @keycmd{@key{D}, elpher-download-current}
259 This is similar to @code{elpher-download}, but instead applies to the
260 current page rather than a link.
261
262 @keycmd{@key{.}, elpher-view-raw}
263 This displays the raw server response for the current page.  While not
264 useful for general browsing, it is useful for debugging incorrect rendering
265 or out-of-spec server responses.
266 @end table
267
268 @node Between-page navigation, History and Caching, Within-page navigation, Navigation
269 @section Between-page navigation
270
271 Moving to a different page can be accomplished in several ways,
272 described by the following command:
273
274 @table @asis
275 @keycmd{@key{RET}\, @kbd{mouse-1}, elpher-follow-link}
276 Follow the menu item or link at point (or selected with the mouse).
277
278 Exactly what is meant by ``follow'' depends on the kind of item selected:
279
280 @itemize
281 @item
282 For text or menu type items or links, the current page text is replaced
283 by the text of this item.  Unless the customization variable
284 @code{elpher-use-header} (@pxref{Customization}) is 
285 @code{nil}, the display string of the link is displayed in the buffer header.
286 Links to images behave similarly on Emacs systems supporting the display of
287 bitmap graphics, however their content is not cached in memory by default.
288
289 @item
290 When followed, links to search/query items (type 7) prompt for input in
291 the minibuffer then display the results in the same way as for text and menu
292 items.
293
294 @item
295 Following links to binary files (and image files on unsupported systems)
296 causes Elpher to prompt for a filename in which to save the content.
297
298 @item
299 Following links of type `h' with a selector having the `URL:' prefix, or
300 unsuported URLs in text files, will result in Elpher using an external
301 programme to open the URL.  This will be either the default system browser
302 or, if the @code{elpher-open-urls-with-eww} customization variable is non-nil,
303 Emacs' own EWW browser. (See @pxref{Customization}.) 
304
305 @end itemize
306
307 Once a text, menu or query response page has been displayed, its contents are
308 cached for the duration of the Emacs session. 
309
310 @keycmd{@key{g}, elpher-go}
311 Open a particular page by specifying either its full URL or just entering
312 a gopher host name. (The protocol defaults to gopher, so gemini links must include the @code{gemini://} prefix.
313
314 If a unsupported protocol is used in the URL the result will be the same
315 as following a URL link of the same type from a link in a page.
316
317 @keycmd{@key{o}, elpher-go-current}
318 Prompts for a URL similar to @code{elpher-go}, but initialized to the URL
319 of the current page.  This allows you to easily try other selectors for the
320 same server.
321
322 Remember however, that the Gopher RFC 1436 provides @emph{no} guarantees about the
323 structure of selectors.
324
325 @keycmd{@key{O}, elpher-root-dir}
326 Open the root page (empty selector) on the current host.
327
328 @keycmd{@key{u}\, @kbd{mouse-3}, elpher-back}
329 Return to the previous page, where ``previous'' means the page where the
330 page which was displayed immediately before the current page.
331 @end table
332
333
334 @node History and Caching,  , Between-page navigation, Navigation
335 @section History and Caching 
336
337 The history and caching strategy in Elpher is extremely simple, but
338 may be confusing without a good mental model of how it works.  That
339 is what this section attempts to provide.
340
341 Essentially, @strong{every} time you navigate to a new page, either
342 by clicking or pressing @key{RET} on a link, using @key{g} to jump
343 to a new page by its address, or using @key{O} to open the root selector,
344 the following two things occur:
345
346 @enumerate
347 @item
348 the cursor position and content for the original page are recorded in an
349 in-memory cache, and
350
351 @item
352 the original page is set as the ``parent'' of the new page.
353 @end enumerate
354
355 The only way to return to pages in this history is by using @key{u},
356 which returns to the previous of the current page.  @footnote{The
357 addition of the new page to the history happens even if the new page is
358 one that has been seen before. This is mostly the desired behaviour.
359 However, opening an explicit ``back'' link provided by a gopher menu or
360 gemini page will also add a new entry to the history.  Unless you
361 haven't yet visited that menu, it's therefore better to use @key{u} to
362 go back in this case.}
363
364 One aspect that may seem peculiar is that Elpher lacks a corresponding ``next'' or
365 ``forward'' command.  However, since Elpher caches the position of point,
366 this will be automatically positioned on the link that was most recently followed
367 from a given page.  This means that, at least for links followed from menus
368 and text files, the inverse of @key{u} is actually just @key{RET}.
369
370
371 @node Bookmarks, Gopher character encodings, Navigation, Top
372 @chapter Bookmarks
373
374 Elpher has a very simple link bookmarking system involving the
375 following commands:
376
377 @table @asis
378 @keycmd{@key{a}, elpher-bookmark-link}
379 Add a bookmark for the link at point.  The minibuffer will prompt for
380 a name for the bookmark, which defaults to the display string.
381
382 @keycmd{@key{A}, elpher-bookmark-current}
383 Add a bookmark for the current page.  The minibuffer will prompt for
384 a name for the bookmark, defaulting to the display string associated
385 with the link that was followed to reach the current page.
386
387 @keycmd{@key{x}, elpher-unbookmark-link}
388 Immediately remove the bookmark (if one exists) to the link at point.
389
390 @keycmd{@key{X}, elpher-unbookmark-current}
391 Immediately remove the bookmark (if one exists) to the current page.
392
393 @keycmd{@key{B}, elpher-bookmarks}
394 Open a page displaying all current bookmarks.  Note that this bookmark
395 page is added to the history just as if you had opened it using a link.
396 Thus to return to the previous page, use @kbd{u}.  This also means
397 that you can peruse the various bookmarks by visiting them in turn, 
398 using @kbd{u} to return to the bookmark page (where the position of point
399 is cached), then moving to another bookmarked link and so on.
400 @end table
401
402 Bookmarks are stored as a s-exp in the file @file{elpher-bookmarks}
403 in the user emacs directory (usually @file{~/.emacs.d/}).
404 Any command which modifies the list of bookmarks immediately updates
405 this file.
406
407 @node Gopher character encodings, Encrypted gopher connections, Bookmarks, Top
408 @chapter Gopher character encodings
409
410 Responses Elpher retrieves from servers are initially read as pure
411 binary data.  When the data is intended to be interpreted as textual (as
412 determined by the type parameter of the gopher menu item or the gopher
413 URL), this data needs to be @emph{decoded} into a sequence of
414 characters.  To do this properly requires knowledge of the encoding
415 system used by whoever authored the document.
416
417 Unfortunately gopher lacks a systematic way of acquiring this necessary
418 information. Thus, the details of the coding system must be either inferred from the binary data,
419 or must be specified by the user.
420
421 By default, Elpher applies Emacs' built-in character encoding detection
422 system to the full (undecoded) response data and uses this to attempt to
423 convert it into a character string.
424 (See @pxref{Recognize coding, Recognizing coding systems, ,emacs}.) While
425 this approach can be okay, it is important to realize that its inference
426 algorithm is extremely primitive and depends heavily on assumptions based
427 on the language settings of your emacs system.
428
429 The alternative is to explicitly set the coding system used for decoding
430 using the following command:
431
432 @table @asis
433 @keycmd{@key{S},elpher-set-coding-system}
434 Causes a elpher to prompt for a coding system to use for decoding
435 future gopher text.  The @key{TAB} key can be used at this prompt to display a
436 list of alternatives (which is extensive) and to auto-complete.  An empty
437 response will cause Elpher to return to its default auto-detection
438 behaviour.
439 @end table
440
441 Note that changing the coding system only affects newly loaded text.
442 Thus, if text has already been decoded using an incorrect system, you
443 will need to select the correct coding and then reload the text using
444 @key{R}.
445
446
447 @node Encrypted gopher connections, Gemini support, Gopher character encodings, Top
448 @chapter Encrypted gopher connections
449
450 While RFC 1436 does not broach the topic of encryption at all, several
451 modern gopher servers can serve content over encrypted connections,
452 and a common choice for this is TLS.
453
454 Elpher can retrieve selectors using Emacs' built-in TLS support which
455 uses the GnuTLS library. (It is possible to build emacs without
456 GnuTLS, in which case encryption is not supported.)
457
458 To retrieve documents using TLS, Elpher's TLS mode must be enabled.
459 This can be directly toggled using @key{T}, but note that just as with
460 the character encoding, changing this mode only affects subsequent
461 connections.
462
463 Alternatively, TLS mode is @emph{automatically} enabled whenever
464 gopher URLs starting with @code{gophers://} are followed.
465
466 The mode is sticky, so it remains active until switched off.
467 It can also be automatically switched off when a TLS connection fails.
468 In this case Elpher will prompt for your confirmation to ensure that
469 you can't accidentally make a non-TLS connection.
470
471 @node Gemini support, Finger support, Encrypted gopher connections, Top
472 @chapter Gemini support
473
474 @uref{gopher://gemini.circumlunar.space, Gemini}
475 is a new protocol being developed by several members of
476 gopherspace.  It aims to solve some of the long-standing technical
477 issues associated with gopher as a protocol, while keeping the major benefits.
478 For instance, it _requires_ encrypted connections, it does away with
479 the selector type, and allows servers to explicitly specify the
480 character coding scheme used for text documents.
481
482 The latest versions of Elpher aim to provide seamless transitions between
483 gemini and gopher documents.  Basically you should be able to open,
484 bookmark, download and otherwise interact with gemini pages in exactly
485 the same way as you do with other non-gemini pages.  The only major
486 difference from your perspective as a user is that you should no longer
487 have to worry about manually toggling TLS on or off (for gemini it's
488 always on), and you should never have to manually set a character coding
489 scheme.
490
491 The gemini protocol specification recommends a Trust on First Use (TOFU)
492 behaviour when validating gemini server TLS certificates.  This is
493 because many gemini servers rely on self-signed certificates rather
494 than certificates signed by a CA. Sadly however, this TOFU behaviour is
495 far from straight-forward to configure using Emacs' existing Network
496 Security Manager.  For this reason, elpher defaults to performing no
497 certificate verification by default.  This behaviour can be easily
498 customized by setting the @code{elpher-gemini-TLS-cert-checks}
499 customization variable to non-nil.
500
501 The gemini specification concerns both the protocol and a simple text
502 document format (mimetype text/gemini) which is like a mixture between
503 gophermap files and markdown-formatted files but simpler than both.
504 Elpher renders gemini responses which are provided in this format in
505 line with the rules in the spec.  This includes wrapping long lines at
506 word boundaries.  The specific column at which this text is wrapped is
507 defined by the customization variable
508 @code{elpher-gemini-max-fill-width}, which is set to 80 columns by
509 default. (This is slightly wider than Emacs' default fill width of 70
510 columns due to the fact that there are a significant amount of older
511 gemini content which, against the advice of the current spec, hard wraps
512 at <80 columns.  The larger default allows this to still look okay,
513 while still keeping content without hard wraps looking pleasant.)
514
515 The text/gemini format also possesses a section header syntax similar to
516 markdown.  Elpher allows different header levels to be drawn with
517 different, customizable, faces.  By default, on graphically-capable
518 emacs systems, these faces are given different heights to distinguish
519 among levels.  On terminal systems, the level is indicated by the
520 number of preceding # symbols.
521
522 I should emphasize however that, while it is definitely functional,
523 Elpher's gemini support is still experimental, and various aspects will
524 change as the protocol develops further.
525
526 @section Client Certificates for Gemini
527
528 Gemini makes explicit use of the client certificate mechanism that TLS
529 provides for allowing clients to authenticate themselves with servers.
530 The Gemini specification suggests two distinct classes of client
531 certificates: short-lived certificates used to identify you for a single
532 session, and more permanent certificates used to identify you over a
533 longer time period.
534
535 When Elpher receives a request for a client certificate from a server,
536 it will present you with the option to create and use a single-use
537 ``throwaway'' certificate, or to use a ``persistent''
538 certificate (optionally creating it or installing pre-existing key and
539 certificate files).
540
541 Certificate creation in Elpher requires an installation of OpenSSL, and
542 ---in particular---that Elpher be able to run the @command{openssl} command-line
543 utility.  By default, Elpher assumes that the @command{openssl} is on the
544 system path, but the precise location can be set by customizing the
545 @code{elpher-openssl-command} variable.
546
547 Each generated certificate results in the creation of a .key file and
548 a .crt file.  In the case of a throwaway certificate, these files are
549 stored in the temporary directory indicated by the Emacs variable
550 @code{temporary-file-directory} and are deleted when ``forgotten''
551 (as described below).
552
553 In the case of persistent certificates, these files are stored in the
554 folder defined by the Elpher variable
555 @code{elpher-certificate-directory}, and are never deleted by Elpher.
556 (Of course you can delete them yourself whenever you like.)
557 The base name of the files (i.e. sans extension) is what Elpher uses
558 to identify the certificate.
559
560 Using throwaway certificates is as simple as pressing the @key{t} 
561 key at the prompt which appears following a certificate request from
562 a server.  There is nothing more to do.
563
564 Using a persistent certificate requires instead selecting @key{p} from the same
565 menu.  This will result in Elpher asking you for the name identifying
566 the certificate.  This entry autocompletes to the list of known certificate
567 names, so you can use @key{TAB} to display the list.
568
569 In the case that you choose a name that does not belong to the list of
570 known certificates, Elpher will offer to create one for you or to
571 ``install'' one from existing key and certificate files.
572 Pressing the @key{n} key will cause Elpher to begin the process of
573 creating a new persistent certificate, using some additional
574 details for which you will be prompted.
575 Alternatively, pressing the @key{i} key will cause Elpher to ask for the
576 locations of edisting key and certificate files to add to
577 @code{elpher-certificate-directory} under the chosen name.
578
579 Once a certificate is selected, it will be used for all subsequent TLS
580 transactions to the host for which the certificate was created.
581 It is immediately ``forgotten'' when a TLS connection to another host
582 is attempted, or the following command is issued:
583
584 @table @asis
585 @keycmd{@key{F},elpher-forget-certificate}
586 Causes Elpher to immediately forget any currently-loaded client certificate.
587 @end table
588
589 In either case, ``forgetting'' means that the details of the key and
590 certificate file pair are erased from memory.  Furthermore, in the case
591 of throw-away certificates, the corresponding files are deleted.
592
593
594 @node Finger support, Customization, Gemini support, Top
595 @chapter Finger support
596
597 Incidentally, Elpher has native support for querying finger servers.
598 Of course, one could argue that this functionality is more easily
599 provided by one's local telnet client.  However finger URLs do appear
600 on occasion in gopherspace, and it's nice to be able to open them
601 in place.
602
603 Elpher interprets @code{finger://} URLs as follows:
604
605 @itemize
606
607 @item
608 The host is determined by the host name portion of the URL.
609
610 @item
611 In the case that the @emph{file name} portion of the URL is non-empty (besides
612 the leading slash), this is interpreted as the user to finger.
613
614 @item
615 Otherwise, the @emph{user} portion of the URL is interpreted as the user to finger.
616
617 @item
618 If no user is provided, the root directory of the finger server is requested.
619
620 @end itemize
621
622 Thus @code{finger://user@@hostname} and @code{finger://hostname/user} are both equivalent.
623
624 (The precedence of the /user notation over the user@ notation reflects a
625 preference of the community.)
626
627 @node Customization, Command Index, Finger support, Top
628 @chapter Customization
629
630 Various parts of Elpher can be customized via the 
631 variables belonging to the elpher customization group, accessible
632 using
633
634 @example
635 @kbd{M-x customize-group elpher @key{RET}}
636 @end example
637
638 @noindent This group contains a number of faces that can be modified to change
639 the appearance of Elpher, including one face per menu item type.
640
641 The group also contains variables for customizing the behaviour of
642 Elpher.  This includes how to open arbitrary (non-gopher) URLs, whether
643 to display buffer headers, how to deal with ANSI escape sequences in
644 text, the timeout to impose on network connections, and whether to
645 prompt for confirmation when switching away from TLS.
646
647 See the customization group itself for details.
648
649 @node Command Index,  , Customization, Top
650 @unnumbered Command Index
651
652 @printindex fn
653
654 @bye