1 .\" Copyright (c) 2021, 2022 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: January 05 2022$
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
37 .It Fl C , Fl -colours
38 Show all available colors and exit.
39 This option can also be spelled
42 Specify an alternative configuration file.
44 .Pa ~/.config/telescope/config
47 Display version, usage and exit.
50 Only check the configuration file for validity.
57 from writing files to the disk and to acquire the lock, allowing to
58 run multiple instances at the same time.
60 still loads the session file and the custom about pages.
61 .It Fl v , Fl -version
62 Display version and exit.
66 interface is divided into four areas: the tabline, the body, the
67 modeline and the echoarea/minibuffer.
69 The tabline is always at the top of the screen and displays the tabs
70 separated by a vertical line.
71 When there are more tabs than the size of the window allow to display,
76 are shown at the start/end of the tabline to indicate that there are
77 more tabs in that direction.
79 The body occupies the majority of the visible area.
80 It contains the current page and optionally a side window.
82 The modeline is the second to last row of the screen.
83 It shows some information about the page: a spinner when the page is
84 loading, the trust level, the document type, the scroll offset and the
87 The echoarea is usually the last line of the screen.
88 Messages are often showed there, and link addresses too.
89 The echoarea is also used to obtain input from the user.
94 are invoked, the minibuffer area grows to show possible completions.
98 .Dq Trust, but Verify Pq where appropriate
101 .Pq Dq Trust On First Use .
102 The idea is to define three level of verification for a certificate:
106 the server fingerprint does NOT match the stored value.
109 the server fingerprint matches the store one.
112 the fingerprint matches and has been verified out-of-band.
115 The trust level of the page is indicated in the modeline with the
120 level is enough, but where is appropriate users should be able to
121 verify out-of-band the certificate.
123 At the moment, there is no built-in support for an out-of-band
125 .Sh SUPPORTED PROTOCOLS
126 The following protocols are supported:
127 .Bl -tag -width gemini://
132 See about:about for a list of all these pages.
136 such as .gmi, .gemini, .txt, .md, .markdown, .diff or .patch, can be
137 viewed inside the application.
138 Types of local files are detected solely based on the file extension.
139 On some systems, such as
141 only files inside special directories
142 .Pq like Pa /tmp No or Pa ~/Downloads
145 Finger URLs are interpreted as follows:
148 the host is determined by the host name portion of the URL
150 if the user portion of the URL is provided, it's interpreted as the
151 user to finger, otherwise the path component will be used
154 .Lk finger://user@hostname
156 .Lk finger://hostname/user
157 are treated as the same URL.
159 Gemini is fully supported, with the exception of client-certificates.
161 Gopher support is limited to items type 0, 1 and 7.
162 All text is assumed to be encoded in UTF-8 (or ASCII).
165 User-entered URLs, given as argument on the command line or entered
168 are intepreted with a simple heuristic:
171 if it's a proper absolute URL then use it as-is,
177 assume it's a file:// URL,
179 otherwise assume it's a Gemini URL.
181 .Sh CONFIGURATION FILE
184 reads the configuration file at
185 .Pa ~/.config/telescope/config
187 .Pa ~/.telescope/config .
189 It's possible to load a custom configuration file using the
194 will also load a file called
198 is the name of the terminal type
199 .Pq i.e. the TERM environment variable ,
202 The format of the configuration file is fairly flexible.
203 The current line can be extended over multiple ones using a
206 Comments can be put anywhere in the file using a hash mark
208 and extend to the end of the current line, but backslashes can't be
209 used to extend comments over multiple lines.
211 The following constructs are available:
213 .It Ic bind Ar map Ar key Ar cmd
220 Valid values for map are
222 .Pq i.e. when the user is viewing a page
225 .Pq i.e. when the minibuffer has the focus.
227 follows the same syntax described in
228 .Sx DEFAULT KEY BINDINGS
229 and all the possible functions are listed in
230 .Sx INTERACTIVE COMMANDS .
231 .It Ic proxy Ar proto Ic via Ar url
234 as proxy for all URLs with
238 must be a Gemini URI without path, query and fragment component.
239 .It Ic set Ar opt No = Ar val
246 .Bl -tag -width twelveletters -compact
249 If greater than zero, save the session after the specified amount of
250 seconds after some events happens
251 .Pq new or closed tabs, visited a link ...
255 If nonzero, don't wrap preformatted blocks.
259 The default download path.
264 If nonzero, when the text of a link starts with an emoji followed by a
265 space, use that emoji as line prefix.
269 If nonzero, enable colours.
275 If greater than zero, lines of text will be formatted in a way that
276 don't exceed the given number of columns.
278 .It Ic fringe-ignore-offset
280 If nonzero, the fringe doesn't obey to
283 .It Ic hide-pre-blocks
285 If nonzero, hide by default the body of the preformatted blocks.
288 can be used to toggle the visibility per-block.
289 .It Ic hide-pre-closing-line
291 If nonzero, hide the closing line of preformatted blocks.
293 .It Ic hide-pre-context
295 If nonzero, hide the start and end line of the preformatted blocks.
296 If both hide-pre-context and hide-pre-blocks are nonzero, preformatted
297 blocks are irremediably hidden.
301 URL for the new tab page.
304 .It Ic max-killed-tabs
306 The maximum number of closed tabs to keep track of, defaults to 10.
307 Must be a positive number; if zero, don't save closed tabs at all.
315 If tab-bar-show is -1 hide the tab bar permanently, if 0 show it
317 If it's 1, show the bar only when there is more than one tab.
321 If nonzero, set the terminal title to the page title.
324 .It Ic style Ar name Ar option
325 Change the styling of the element identified by
327 Multiple options may be specified within curly braces.
328 Valid style identifiers are:
329 .Bl -tag -width line.download.ongoing -compact -offset Ds
331 the area outside the lines in the body of the page.
334 .It line.compl.current
335 the current completion.
337 text in the *Help* buffer.
338 .It line.download.ongoing
340 .It line.download.done
342 .It line.download.info
343 informational text in the *Downloads* buffer.
346 lines draw after the end of a buffer.
358 the heading of a preformatted block.
360 the content of a preformatted block.
362 the closing line of a preformatted block.
372 the non-focused tabs.
379 .It Ic attr Ar prefix Oo Ar line Oo Ar trail Oc Oc
380 Sets the text attributes.
381 If only one value is given,
385 default to that; if two values are given then
389 Each attribute is a comma-separated list of keywords:
390 .Bl -tag -width underline -compact -offset Ds
394 best highlighting mode for the terminal.
398 reverses background/foreground colors.
400 makes the text blinking.
404 extra bright or bold.
407 Only the style identifiers with the
409 prefix accept up to three attributes.
410 The other will only use the first one given.
411 .It Ic bg Ar prefix Oo Ar line Oo Ar trail Oc Oc
412 Sets the background color.
413 Follows the same behaviour as
415 regarding the optional parameters.
416 The colour is one of black, red, green, yellow, blue,
417 magenta, cyan and white; colour0 to colour255
418 .Pq or color0 to color255
419 from the 256-colour set;
420 default for the default colour.
421 .It Ic fg Ar prefix Oo Ar line Oo Ar trail Oc Oc
422 Sets the foreground color.
425 .It Ic prefix Ar prfx Op Ar cont
426 Sets the prefix for the current line type to
430 as the prefix for the continuation lines
431 .Pq i.e. when a long line gets wrapped.
434 is not given its value will be the same of
438 .Sh DEFAULT KEY BINDINGS
439 The default key bindings are very similar to GNU Emacs, but care has
440 been taken to include also bindings familiar for
445 In the following examples, C-x means Control-x, M-x means Meta-x,
446 where the Meta key may be either a special key on the keyboard or the
447 ALT key; otherwise ESC followed by the key X works as well, and C-M-x
448 means to press the key X together with both Control and Meta.
450 Keys are usually a single character, like
454 but some special keys are accepted as well.
456 .Bl -tag -width 16m -offset indent -compact
466 Previous page/Page up
486 Depends on the configuration of the terminal emulator; usually shift
489 .Ss GNU Emacs-like keys
490 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
504 move-beginning-of-line
522 execute-extended-command
566 .Ss Xr vi 1 Ns -like keys
567 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
581 move-beginning-of-line
615 execute-extended-command
618 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
628 move-beginning-of-line
654 .Ss Neither Emacs nor vi specific
655 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
685 .Ss Minibuffer-specific keys
686 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
688 mini-complete-and-exit
696 mini-delete-backward-char
698 mini-delete-backward-char
700 mini-delete-backward-char
712 move-beginning-of-line
716 move-beginning-of-line
720 mini-previous-history-element
722 mini-next-history-element
732 insert-current-candidate
738 .Sh INTERACTIVE COMMANDS
739 Follows the documentation for the interactive commands.
740 These commands can be bound to a key or executed with
741 .Ic execute-extended-command .
742 .Ss Movement commands
743 .Bl -tag -width execute-extended-command -compact
745 Move point one character backward.
746 .It Ic backward-paragraph
747 Move point one paragraph backward.
748 .It Ic beginning-of-buffer
749 Move point to the beginning of the buffer.
751 Move point to the end of the buffer.
753 Move point one character forward.
754 .It Ic forward-paragraph
755 Move point one paragraph forward.
756 .It Ic insert-current-candidate
757 Copy the current selection text as minibuffer input.
758 .It Ic move-beginning-of-line
759 Move point at the beginning of the current (visual) line.
760 .It Ic move-end-of-line
761 Move point at the end of the current (visual) line.
763 Move point to the next link.
764 .It Ic next-completion
765 Select the next completion.
767 Move point to the next heading.
769 Move point to the next (visual) line, in the same column if possible.
770 .It Ic previous-button
771 Move point to the previous link.
772 .It Ic previous-completion
773 Select the previous completion.
774 .It Ic previous-heading
775 Move point to the previous heading.
777 Move point to the previous (visual) line.
779 .Ss Bookmark-related commands
780 .Bl -tag -width execute-extended-command -compact
782 Save a page in the bookmark file.
783 It preloads the minibuffer with the current URL.
784 .It Ic list-bookmarks
785 Load the bookmarks page.
787 .Ss Tab-related commands
788 .Bl -tag -width execute-extended-command -compact
790 Close the current tab.
791 .It Ic tab-close-other
792 Close all tabs but the current one.
794 Move the current tab after the next one, wrapping around if
797 Move the current tab before the previous one, wrapping around if needed.
801 Focus next tab, wrapping around eventually.
803 Focus the previous tab, wrapping around eventually.
805 Switch to a tab using the minibuffer.
806 .It Ic tab-undo-close
807 Re-open the most recently closed tab, if any.
810 .Bl -tag -width execute-extended-command -compact
815 .It Ic dec-fill-column
816 Decrement fill-column by two.
817 .It Ic execute-extended-command
818 Execute an internal command.
819 .It Ic kill-telescope
822 .It Ic inc-fill-column
823 Increment fill-column by two.
825 Select and visit a link using the minibuffer.
826 .It Ic load-current-url
827 Edit the current URL.
831 Go forward in the page history.
833 Toggle olivetti mode (i.e. horizontal centering of the lines of the
836 Select the other window.
838 Go backward in the page history.
840 Follow link at point, or toggle the visibility of the following
841 preformatted block if called when the cursor is on the heading of the block.
842 .It Ic push-button-new-tab
843 Follow link at point in a new tab.
845 Redraw the screen, useful if some background program messed up the
848 Reload the current page.
849 .It Ic reply-last-input
850 Reply the last input request.
852 Scroll down by one visual page.
853 .It Ic scroll-line-down
854 Scroll down by one line.
855 .It Ic scroll-line-up
856 Scroll up by one line.
858 Scroll up by one visual page.
859 .It Ic suspend-telescope
864 Jump to a line using the minibuffer.
866 Jump to a heading using the minibuffer.
868 Toggle side window with help about available keys and their associated
870 .It Ic toggle-pre-wrap
871 Toggle the wrapping of preformatted blocks.
873 Save the current buffer to the disk.
875 .Ss Minibuffer commands
876 .Bl -tag -width execute-extended-command -compact
878 Abort the current minibuffer action.
879 .It Ic mini-complete-and-exit
880 Complete the current minibuffer action.
881 .It Ic mini-delete-backward-char
882 Delete the character before the point.
883 .It Ic mini-delete-char
884 Delete the character after the point.
885 .It Ic mini-goto-beginning
886 Select the first completion, if any.
888 Select the last completion, if any.
889 .It Ic mini-kill-line
890 Delete from point until the end of the line.
891 .It Ic mini-next-history-element
892 Load the previous history element.
893 .It Ic mini-previous-history-element
894 Load the next history element.
897 The following aliases are available during
898 .Ic execute-extended-command :
899 .Bl -tag -width 16m -compact
908 .It Ic q No and Ic wq
916 is started, it inspects the following environment variables:
917 .Bl -tag -width NO_COLORS
919 The user's login directory.
921 To decide whether to use colors or not.
922 The content of the variable doesn't matter.
924 The user's terminal name.
925 .It Ev XDG_CACHE_HOME , Ev XDG_CONFIG_HOME , Ev XDG_DATA_HOME
926 If defined can alter the default location of the files used.
931 follows the XDG Base Directory Specification.
934 exists, XDG is ignored and all the files are stored inside it.
940 can further alter the location of these files.
942 .Bl -tag -width Ds -compact
943 .It Pa ~/.config/telescope/config
944 Default configuration file.
945 .It Pa ~/.local/share/telescope/pages/about_*.gmi
946 Overrides for built-in about: pages.
947 .It Pa ~/.local/share/telescope/bookmarks.gmi
949 .It Pa ~/.local/share/telescope/known_hosts
950 Hash of the certificates for all the known hosts.
951 Each line contains three fields: hostname with optional port number,
952 hash of the certificate and a numeric flag.
953 .It Pa ~/.cache/telescope/lock
954 Lock file used to prevent multiple instance of
956 from running at the same time.
957 .It Pa ~/.cache/telescope/session
958 The list of tabs from the last session.
961 It's possible to browse
963 .Pq i.e. simple websites
964 by using programs like the duckling-proxy by defining a proxy in
965 .Pa ~/.config/telescope/config :
966 .Bd -literal -offset indent
967 proxy http via "gemini://127.0.0.1:1965"
968 proxy https via "gemini://127.0.0.1:1965"
973 without any configuration
974 .Bd -literal -offset indent
975 telescope -c /dev/null
979 .%B XDG Base Directory Specification
980 .%U https://specifications.freedesktop.org/basedir-spec/latest/
984 .Dq Trust, but verify (where appropriate)
985 TOFU scheme was firstly suggested by thfr:
986 .Lk gemini://thfr.info/gemini/modified-trust-verify.gmi .
991 program was written by
992 .An Omar Polo Aq Mt op@omarpolo.com .
995 assumes a UTF-8 environment and doesn't try to cope with other encodings.
996 This can cause strange rendering issues if you're lucky, or possibly
997 weird thing happening depending on your locale and terminal emulator.
999 The algorithm used for text-wrapping is naive and doesn't really work for
1000 languages that make heavily use of glyphs composed by multiple UNICODE
1003 There's no UI for out-of-band certificates validation.