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 Display version and usage.
40 Only check the configuration file for validity.
42 Specify an alternative configuration file.
44 .Pa $HOME/.telescope/config
46 .It Fl v , Fl -version
51 aims to use the "Trust, but Verify (where appropriate)" approach.
52 The idea is to define three level of verification for a certificate:
55 the server fingerprint does NOT match the stored value
57 the server fingerprint matches the store one
59 the fingerprint matches and has been verified out-of-band
64 level is enough, but where is appropriate users should be able to
65 verify out-of-band the certificate.
67 At the moment, there is no built-in support for an out-of-band
70 Known certificates are store in
71 .Pa ~/.telescope/known_hosts
72 with a format similar to the
76 Each line is a record and it's made up by three fields, separated by a
77 single space, according to the following format:
82 the hostname, optionally followed by a colon (":") and a port number.
84 is the hash of the certificate, as outputted by
85 .Xr tls_peer_cert_hash 3 .
88 0 means trusted, 1 verified.
90 .Sh DEFAULT KEY BINDINGS
91 The default key bindings are very similar to GNU Emacs, but care has
92 been taken to include also bindings familiar for
97 In the following examples, C-x means Control-x, M-x means Meta-x,
98 where the Meta key may be either a special key on the keyboard or the
99 ALT key; otherwise ESC followed by the key X works as well, and C-M-x
100 means to press the key X together with both Control and Meta.
102 Keys are usually a single character, like
106 but some special keys are accepted as well.
108 .Bl -tag -width 16m -offset indent -compact
118 Previous page/Page up
138 Depends on the configuration of the terminal emulator.
139 Usually is shift tab though.
141 .Ss GNU Emacs-like keys
142 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
156 move-beginning-of-line
172 execute-extended-command
212 .Ss Xr vi 1 Ns -like keys
213 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
227 move-beginning-of-line
259 execute-extended-command
262 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
292 .Ss Neither Emacs nor vi specific
293 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
313 .Ss Minibuffer-specific keys
314 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
316 mini-complete-and-exit
324 mini-delete-backward-char
326 mini-delete-backward-char
328 mini-delete-backward-char
340 move-beginning-of-line
344 move-beginning-of-line
348 mini-previous-history-element
350 mini-next-history-element
360 insert-current-candidate
362 .Sh INTERACTIVE COMMANDS
363 Follows the documentation for the interactive commands.
364 These commands can be bound to a key or executed with
365 .Ic execute-extended-command .
366 .Ss Movement commands
367 .Bl -tag -width execute-extended-command -compact
369 Move point one character backward.
370 .It Ic backward-paragraph
371 Move point one paragraph backward.
372 .It Ic beginning-of-buffer
373 Move point to the beginning of the buffer.
375 Move point to the end of the buffer.
377 Move point one character forward.
378 .It Ic forward-paragraph
379 Move point one paragraph forward.
380 .It Ic insert-current-candidate
381 Copy the current selection text as minibuffer input.
382 .It Ic move-beginning-of-line
383 Move point at the beginning of the current (visual) line.
384 .It Ic move-end-of-line
385 Move point at the end of the current (visual) line.
387 Move point to the next link.
388 .It Ic next-completion
389 Select the next completion.
391 Move point to the next heading.
393 Move point to the next (visual) line, in the same column if possible.
394 .It Ic previous-button
395 Move point to the previous link.
396 .It Ic previous-completion
397 Select the previous completion.
398 .It Ic previous-heading
399 Move point to the previous heading.
401 Move point to the previous (visual) line.
403 .Ss Bookmark-related commands
404 .Bl -tag -width execute-extended-command -compact
406 Add a link to the bookmark file.
407 It preloads the minibuffer with the current URL.
408 .It Ic list-bookmarks
409 Load the bookmarks page.
411 .Ss Tab-related commands
412 .Bl -tag -width execute-extended-command -compact
414 Close the current tab.
415 .It Ic tab-close-other
416 Close all tabs but the current one.
418 Move the current tab after the next one, wrapping around if
421 Move the current tab before the previous one, wrapping around if needed.
425 Focus next tab, wrapping around eventually.
427 Focus the previous tab, wrapping around eventually.
429 Switch to a tab using the minibuffer.
432 .Bl -tag -width execute-extended-command -compact
434 Clears the echo area.
435 .It Ic dec-fill-column
436 Decrements fill-column by two.
437 .It Ic execute-extended-command
438 Prompts for a command name using the minibuffer.
439 .It Ic kill-telescope
442 .It Ic inc-fill-column
443 Increments fill-column by two.
445 Select and visit a link using the minibuffer.
446 .It Ic load-current-url
447 Prompts for an URL, the minibuffer is preloaded with the current
452 Load the next item in the history list.
454 Toggle olivetti mode (i.e. horizontal centering of the lines of the
457 Load the previous item in the history list.
459 Follow the link on the current line, or toggle the visibility of the
460 following preformatted block if called when the cursor is on the
461 heading of the block.
462 .It Ic push-button-new-tab
463 Follow the link on the current line on a new tab.
465 Redraw the screen, useful if some background program messed up the
468 Reload the current page.
470 Scroll down by one visual page.
471 .It Ic scroll-line-down
472 Scroll down by one line.
473 .It Ic scroll-line-up
474 Scroll up by one line.
476 Scroll up by one visual page.
478 Jump to a line using the minibuffer.
480 Select and jump to a heading of the page using the minibuffer.
482 Toggle side window with help about available keys and their associated
485 .Ss Minibuffer commands
486 .Bl -tag -width execute-extended-command -compact
488 Abort the current minibuffer action.
489 .It Ic mini-complete-and-exit
490 Complete the current minibuffer action.
491 .It Ic mini-delete-backward-char
492 Delete the character before the point.
493 .It Ic mini-delete-char
494 Delete the character after the point.
495 .It Ic mini-kill-line
496 Delete from the point until the end of the line.
497 .It Ic mini-next-history-element
498 Load the previous history element.
499 .It Ic mini-previous-history-element
500 Load the next history element.
503 The following aliases are available during
504 .Ic execute-extended-command :
505 .Bl -tag -width 16m -compact
512 .It Ic q No and Ic wq
515 .Sh CONFIGURATION FILE
518 reads the configuration file at
519 .Pa ~/.telescope/config
520 or the one given with the
524 The format of the configuration file is fairly flexible.
525 The current line can be extended over multiple ones using a
528 Comments can be put anywhere in the file using a hash mark
530 and extend to the end of the current line, but backslashes can't be
531 used to extend comments over multiple lines.
533 The following constructs are available:
535 .It Ic bind Ar map Ar key Ar cmd
542 Valid values for map are
544 .Pq i.e. when the user is viewing a page
547 .Pq i.e. when the minibuffer has the focus.
549 follows the same syntax described in
550 .Sx DEFAULT KEY BINDINGS
551 and all the possible functions are listed in
552 .Sx INTERACTIVE COMMANDS .
553 .It Ic proxy Ar proto Ic via Ar url
556 as proxy for all URLs with
560 must be a Gemini URI without path, query and fragment component.
561 .It Ic set Ar opt No = Ar val
568 .Bl -tag -width twelveletters -compact
571 If not zero, enable colours.
574 is not set, 0 otherwise.
577 If greater than zero, lines of text will be formatted in a way that
578 don't exceed the given number of columns.
582 If nonzero, hide by default the body of the preformatted blocks.
585 can be used to toggle the visibility per-block.
586 .It hide-pre-closing-line
588 If nonzero, hide the closing line of preformatted blocks.
591 If nonzero, hide the start and end line of the preformatted blocks.
592 If both hide-pre-context and hide-pre-blocks are nonzero, preformatted
593 blocks are irremediably hidden.
597 URL for the new tab page.
607 .It Ic style Ar name Ar option
608 Change the styling of the element identified by
610 Multiple options may be specified within curly braces.
611 Valid style identifiers are:
612 .Bl -tag -width 16m -compact -offset Ds
614 for the area outside the lines in the body of the page.
616 for the completion in the minibuffer
617 .It line.compl.current
618 for the current completion
630 for the heading of a preformatted block.
632 for the content of a preformatted block.
634 for the closing line of a preformatted block.
637 .Dq i.e. the last line of the window
640 .Dq i.e. the info line right above the minibuffer
644 for the non-focused tabs.
651 .It Ic attr Ar prefix Oo Ar line Oo Ar trail Oc Oc
652 Sets the text attributes.
653 If only one value is given,
657 default to that; if two values are given then
661 Each attribute is a comma-separated list of keywords:
662 .Bl -tag -width underline -compact -offset Ds
666 best highlighting mode for the terminal.
670 reverses background/foreground colors.
672 makes the text blinking.
676 extra bright or bold.
679 Only the styles under the
681 prefix accept up to three attributes.
682 The other will only use the first one given.
683 .It Ic bg Ar prefix Oo Ar line Oo Ar trail Oc Oc
684 Sets the background color.
685 Follows the same behaviour as
687 regarding the optional parameters.
688 The colour is one of black, red, green, yellow, blue,
689 magenta, cyan and white; colour0 to colour255
690 .Pq or color0 to color255
691 from the 256-colour set;
692 default for the default colour.
693 .It Ic fg Ar prefix Oo Ar line Oo Ar trail Oc Oc
694 Sets the foreground color.
697 .It Ic prefix Ar prfx Op Ar cont
698 Sets the prefix for the current line type to
702 as the prefix for the continuation lines
703 .Pq i.e. when a long line gets wrapped.
706 is not given its value will be the same of
711 .Bl -tag -width Ds -compact
712 .It Pa ~/.telescope/bookmarks.gmi
714 .It Pa ~/.telescope/config
715 Default configuration file.
716 .It Pa ~/.telescope/known_hosts
717 Contains a list of host keys for all the hosts the user has visited.
718 See the TOFU section for more info.
719 .It Pa ~/.telescope/lock
720 Lock file used to prevent multiple instance of
722 from running at the same time.
723 .It Pa ~/.telescope/session
724 Contains the list of opened tabs in the last session, one per line.
727 and loaded on startup.
730 The following is my config file:
731 .Bd -literal -offset indent
732 # enable colors regardless of $NO_COLOR
733 set enable-colors = 1
748 It's possible to browse
750 .Pq i.e. simple websites
751 by using programs like the duckling-proxy by defining a proxy in
752 .Pa ~/.telescope/config :
753 .Bd -literal -offset indent
754 proxy http via "gemini://localhost:1965"
755 proxy https via "gemini://localhost:1965"
760 without any configuration use
761 .Bd -literal -offset indent
762 telescope -c /dev/null
768 program was written by
769 .An Omar Polo Aq Mt op@omarpolo.com .
