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: August 27 2021$
19 .Nd multi-protocol browser
29 is an interactive browser that supports the Finger, Gemini and Gopher
32 features tabs, a minibuffer, interactive completions, bookmarks and
33 out-of-band TOFU verification.
35 The arguments are as follows:
36 .Bl -tag -width xxxxxxxxxxxxx
38 Show all available colors and exit.
40 Specify an alternative configuration file.
42 .Pa $HOME/.telescope/config
45 Display version and usage.
48 Only check the configuration file for validity.
49 .It Fl v , Fl -version
54 interface is divided into four areas: the tabline, the body, the
55 modeline and the echoarea/minibuffer.
57 The tabline is always at the top of the screen and displays the tabs
58 separated by a vertical line.
59 When there are more tabs than the size of the window allow to display,
64 are shown at the start/end of the tabline to indicate that there are
65 more tabs in that direction.
67 The body occupies the majority of the visible area.
68 It contains the current page and optionally a side window.
70 The modeline is the second to last row of the screen.
71 It shows some information about the page: a spinner when the page is
72 loading, the trust level, the document type, the scroll offset and the
75 The echoarea is usually the last line of the screen.
76 Messages are often showed there, and link addresses too.
77 The echoarea is also used to obtain input from the user.
82 are invoked, the minibuffer area grows to show possible completions.
86 .Dq Trust, but Verify Pq where appropriate
89 .Pq Dq Trust On First Use .
90 The idea is to define three level of verification for a certificate:
94 the server fingerprint does NOT match the stored value.
97 the server fingerprint matches the store one.
100 the fingerprint matches and has been verified out-of-band.
103 The trust level of the page is indicated in the modeline with the
108 level is enough, but where is appropriate users should be able to
109 verify out-of-band the certificate.
111 At the moment, there is no built-in support for an out-of-band
113 .Sh SUPPORTED PROTOCOLS
114 The following protocols are supported:
115 .Bl -tag -width gemini://
120 See about:about for a list of all these pages.
124 such as .gmi, .gemini, .txt, .md, .markdown, .diff or .patch, can be
125 viewed inside the application.
126 Types of local files are detected solely based on the file extension.
127 On some systems, such as
129 only files inside special directories
130 .Pq like Pa /tmp No or Pa ~/Downloads
133 Finger URLs are interpreted as follows:
136 the host is determined by the host name portion of the URL
138 if the user portion of the URL is provided, it's interpreted as the
139 user to finger, otherwise the path component will be used
142 .Lk finger://user@hostname
144 .Lk finger://hostname/user
145 are treated as the same URL.
147 Gemini is fully supported, with the exception of client-certificates.
149 Gopher support is limited to items type 0, 1 and 7.
150 All text is assumed to be encoded in UTF-8 (or ASCII).
153 User-entered URLs, given as argument on the command line or entered
156 are intepreted with a simple heuristic:
159 if it's a proper absolute URL then use it as-is,
165 assume it's a file:// URL,
167 otherwise assume it's a Gemini URL.
169 .Sh DEFAULT KEY BINDINGS
170 The default key bindings are very similar to GNU Emacs, but care has
171 been taken to include also bindings familiar for
176 In the following examples, C-x means Control-x, M-x means Meta-x,
177 where the Meta key may be either a special key on the keyboard or the
178 ALT key; otherwise ESC followed by the key X works as well, and C-M-x
179 means to press the key X together with both Control and Meta.
181 Keys are usually a single character, like
185 but some special keys are accepted as well.
187 .Bl -tag -width 16m -offset indent -compact
197 Previous page/Page up
217 Depends on the configuration of the terminal emulator; usually shift
220 .Ss GNU Emacs-like keys
221 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
235 move-beginning-of-line
251 execute-extended-command
295 .Ss Xr vi 1 Ns -like keys
296 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
310 move-beginning-of-line
342 execute-extended-command
345 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
355 move-beginning-of-line
379 .Ss Neither Emacs nor vi specific
380 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
408 .Ss Minibuffer-specific keys
409 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
411 mini-complete-and-exit
419 mini-delete-backward-char
421 mini-delete-backward-char
423 mini-delete-backward-char
435 move-beginning-of-line
439 move-beginning-of-line
443 mini-previous-history-element
445 mini-next-history-element
455 insert-current-candidate
461 .Sh INTERACTIVE COMMANDS
462 Follows the documentation for the interactive commands.
463 These commands can be bound to a key or executed with
464 .Ic execute-extended-command .
465 .Ss Movement commands
466 .Bl -tag -width execute-extended-command -compact
468 Move point one character backward.
469 .It Ic backward-paragraph
470 Move point one paragraph backward.
471 .It Ic beginning-of-buffer
472 Move point to the beginning of the buffer.
474 Move point to the end of the buffer.
476 Move point one character forward.
477 .It Ic forward-paragraph
478 Move point one paragraph forward.
479 .It Ic insert-current-candidate
480 Copy the current selection text as minibuffer input.
481 .It Ic move-beginning-of-line
482 Move point at the beginning of the current (visual) line.
483 .It Ic move-end-of-line
484 Move point at the end of the current (visual) line.
486 Move point to the next link.
487 .It Ic next-completion
488 Select the next completion.
490 Move point to the next heading.
492 Move point to the next (visual) line, in the same column if possible.
493 .It Ic previous-button
494 Move point to the previous link.
495 .It Ic previous-completion
496 Select the previous completion.
497 .It Ic previous-heading
498 Move point to the previous heading.
500 Move point to the previous (visual) line.
502 .Ss Bookmark-related commands
503 .Bl -tag -width execute-extended-command -compact
505 Save a page in the bookmark file.
506 It preloads the minibuffer with the current URL.
507 .It Ic list-bookmarks
508 Load the bookmarks page.
510 .Ss Tab-related commands
511 .Bl -tag -width execute-extended-command -compact
513 Close the current tab.
514 .It Ic tab-close-other
515 Close all tabs but the current one.
517 Move the current tab after the next one, wrapping around if
520 Move the current tab before the previous one, wrapping around if needed.
524 Focus next tab, wrapping around eventually.
526 Focus the previous tab, wrapping around eventually.
528 Switch to a tab using the minibuffer.
531 .Bl -tag -width execute-extended-command -compact
534 .It Ic dec-fill-column
535 Decrement fill-column by two.
536 .It Ic execute-extended-command
537 Execute an internal command.
538 .It Ic kill-telescope
541 .It Ic inc-fill-column
542 Increment fill-column by two.
544 Select and visit a link using the minibuffer.
545 .It Ic load-current-url
546 Edit the current URL.
550 Go forward in the page history.
552 Toggle olivetti mode (i.e. horizontal centering of the lines of the
555 Select the other window.
557 Go backward in the page history.
559 Follow link at point, or toggle the visibility of the following
560 preformatted block if called when the cursor is on the heading of the block.
561 .It Ic push-button-new-tab
562 Follow link at point in a new tab.
564 Redraw the screen, useful if some background program messed up the
567 Reload the current page.
569 Scroll down by one visual page.
570 .It Ic scroll-line-down
571 Scroll down by one line.
572 .It Ic scroll-line-up
573 Scroll up by one line.
575 Scroll up by one visual page.
576 .It Ic suspend-telescope
581 Jump to a line using the minibuffer.
583 Jump to a heading using the minibuffer.
585 Toggle side window with help about available keys and their associated
587 .It Ic toggle-pre-wrap
588 Toggle the wrapping of preformatted blocks.
590 .Ss Minibuffer commands
591 .Bl -tag -width execute-extended-command -compact
593 Abort the current minibuffer action.
594 .It Ic mini-complete-and-exit
595 Complete the current minibuffer action.
596 .It Ic mini-delete-backward-char
597 Delete the character before the point.
598 .It Ic mini-delete-char
599 Delete the character after the point.
600 .It Ic mini-goto-beginning
601 Select the first completion, if any.
603 Select the last completion, if any.
604 .It Ic mini-kill-line
605 Delete from point until the end of the line.
606 .It Ic mini-next-history-element
607 Load the previous history element.
608 .It Ic mini-previous-history-element
609 Load the next history element.
612 The following aliases are available during
613 .Ic execute-extended-command :
614 .Bl -tag -width 16m -compact
621 .It Ic q No and Ic wq
624 .Sh CONFIGURATION FILE
627 reads the configuration file at
628 .Pa ~/.telescope/config
629 or the one given with the
634 will also load a file called
638 is the name of the terminal type
639 .Pq i.e. the TERM environment variable ,
642 The format of the configuration file is fairly flexible.
643 The current line can be extended over multiple ones using a
646 Comments can be put anywhere in the file using a hash mark
648 and extend to the end of the current line, but backslashes can't be
649 used to extend comments over multiple lines.
651 The following constructs are available:
653 .It Ic bind Ar map Ar key Ar cmd
660 Valid values for map are
662 .Pq i.e. when the user is viewing a page
665 .Pq i.e. when the minibuffer has the focus.
667 follows the same syntax described in
668 .Sx DEFAULT KEY BINDINGS
669 and all the possible functions are listed in
670 .Sx INTERACTIVE COMMANDS .
671 .It Ic proxy Ar proto Ic via Ar url
674 as proxy for all URLs with
678 must be a Gemini URI without path, query and fragment component.
679 .It Ic set Ar opt No = Ar val
686 .Bl -tag -width twelveletters -compact
689 If greater than zero, save the session after the specified amount of
690 seconds after some events happens
691 .Pq new or closed tabs, visited a link ...
695 If nonzero, don't wrap preformatted blocks.
699 The default download path.
704 If nonzero, when the text of a link starts with an emoji followed by a
705 space, use that emoji as line prefix.
709 If nonzero, enable colours.
715 If greater than zero, lines of text will be formatted in a way that
716 don't exceed the given number of columns.
720 If nonzero, hide by default the body of the preformatted blocks.
723 can be used to toggle the visibility per-block.
724 .It hide-pre-closing-line
726 If nonzero, hide the closing line of preformatted blocks.
730 If nonzero, hide the start and end line of the preformatted blocks.
731 If both hide-pre-context and hide-pre-blocks are nonzero, preformatted
732 blocks are irremediably hidden.
736 URL for the new tab page.
746 If nonzero, set the terminal title to the page title.
750 If tab-bar-show is -1 hide the tab bar permanently, if 0 show it
752 If it's 1, show the bar only when there is more than one tab.
755 .It Ic style Ar name Ar option
756 Change the styling of the element identified by
758 Multiple options may be specified within curly braces.
759 Valid style identifiers are:
760 .Bl -tag -width line.compl.current -compact -offset Ds
762 the area outside the lines in the body of the page.
765 .It line.compl.current
766 the current completion.
768 text in the *Help* buffer.
780 the heading of a preformatted block.
782 the content of a preformatted block.
784 the closing line of a preformatted block.
792 the non-focused tabs.
799 .It Ic attr Ar prefix Oo Ar line Oo Ar trail Oc Oc
800 Sets the text attributes.
801 If only one value is given,
805 default to that; if two values are given then
809 Each attribute is a comma-separated list of keywords:
810 .Bl -tag -width underline -compact -offset Ds
814 best highlighting mode for the terminal.
818 reverses background/foreground colors.
820 makes the text blinking.
824 extra bright or bold.
827 Only the style identifiers with the
829 prefix accept up to three attributes.
830 The other will only use the first one given.
831 .It Ic bg Ar prefix Oo Ar line Oo Ar trail Oc Oc
832 Sets the background color.
833 Follows the same behaviour as
835 regarding the optional parameters.
836 The colour is one of black, red, green, yellow, blue,
837 magenta, cyan and white; colour0 to colour255
838 .Pq or color0 to color255
839 from the 256-colour set;
840 default for the default colour.
841 .It Ic fg Ar prefix Oo Ar line Oo Ar trail Oc Oc
842 Sets the foreground color.
845 .It Ic prefix Ar prfx Op Ar cont
846 Sets the prefix for the current line type to
850 as the prefix for the continuation lines
851 .Pq i.e. when a long line gets wrapped.
854 is not given its value will be the same of
861 is started, it inspects the following environment variables:
862 .Bl -tag -width NO_COLORS
864 The user's login directory.
866 To decide whether to use colors or not.
867 The content of the variable doesn't matter.
869 The user's terminal name.
872 .Bl -tag -width Ds -compact
873 .It Pa ~/.telescope/bookmarks.gmi
875 .It Pa ~/.telescope/config
876 Default configuration file.
877 .It Pa ~/.telescope/known_hosts
878 Hash of the certificates for all the known hosts.
879 Each line contains three fields: hostname with optional port number,
880 hash of the certificate and a numeric flag.
881 .It Pa ~/.telescope/lock
882 Lock file used to prevent multiple instance of
884 from running at the same time.
885 .It Pa ~/.telescope/pages/about_*.gmi
886 Overrides for built-in about: pages.
887 .It Pa ~/.telescope/session
888 The list of tabs from the last session.
889 Every line identifies a tab and contains three space-separated fields:
890 the full URL, a comma-separated list of attributes and the cached
894 and loaded during startup.
897 It's possible to browse
899 .Pq i.e. simple websites
900 by using programs like the duckling-proxy by defining a proxy in
901 .Pa ~/.telescope/config :
902 .Bd -literal -offset indent
903 proxy http via "gemini://127.0.0.1:1965"
904 proxy https via "gemini://127.0.0.1:1965"
909 without any configuration
910 .Bd -literal -offset indent
911 telescope -c /dev/null
917 program was written by
918 .An Omar Polo Aq Mt op@omarpolo.com .
920 There's no UI for out-of-band certificates validation.
