1 .\" Copyright (c) 2021 Omar Polo <op@omarpolo.com>
3 .\" Permission to use, copy, modify, and distribute this software for any
4 .\" purpose with or without fee is hereby granted, provided that the above
5 .\" copyright notice and this permission notice appear in all copies.
7 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
8 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
10 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
12 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
13 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
14 .Dd $Mdocdate: March 28 2021$
29 is an interactive browser for the Gemini protocol.
30 It is able to process text/gemini and more in general every text/* file.
32 also features tabs, bookmarks and out-of-band TOFU verification.
34 The arguments are as follows:
35 .Bl -tag -width xxxxxxxxxxxxx
37 Show all available colors and exit.
39 Display version and usage.
42 Only check the configuration file for validity.
44 Specify an alternative configuration file.
46 .Pa $HOME/.telescope/config
48 .It Fl v , Fl -version
53 aims to use the "Trust, but Verify (where appropriate)" approach.
54 The idea is to define three level of verification for a certificate:
57 the server fingerprint does NOT match the stored value
59 the server fingerprint matches the store one
61 the fingerprint matches and has been verified out-of-band
66 level is enough, but where is appropriate users should be able to
67 verify out-of-band the certificate.
69 At the moment, there is no built-in support for an out-of-band
72 Known certificates are store in
73 .Pa ~/.telescope/known_hosts
74 with a format similar to the
78 Each line is a record and it's made up by three fields, separated by a
79 single space, according to the following format:
84 the hostname, optionally followed by a colon (":") and a port number.
86 is the hash of the certificate, as outputted by
87 .Xr tls_peer_cert_hash 3 .
90 0 means trusted, 1 verified.
92 .Sh DEFAULT KEY BINDINGS
93 The default key bindings are very similar to GNU Emacs, but care has
94 been taken to include also bindings familiar for
99 In the following examples, C-x means Control-x, M-x means Meta-x,
100 where the Meta key may be either a special key on the keyboard or the
101 ALT key; otherwise ESC followed by the key X works as well, and C-M-x
102 means to press the key X together with both Control and Meta.
104 Keys are usually a single character, like
108 but some special keys are accepted as well.
110 .Bl -tag -width 16m -offset indent -compact
120 Previous page/Page up
140 Depends on the configuration of the terminal emulator.
141 Usually is shift tab though.
143 .Ss GNU Emacs-like keys
144 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
158 move-beginning-of-line
174 execute-extended-command
214 .Ss Xr vi 1 Ns -like keys
215 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
229 move-beginning-of-line
261 execute-extended-command
264 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
294 .Ss Neither Emacs nor vi specific
295 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
315 .Ss Minibuffer-specific keys
316 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
318 mini-complete-and-exit
326 mini-delete-backward-char
328 mini-delete-backward-char
330 mini-delete-backward-char
342 move-beginning-of-line
346 move-beginning-of-line
350 mini-previous-history-element
352 mini-next-history-element
362 insert-current-candidate
364 .Sh INTERACTIVE COMMANDS
365 Follows the documentation for the interactive commands.
366 These commands can be bound to a key or executed with
367 .Ic execute-extended-command .
368 .Ss Movement commands
369 .Bl -tag -width execute-extended-command -compact
371 Move point one character backward.
372 .It Ic backward-paragraph
373 Move point one paragraph backward.
374 .It Ic beginning-of-buffer
375 Move point to the beginning of the buffer.
377 Move point to the end of the buffer.
379 Move point one character forward.
380 .It Ic forward-paragraph
381 Move point one paragraph forward.
382 .It Ic insert-current-candidate
383 Copy the current selection text as minibuffer input.
384 .It Ic move-beginning-of-line
385 Move point at the beginning of the current (visual) line.
386 .It Ic move-end-of-line
387 Move point at the end of the current (visual) line.
389 Move point to the next link.
390 .It Ic next-completion
391 Select the next completion.
393 Move point to the next heading.
395 Move point to the next (visual) line, in the same column if possible.
396 .It Ic previous-button
397 Move point to the previous link.
398 .It Ic previous-completion
399 Select the previous completion.
400 .It Ic previous-heading
401 Move point to the previous heading.
403 Move point to the previous (visual) line.
405 .Ss Bookmark-related commands
406 .Bl -tag -width execute-extended-command -compact
408 Add a link to the bookmark file.
409 It preloads the minibuffer with the current URL.
410 .It Ic list-bookmarks
411 Load the bookmarks page.
413 .Ss Tab-related commands
414 .Bl -tag -width execute-extended-command -compact
416 Close the current tab.
417 .It Ic tab-close-other
418 Close all tabs but the current one.
420 Move the current tab after the next one, wrapping around if
423 Move the current tab before the previous one, wrapping around if needed.
427 Focus next tab, wrapping around eventually.
429 Focus the previous tab, wrapping around eventually.
431 Switch to a tab using the minibuffer.
434 .Bl -tag -width execute-extended-command -compact
436 Clears the echo area.
437 .It Ic dec-fill-column
438 Decrements fill-column by two.
439 .It Ic execute-extended-command
440 Prompts for a command name using the minibuffer.
441 .It Ic kill-telescope
444 .It Ic inc-fill-column
445 Increments fill-column by two.
447 Select and visit a link using the minibuffer.
448 .It Ic load-current-url
449 Prompts for an URL, the minibuffer is preloaded with the current
454 Load the next item in the history list.
456 Toggle olivetti mode (i.e. horizontal centering of the lines of the
459 Load the previous item in the history list.
461 Follow the link on the current line, or toggle the visibility of the
462 following preformatted block if called when the cursor is on the
463 heading of the block.
464 .It Ic push-button-new-tab
465 Follow the link on the current line on a new tab.
467 Redraw the screen, useful if some background program messed up the
470 Reload the current page.
472 Scroll down by one visual page.
473 .It Ic scroll-line-down
474 Scroll down by one line.
475 .It Ic scroll-line-up
476 Scroll up by one line.
478 Scroll up by one visual page.
480 Jump to a line using the minibuffer.
482 Select and jump to a heading of the page using the minibuffer.
484 Toggle side window with help about available keys and their associated
487 .Ss Minibuffer commands
488 .Bl -tag -width execute-extended-command -compact
490 Abort the current minibuffer action.
491 .It Ic mini-complete-and-exit
492 Complete the current minibuffer action.
493 .It Ic mini-delete-backward-char
494 Delete the character before the point.
495 .It Ic mini-delete-char
496 Delete the character after the point.
497 .It Ic mini-kill-line
498 Delete from the point until the end of the line.
499 .It Ic mini-next-history-element
500 Load the previous history element.
501 .It Ic mini-previous-history-element
502 Load the next history element.
505 The following aliases are available during
506 .Ic execute-extended-command :
507 .Bl -tag -width 16m -compact
514 .It Ic q No and Ic wq
517 .Sh CONFIGURATION FILE
520 reads the configuration file at
521 .Pa ~/.telescope/config
522 or the one given with the
526 The format of the configuration file is fairly flexible.
527 The current line can be extended over multiple ones using a
530 Comments can be put anywhere in the file using a hash mark
532 and extend to the end of the current line, but backslashes can't be
533 used to extend comments over multiple lines.
535 The following constructs are available:
537 .It Ic bind Ar map Ar key Ar cmd
544 Valid values for map are
546 .Pq i.e. when the user is viewing a page
549 .Pq i.e. when the minibuffer has the focus.
551 follows the same syntax described in
552 .Sx DEFAULT KEY BINDINGS
553 and all the possible functions are listed in
554 .Sx INTERACTIVE COMMANDS .
555 .It Ic proxy Ar proto Ic via Ar url
558 as proxy for all URLs with
562 must be a Gemini URI without path, query and fragment component.
563 .It Ic set Ar opt No = Ar val
570 .Bl -tag -width twelveletters -compact
573 If not zero, enable colours.
576 is not set, 0 otherwise.
579 If greater than zero, lines of text will be formatted in a way that
580 don't exceed the given number of columns.
584 If nonzero, hide by default the body of the preformatted blocks.
587 can be used to toggle the visibility per-block.
588 .It hide-pre-closing-line
590 If nonzero, hide the closing line of preformatted blocks.
593 If nonzero, hide the start and end line of the preformatted blocks.
594 If both hide-pre-context and hide-pre-blocks are nonzero, preformatted
595 blocks are irremediably hidden.
599 URL for the new tab page.
609 .It Ic style Ar name Ar option
610 Change the styling of the element identified by
612 Multiple options may be specified within curly braces.
613 Valid style identifiers are:
614 .Bl -tag -width 16m -compact -offset Ds
616 for the area outside the lines in the body of the page.
618 for the completion in the minibuffer
619 .It line.compl.current
620 for the current completion
632 for the heading of a preformatted block.
634 for the content of a preformatted block.
636 for the closing line of a preformatted block.
639 .Dq i.e. the last line of the window
642 .Dq i.e. the info line right above the minibuffer
646 for the non-focused tabs.
653 .It Ic attr Ar prefix Oo Ar line Oo Ar trail Oc Oc
654 Sets the text attributes.
655 If only one value is given,
659 default to that; if two values are given then
663 Each attribute is a comma-separated list of keywords:
664 .Bl -tag -width underline -compact -offset Ds
668 best highlighting mode for the terminal.
672 reverses background/foreground colors.
674 makes the text blinking.
678 extra bright or bold.
681 Only the styles under the
683 prefix accept up to three attributes.
684 The other will only use the first one given.
685 .It Ic bg Ar prefix Oo Ar line Oo Ar trail Oc Oc
686 Sets the background color.
687 Follows the same behaviour as
689 regarding the optional parameters.
690 The colour is one of black, red, green, yellow, blue,
691 magenta, cyan and white; colour0 to colour255
692 .Pq or color0 to color255
693 from the 256-colour set;
694 default for the default colour.
695 .It Ic fg Ar prefix Oo Ar line Oo Ar trail Oc Oc
696 Sets the foreground color.
699 .It Ic prefix Ar prfx Op Ar cont
700 Sets the prefix for the current line type to
704 as the prefix for the continuation lines
705 .Pq i.e. when a long line gets wrapped.
708 is not given its value will be the same of
713 .Bl -tag -width Ds -compact
714 .It Pa ~/.telescope/bookmarks.gmi
716 .It Pa ~/.telescope/config
717 Default configuration file.
718 .It Pa ~/.telescope/known_hosts
719 Contains a list of host keys for all the hosts the user has visited.
720 See the TOFU section for more info.
721 .It Pa ~/.telescope/lock
722 Lock file used to prevent multiple instance of
724 from running at the same time.
725 .It Pa ~/.telescope/session
726 Contains the list of opened tabs in the last session, one per line.
729 and loaded on startup.
732 The following is my config file:
733 .Bd -literal -offset indent
734 # enable colors regardless of $NO_COLOR
735 set enable-colors = 1
750 It's possible to browse
752 .Pq i.e. simple websites
753 by using programs like the duckling-proxy by defining a proxy in
754 .Pa ~/.telescope/config :
755 .Bd -literal -offset indent
756 proxy http via "gemini://localhost:1965"
757 proxy https via "gemini://localhost:1965"
762 without any configuration use
763 .Bd -literal -offset indent
764 telescope -c /dev/null
770 program was written by
771 .An Omar Polo Aq Mt op@omarpolo.com .
