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: September 15 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.
55 from writing files to the disk.
56 .It Fl v , Fl -version
61 interface is divided into four areas: the tabline, the body, the
62 modeline and the echoarea/minibuffer.
64 The tabline is always at the top of the screen and displays the tabs
65 separated by a vertical line.
66 When there are more tabs than the size of the window allow to display,
71 are shown at the start/end of the tabline to indicate that there are
72 more tabs in that direction.
74 The body occupies the majority of the visible area.
75 It contains the current page and optionally a side window.
77 The modeline is the second to last row of the screen.
78 It shows some information about the page: a spinner when the page is
79 loading, the trust level, the document type, the scroll offset and the
82 The echoarea is usually the last line of the screen.
83 Messages are often showed there, and link addresses too.
84 The echoarea is also used to obtain input from the user.
89 are invoked, the minibuffer area grows to show possible completions.
93 .Dq Trust, but Verify Pq where appropriate
96 .Pq Dq Trust On First Use .
97 The idea is to define three level of verification for a certificate:
101 the server fingerprint does NOT match the stored value.
104 the server fingerprint matches the store one.
107 the fingerprint matches and has been verified out-of-band.
110 The trust level of the page is indicated in the modeline with the
115 level is enough, but where is appropriate users should be able to
116 verify out-of-band the certificate.
118 At the moment, there is no built-in support for an out-of-band
120 .Sh SUPPORTED PROTOCOLS
121 The following protocols are supported:
122 .Bl -tag -width gemini://
127 See about:about for a list of all these pages.
131 such as .gmi, .gemini, .txt, .md, .markdown, .diff or .patch, can be
132 viewed inside the application.
133 Types of local files are detected solely based on the file extension.
134 On some systems, such as
136 only files inside special directories
137 .Pq like Pa /tmp No or Pa ~/Downloads
140 Finger URLs are interpreted as follows:
143 the host is determined by the host name portion of the URL
145 if the user portion of the URL is provided, it's interpreted as the
146 user to finger, otherwise the path component will be used
149 .Lk finger://user@hostname
151 .Lk finger://hostname/user
152 are treated as the same URL.
154 Gemini is fully supported, with the exception of client-certificates.
156 Gopher support is limited to items type 0, 1 and 7.
157 All text is assumed to be encoded in UTF-8 (or ASCII).
160 User-entered URLs, given as argument on the command line or entered
163 are intepreted with a simple heuristic:
166 if it's a proper absolute URL then use it as-is,
172 assume it's a file:// URL,
174 otherwise assume it's a Gemini URL.
176 .Sh DEFAULT KEY BINDINGS
177 The default key bindings are very similar to GNU Emacs, but care has
178 been taken to include also bindings familiar for
183 In the following examples, C-x means Control-x, M-x means Meta-x,
184 where the Meta key may be either a special key on the keyboard or the
185 ALT key; otherwise ESC followed by the key X works as well, and C-M-x
186 means to press the key X together with both Control and Meta.
188 Keys are usually a single character, like
192 but some special keys are accepted as well.
194 .Bl -tag -width 16m -offset indent -compact
204 Previous page/Page up
224 Depends on the configuration of the terminal emulator; usually shift
227 .Ss GNU Emacs-like keys
228 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
242 move-beginning-of-line
258 execute-extended-command
302 .Ss Xr vi 1 Ns -like keys
303 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
317 move-beginning-of-line
349 execute-extended-command
352 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
362 move-beginning-of-line
386 .Ss Neither Emacs nor vi specific
387 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
415 .Ss Minibuffer-specific keys
416 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
418 mini-complete-and-exit
426 mini-delete-backward-char
428 mini-delete-backward-char
430 mini-delete-backward-char
442 move-beginning-of-line
446 move-beginning-of-line
450 mini-previous-history-element
452 mini-next-history-element
462 insert-current-candidate
468 .Sh INTERACTIVE COMMANDS
469 Follows the documentation for the interactive commands.
470 These commands can be bound to a key or executed with
471 .Ic execute-extended-command .
472 .Ss Movement commands
473 .Bl -tag -width execute-extended-command -compact
475 Move point one character backward.
476 .It Ic backward-paragraph
477 Move point one paragraph backward.
478 .It Ic beginning-of-buffer
479 Move point to the beginning of the buffer.
481 Move point to the end of the buffer.
483 Move point one character forward.
484 .It Ic forward-paragraph
485 Move point one paragraph forward.
486 .It Ic insert-current-candidate
487 Copy the current selection text as minibuffer input.
488 .It Ic move-beginning-of-line
489 Move point at the beginning of the current (visual) line.
490 .It Ic move-end-of-line
491 Move point at the end of the current (visual) line.
493 Move point to the next link.
494 .It Ic next-completion
495 Select the next completion.
497 Move point to the next heading.
499 Move point to the next (visual) line, in the same column if possible.
500 .It Ic previous-button
501 Move point to the previous link.
502 .It Ic previous-completion
503 Select the previous completion.
504 .It Ic previous-heading
505 Move point to the previous heading.
507 Move point to the previous (visual) line.
509 .Ss Bookmark-related commands
510 .Bl -tag -width execute-extended-command -compact
512 Save a page in the bookmark file.
513 It preloads the minibuffer with the current URL.
514 .It Ic list-bookmarks
515 Load the bookmarks page.
517 .Ss Tab-related commands
518 .Bl -tag -width execute-extended-command -compact
520 Close the current tab.
521 .It Ic tab-close-other
522 Close all tabs but the current one.
524 Move the current tab after the next one, wrapping around if
527 Move the current tab before the previous one, wrapping around if needed.
531 Focus next tab, wrapping around eventually.
533 Focus the previous tab, wrapping around eventually.
535 Switch to a tab using the minibuffer.
538 .Bl -tag -width execute-extended-command -compact
541 .It Ic dec-fill-column
542 Decrement fill-column by two.
543 .It Ic execute-extended-command
544 Execute an internal command.
545 .It Ic kill-telescope
548 .It Ic inc-fill-column
549 Increment fill-column by two.
551 Select and visit a link using the minibuffer.
552 .It Ic load-current-url
553 Edit the current URL.
557 Go forward in the page history.
559 Toggle olivetti mode (i.e. horizontal centering of the lines of the
562 Select the other window.
564 Go backward in the page history.
566 Follow link at point, or toggle the visibility of the following
567 preformatted block if called when the cursor is on the heading of the block.
568 .It Ic push-button-new-tab
569 Follow link at point in a new tab.
571 Redraw the screen, useful if some background program messed up the
574 Reload the current page.
576 Scroll down by one visual page.
577 .It Ic scroll-line-down
578 Scroll down by one line.
579 .It Ic scroll-line-up
580 Scroll up by one line.
582 Scroll up by one visual page.
583 .It Ic suspend-telescope
588 Jump to a line using the minibuffer.
590 Jump to a heading using the minibuffer.
592 Toggle side window with help about available keys and their associated
594 .It Ic toggle-pre-wrap
595 Toggle the wrapping of preformatted blocks.
597 .Ss Minibuffer commands
598 .Bl -tag -width execute-extended-command -compact
600 Abort the current minibuffer action.
601 .It Ic mini-complete-and-exit
602 Complete the current minibuffer action.
603 .It Ic mini-delete-backward-char
604 Delete the character before the point.
605 .It Ic mini-delete-char
606 Delete the character after the point.
607 .It Ic mini-goto-beginning
608 Select the first completion, if any.
610 Select the last completion, if any.
611 .It Ic mini-kill-line
612 Delete from point until the end of the line.
613 .It Ic mini-next-history-element
614 Load the previous history element.
615 .It Ic mini-previous-history-element
616 Load the next history element.
619 The following aliases are available during
620 .Ic execute-extended-command :
621 .Bl -tag -width 16m -compact
628 .It Ic q No and Ic wq
631 .Sh CONFIGURATION FILE
634 reads the configuration file at
635 .Pa ~/.telescope/config
636 or the one given with the
641 will also load a file called
645 is the name of the terminal type
646 .Pq i.e. the TERM environment variable ,
649 The format of the configuration file is fairly flexible.
650 The current line can be extended over multiple ones using a
653 Comments can be put anywhere in the file using a hash mark
655 and extend to the end of the current line, but backslashes can't be
656 used to extend comments over multiple lines.
658 The following constructs are available:
660 .It Ic bind Ar map Ar key Ar cmd
667 Valid values for map are
669 .Pq i.e. when the user is viewing a page
672 .Pq i.e. when the minibuffer has the focus.
674 follows the same syntax described in
675 .Sx DEFAULT KEY BINDINGS
676 and all the possible functions are listed in
677 .Sx INTERACTIVE COMMANDS .
678 .It Ic proxy Ar proto Ic via Ar url
681 as proxy for all URLs with
685 must be a Gemini URI without path, query and fragment component.
686 .It Ic set Ar opt No = Ar val
693 .Bl -tag -width twelveletters -compact
696 If greater than zero, save the session after the specified amount of
697 seconds after some events happens
698 .Pq new or closed tabs, visited a link ...
702 If nonzero, don't wrap preformatted blocks.
706 The default download path.
711 If nonzero, when the text of a link starts with an emoji followed by a
712 space, use that emoji as line prefix.
716 If nonzero, enable colours.
722 If greater than zero, lines of text will be formatted in a way that
723 don't exceed the given number of columns.
727 If nonzero, hide by default the body of the preformatted blocks.
730 can be used to toggle the visibility per-block.
731 .It hide-pre-closing-line
733 If nonzero, hide the closing line of preformatted blocks.
737 If nonzero, hide the start and end line of the preformatted blocks.
738 If both hide-pre-context and hide-pre-blocks are nonzero, preformatted
739 blocks are irremediably hidden.
743 URL for the new tab page.
753 If nonzero, set the terminal title to the page title.
757 If tab-bar-show is -1 hide the tab bar permanently, if 0 show it
759 If it's 1, show the bar only when there is more than one tab.
762 .It Ic style Ar name Ar option
763 Change the styling of the element identified by
765 Multiple options may be specified within curly braces.
766 Valid style identifiers are:
767 .Bl -tag -width line.compl.current -compact -offset Ds
769 the area outside the lines in the body of the page.
772 .It line.compl.current
773 the current completion.
775 text in the *Help* buffer.
787 the heading of a preformatted block.
789 the content of a preformatted block.
791 the closing line of a preformatted block.
799 the non-focused tabs.
806 .It Ic attr Ar prefix Oo Ar line Oo Ar trail Oc Oc
807 Sets the text attributes.
808 If only one value is given,
812 default to that; if two values are given then
816 Each attribute is a comma-separated list of keywords:
817 .Bl -tag -width underline -compact -offset Ds
821 best highlighting mode for the terminal.
825 reverses background/foreground colors.
827 makes the text blinking.
831 extra bright or bold.
834 Only the style identifiers with the
836 prefix accept up to three attributes.
837 The other will only use the first one given.
838 .It Ic bg Ar prefix Oo Ar line Oo Ar trail Oc Oc
839 Sets the background color.
840 Follows the same behaviour as
842 regarding the optional parameters.
843 The colour is one of black, red, green, yellow, blue,
844 magenta, cyan and white; colour0 to colour255
845 .Pq or color0 to color255
846 from the 256-colour set;
847 default for the default colour.
848 .It Ic fg Ar prefix Oo Ar line Oo Ar trail Oc Oc
849 Sets the foreground color.
852 .It Ic prefix Ar prfx Op Ar cont
853 Sets the prefix for the current line type to
857 as the prefix for the continuation lines
858 .Pq i.e. when a long line gets wrapped.
861 is not given its value will be the same of
868 is started, it inspects the following environment variables:
869 .Bl -tag -width NO_COLORS
871 The user's login directory.
873 To decide whether to use colors or not.
874 The content of the variable doesn't matter.
876 The user's terminal name.
879 .Bl -tag -width Ds -compact
880 .It Pa ~/.telescope/bookmarks.gmi
882 .It Pa ~/.telescope/config
883 Default configuration file.
884 .It Pa ~/.telescope/known_hosts
885 Hash of the certificates for all the known hosts.
886 Each line contains three fields: hostname with optional port number,
887 hash of the certificate and a numeric flag.
888 .It Pa ~/.telescope/lock
889 Lock file used to prevent multiple instance of
891 from running at the same time.
892 .It Pa ~/.telescope/pages/about_*.gmi
893 Overrides for built-in about: pages.
894 .It Pa ~/.telescope/session
895 The list of tabs from the last session.
896 Every line identifies a tab and contains three space-separated fields:
897 the full URL, a comma-separated list of attributes and the cached
901 and loaded during startup.
904 It's possible to browse
906 .Pq i.e. simple websites
907 by using programs like the duckling-proxy by defining a proxy in
908 .Pa ~/.telescope/config :
909 .Bd -literal -offset indent
910 proxy http via "gemini://127.0.0.1:1965"
911 proxy https via "gemini://127.0.0.1:1965"
916 without any configuration
917 .Bd -literal -offset indent
918 telescope -c /dev/null
924 program was written by
925 .An Omar Polo Aq Mt op@omarpolo.com .
927 There's no UI for out-of-band certificates validation.
