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 Specify an alternative configuration file.
41 .Pa $HOME/.telescope/config
44 Display version and usage.
47 Only check the configuration file for validity.
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
216 .Ss Xr vi 1 Ns -like keys
217 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
231 move-beginning-of-line
263 execute-extended-command
266 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
276 move-beginning-of-line
300 .Ss Neither Emacs nor vi specific
301 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
325 .Ss Minibuffer-specific keys
326 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
328 mini-complete-and-exit
336 mini-delete-backward-char
338 mini-delete-backward-char
340 mini-delete-backward-char
352 move-beginning-of-line
356 move-beginning-of-line
360 mini-previous-history-element
362 mini-next-history-element
372 insert-current-candidate
374 .Sh INTERACTIVE COMMANDS
375 Follows the documentation for the interactive commands.
376 These commands can be bound to a key or executed with
377 .Ic execute-extended-command .
378 .Ss Movement commands
379 .Bl -tag -width execute-extended-command -compact
381 Move point one character backward.
382 .It Ic backward-paragraph
383 Move point one paragraph backward.
384 .It Ic beginning-of-buffer
385 Move point to the beginning of the buffer.
387 Move point to the end of the buffer.
389 Move point one character forward.
390 .It Ic forward-paragraph
391 Move point one paragraph forward.
392 .It Ic insert-current-candidate
393 Copy the current selection text as minibuffer input.
394 .It Ic move-beginning-of-line
395 Move point at the beginning of the current (visual) line.
396 .It Ic move-end-of-line
397 Move point at the end of the current (visual) line.
399 Move point to the next link.
400 .It Ic next-completion
401 Select the next completion.
403 Move point to the next heading.
405 Move point to the next (visual) line, in the same column if possible.
406 .It Ic previous-button
407 Move point to the previous link.
408 .It Ic previous-completion
409 Select the previous completion.
410 .It Ic previous-heading
411 Move point to the previous heading.
413 Move point to the previous (visual) line.
415 .Ss Bookmark-related commands
416 .Bl -tag -width execute-extended-command -compact
418 Save a page in the bookmark file.
419 It preloads the minibuffer with the current URL.
420 .It Ic list-bookmarks
421 Load the bookmarks page.
423 .Ss Tab-related commands
424 .Bl -tag -width execute-extended-command -compact
426 Close the current tab.
427 .It Ic tab-close-other
428 Close all tabs but the current one.
430 Move the current tab after the next one, wrapping around if
433 Move the current tab before the previous one, wrapping around if needed.
437 Focus next tab, wrapping around eventually.
439 Focus the previous tab, wrapping around eventually.
441 Switch to a tab using the minibuffer.
444 .Bl -tag -width execute-extended-command -compact
447 .It Ic dec-fill-column
448 Decrement fill-column by two.
449 .It Ic execute-extended-command
450 Execute an internal command.
451 .It Ic kill-telescope
454 .It Ic inc-fill-column
455 Increment fill-column by two.
457 Select and visit a link using the minibuffer.
458 .It Ic load-current-url
459 Edit the current URL.
463 Go forward in the page history.
465 Toggle olivetti mode (i.e. horizontal centering of the lines of the
468 Go backward in the page history.
470 Follow link at point, or toggle the visibility of the following
471 preformatted block if called when the cursor is on the heading of the block.
472 .It Ic push-button-new-tab
473 Follow link at point in a new tab.
475 Redraw the screen, useful if some background program messed up the
478 Reload the current page.
480 Scroll down by one visual page.
481 .It Ic scroll-line-down
482 Scroll down by one line.
483 .It Ic scroll-line-up
484 Scroll up by one line.
486 Scroll up by one visual page.
487 .It Ic suspend-telescope
492 Jump to a line using the minibuffer.
494 Jump to a heading using the minibuffer.
496 Toggle side window with help about available keys and their associated
498 .It Ic toggle-pre-wrap
499 Toggle the wrapping of preformatted blocks.
501 .Ss Minibuffer commands
502 .Bl -tag -width execute-extended-command -compact
504 Abort the current minibuffer action.
505 .It Ic mini-complete-and-exit
506 Complete the current minibuffer action.
507 .It Ic mini-delete-backward-char
508 Delete the character before the point.
509 .It Ic mini-delete-char
510 Delete the character after the point.
511 .It Ic mini-goto-beginning
512 Select the first completion, if any.
514 Select the last completion, if any.
515 .It Ic mini-kill-line
516 Delete from point until the end of the line.
517 .It Ic mini-next-history-element
518 Load the previous history element.
519 .It Ic mini-previous-history-element
520 Load the next history element.
523 The following aliases are available during
524 .Ic execute-extended-command :
525 .Bl -tag -width 16m -compact
532 .It Ic q No and Ic wq
535 .Sh CONFIGURATION FILE
538 reads the configuration file at
539 .Pa ~/.telescope/config
540 or the one given with the
545 will also load a file called
549 is the name of the terminal type
550 .Pq i.e. the TERM variable ,
553 The format of the configuration file is fairly flexible.
554 The current line can be extended over multiple ones using a
557 Comments can be put anywhere in the file using a hash mark
559 and extend to the end of the current line, but backslashes can't be
560 used to extend comments over multiple lines.
562 The following constructs are available:
564 .It Ic bind Ar map Ar key Ar cmd
571 Valid values for map are
573 .Pq i.e. when the user is viewing a page
576 .Pq i.e. when the minibuffer has the focus.
578 follows the same syntax described in
579 .Sx DEFAULT KEY BINDINGS
580 and all the possible functions are listed in
581 .Sx INTERACTIVE COMMANDS .
582 .It Ic proxy Ar proto Ic via Ar url
585 as proxy for all URLs with
589 must be a Gemini URI without path, query and fragment component.
590 .It Ic set Ar opt No = Ar val
597 .Bl -tag -width twelveletters -compact
600 If nonzero, don't wrap preformatted blocks.
603 If not zero, when the text of a link starts with an emoji followed by
604 a space, use that emoji as line prefix.
608 If not zero, enable colours.
611 is not set, 0 otherwise.
614 If greater than zero, lines of text will be formatted in a way that
615 don't exceed the given number of columns.
619 If nonzero, hide by default the body of the preformatted blocks.
622 can be used to toggle the visibility per-block.
623 .It hide-pre-closing-line
625 If nonzero, hide the closing line of preformatted blocks.
628 If nonzero, hide the start and end line of the preformatted blocks.
629 If both hide-pre-context and hide-pre-blocks are nonzero, preformatted
630 blocks are irremediably hidden.
634 URL for the new tab page.
645 If nonzero, set the terminal title.
648 .It Ic style Ar name Ar option
649 Change the styling of the element identified by
651 Multiple options may be specified within curly braces.
652 Valid style identifiers are:
653 .Bl -tag -width 16m -compact -offset Ds
655 for the area outside the lines in the body of the page.
657 for the completion in the minibuffer
658 .It line.compl.current
659 for the current completion
671 for the heading of a preformatted block.
673 for the content of a preformatted block.
675 for the closing line of a preformatted block.
678 .Dq i.e. the last line of the window
681 .Dq i.e. the info line right above the minibuffer
685 for the non-focused tabs.
692 .It Ic attr Ar prefix Oo Ar line Oo Ar trail Oc Oc
693 Sets the text attributes.
694 If only one value is given,
698 default to that; if two values are given then
702 Each attribute is a comma-separated list of keywords:
703 .Bl -tag -width underline -compact -offset Ds
707 best highlighting mode for the terminal.
711 reverses background/foreground colors.
713 makes the text blinking.
717 extra bright or bold.
720 Only the styles under the
722 prefix accept up to three attributes.
723 The other will only use the first one given.
724 .It Ic bg Ar prefix Oo Ar line Oo Ar trail Oc Oc
725 Sets the background color.
726 Follows the same behaviour as
728 regarding the optional parameters.
729 The colour is one of black, red, green, yellow, blue,
730 magenta, cyan and white; colour0 to colour255
731 .Pq or color0 to color255
732 from the 256-colour set;
733 default for the default colour.
734 .It Ic fg Ar prefix Oo Ar line Oo Ar trail Oc Oc
735 Sets the foreground color.
738 .It Ic prefix Ar prfx Op Ar cont
739 Sets the prefix for the current line type to
743 as the prefix for the continuation lines
744 .Pq i.e. when a long line gets wrapped.
747 is not given its value will be the same of
752 .Bl -tag -width Ds -compact
753 .It Pa ~/.telescope/bookmarks.gmi
755 .It Pa ~/.telescope/config
756 Default configuration file.
757 .It Pa ~/.telescope/known_hosts
758 Contains a list of host keys for all the hosts the user has visited.
759 See the TOFU section for more info.
760 .It Pa ~/.telescope/lock
761 Lock file used to prevent multiple instance of
763 from running at the same time.
764 .It Pa ~/.telescope/session
765 Contains the list of tabs from the last session.
766 Every line identifies a tab.
767 The syntax is the full URL, followed by a space, followed by an
768 optional comma-separated list of attributes.
771 and loaded on startup.
774 The following is my config file:
775 .Bd -literal -offset indent
776 # enable colors regardless of $NO_COLOR
777 set enable-colors = 1
792 It's possible to browse
794 .Pq i.e. simple websites
795 by using programs like the duckling-proxy by defining a proxy in
796 .Pa ~/.telescope/config :
797 .Bd -literal -offset indent
798 proxy http via "gemini://localhost:1965"
799 proxy https via "gemini://localhost:1965"
804 without any configuration use
805 .Bd -literal -offset indent
806 telescope -c /dev/null
812 program was written by
813 .An Omar Polo Aq Mt op@omarpolo.com .
