1 .\" Copyright (c) 2021, 2022, 2024 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: February 12 2024$
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 Specify an alternative configuration file.
40 .Pa ~/.config/telescope/config
43 Display version, usage and exit.
46 Only check the configuration file for validity.
53 from writing files to the disk and to acquire the lock, allowing to
54 run multiple instances at the same time.
56 still loads the session file and the custom about pages.
57 .It Fl v , Fl -version
58 Display version and exit.
62 interface is divided into four areas: the tabline, the body, the
63 modeline and the echoarea/minibuffer.
65 The tabline is always at the top of the screen and displays the tabs
66 separated by a vertical line.
67 When there are more tabs than the size of the window allow to display,
72 are shown at the start/end of the tabline to indicate that there are
73 more tabs in that direction.
75 The body occupies the majority of the visible area.
76 It contains the current page and optionally a side window.
78 The modeline is the second to last row of the screen.
79 It shows some information about the page: a spinner when the page is
80 loading, the trust level, whether a client certificate is in use, the
81 document type, the scroll offset and the URL.
82 When a client certificate is in use, a
86 The echoarea is usually the last line of the screen.
87 Messages are often showed there, and link addresses too.
88 The echoarea is also used to obtain input from the user.
93 are invoked, the minibuffer area grows to show possible completions.
97 .Dq Trust, but Verify Pq where appropriate
100 .Pq Dq Trust On First Use .
101 The idea is to define three level of verification for a certificate:
105 the server fingerprint does NOT match the stored value.
108 the server fingerprint matches the store one.
111 the fingerprint matches and has been verified out-of-band.
114 The trust level of the page is indicated in the modeline with the
119 level is enough, but where is appropriate users should be able to
120 verify out-of-band the certificate.
122 At the moment, there is no built-in support for an out-of-band
124 .Sh SUPPORTED PROTOCOLS
125 The following protocols are supported:
126 .Bl -tag -width gemini://
131 See about:about for a list of all these pages.
135 such as .gmi, .gemini, .txt, .md, .markdown, .diff or .patch, can be
136 viewed inside the application.
137 Types of local files are detected solely based on the file extension.
138 On some systems, such as
140 only files inside special directories
141 .Pq like Pa /tmp No or Pa ~/Downloads
144 Finger URLs are interpreted as follows:
147 the host is determined by the host name portion of the URL
149 if the user portion of the URL is provided, it's interpreted as the
150 user to finger, otherwise the path component will be used
153 .Lk finger://user@hostname
155 .Lk finger://hostname/user
156 are treated as the same URL.
158 Gemini is fully supported, with the exception of client-certificates.
160 Gopher support is limited to items type 0, 1 and 7.
161 All text is assumed to be encoded in UTF-8 (or ASCII).
164 User-entered URLs, given as argument on the command line or entered
167 by default are intepreted with a simple heuristic:
170 if it's a proper absolute URL then use it as-is,
176 assume it's a file:// URL,
178 otherwise treat it like a hostname with protocol
180 .Pq gemini by default .
184 .Ic load-url-use-heuristic
185 can be used to disable the use of heuristics.
186 .Sh CONFIGURATION FILE
189 reads the configuration file at
190 .Pa ~/.config/telescope/config
192 .Pa ~/.telescope/config .
194 It's possible to load a custom configuration file using the
199 will also load a file called
203 is the name of the terminal type
204 .Pq i.e. the TERM environment variable ,
207 The format of the configuration file is fairly flexible.
208 The current line can be extended over multiple ones using a
211 Comments can be put anywhere in the file using a hash mark
213 and extend to the end of the current line, but backslashes can't be
214 used to extend comments over multiple lines.
216 The following constructs are available:
218 .It Ic bind Ar map Ar key Ar cmd
225 Valid values for map are
227 .Pq i.e. when the user is viewing a page
230 .Pq i.e. when the minibuffer has the focus.
232 follows the same syntax described in
233 .Sx DEFAULT KEY BINDINGS
234 and all the possible functions are listed in
235 .Sx INTERACTIVE COMMANDS .
236 .It Ic proxy Ar proto Ic via Ar url
239 as proxy for all URLs with
243 must be a Gemini URI without path, query and fragment component.
244 .It Ic set Ar opt No = Ar val
251 .Bl -tag -width twelveletters -compact
254 If greater than zero, save the session after the specified amount of
255 seconds after some events happens
256 .Pq new or closed tabs, visited a link ...
258 .It Ic default-protocol
260 The default protocol assumed for the
267 If true, don't wrap preformatted blocks.
271 The default download path.
276 If true, when the text of a link starts with an emoji followed by a
277 space, use that emoji as line prefix.
281 If true, enable colours.
284 is set, true otherwise.
287 If greater than zero, lines of text will be formatted in a way that
288 don't exceed the given number of columns.
290 .It Ic fringe-ignore-offset
292 If true, the fringe doesn't obey to
295 .It Ic hide-pre-blocks
297 If true, hide by default the body of the preformatted blocks.
300 can be used to toggle the visibility per-block.
301 .It Ic hide-pre-closing-line
303 If true, hide the closing line of preformatted blocks.
305 .It Ic hide-pre-context
307 If true, hide the start and end line of the preformatted blocks.
308 If both hide-pre-context and hide-pre-blocks are nonzero, preformatted
309 blocks are irremediably hidden.
313 URL for the new tab page.
316 .It Ic load-url-use-heuristic
318 If false, don't use euristics to resolve the URLs.
319 Non-absolute URLs given as command line argument will be resolved as
322 will resolve as relative to the current URL.
324 .It Ic max-killed-tabs
326 The maximum number of closed tabs to keep track of, defaults to 10.
327 Must be a positive number; if zero, don't save closed tabs at all.
333 .It Ic default-search-engine
335 URL of the preferred search engine, used by the
338 If it's a Gemini URI, the user query will be appended as query,
339 replacing it if present.
340 If it's a Gopher URI, the user query will be sent as gopher search
342 No other URI scheme are allowed.
345 If tab-bar-show is -1 hide the tab bar permanently, if 0 show it
347 If it's 1, show the bar only when there is more than one tab.
351 If true, set the terminal title to the page title.
354 .It Ic style Ar name Ar option
355 Change the styling of the element identified by
357 Multiple options may be specified within curly braces.
358 Valid style identifiers are:
359 .Bl -tag -width line.download.ongoing -compact -offset Ds
361 the area outside the lines in the body of the page.
364 .It line.compl.current
365 the current completion.
367 text in the *Help* buffer.
368 .It line.download.ongoing
370 .It line.download.done
372 .It line.download.info
373 informational text in the *Downloads* buffer.
376 lines draw after the end of a buffer.
388 the heading of a preformatted block.
390 the content of a preformatted block.
392 the closing line of a preformatted block.
402 the non-focused tabs.
409 .It Ic attr Ar prefix Oo Ar line Oo Ar trail Oc Oc
410 Sets the text attributes.
411 If only one value is given,
415 default to that; if two values are given then
419 Each attribute is a comma-separated list of keywords:
420 .Bl -tag -width underline -compact -offset Ds
424 best highlighting mode for the terminal.
428 reverses background/foreground colors.
430 makes the text blinking.
434 extra bright or bold.
437 Only the style identifiers with the
439 prefix accept up to three attributes.
440 The other will only use the first one given.
441 .It Ic bg Ar prefix Oo Ar line Oo Ar trail Oc Oc
442 Sets the background color.
443 Follows the same behaviour as
445 regarding the optional parameters.
446 The colour is one of black, red, green, yellow, blue,
447 magenta, cyan and white; colour0 to colour255
448 .Pq or color0 to color255
449 from the 256-colour set;
450 default for the default colour.
451 .It Ic fg Ar prefix Oo Ar line Oo Ar trail Oc Oc
452 Sets the foreground color.
455 .It Ic prefix Ar prfx Op Ar cont
456 Sets the prefix for the current line type to
460 as the prefix for the continuation lines
461 .Pq i.e. when a long line gets wrapped.
464 is not given its value will be the same of
468 .Sh DEFAULT KEY BINDINGS
469 The default key bindings are very similar to GNU Emacs, but care has
470 been taken to include also bindings familiar for
475 In the following examples, C-x means Control-x, M-x means Meta-x,
476 where the Meta key may be either a special key on the keyboard or the
477 ALT key; otherwise ESC followed by the key X works as well, and C-M-x
478 means to press the key X together with both Control and Meta.
480 Keys are usually a single character, like
484 but some special keys are accepted as well.
486 .Bl -tag -width 16m -offset indent -compact
496 Previous page/Page up
516 Depends on the configuration of the terminal emulator; usually shift
519 .Ss GNU Emacs-like keys
520 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
534 move-beginning-of-line
552 execute-extended-command
596 .Ss Xr vi 1 Ns -like keys
597 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
611 move-beginning-of-line
651 execute-extended-command
654 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
664 move-beginning-of-line
690 .Ss Neither Emacs nor vi specific
691 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
723 .Ss Minibuffer-specific keys
724 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
726 mini-complete-and-exit
734 mini-delete-backward-char
736 mini-delete-backward-char
738 mini-delete-backward-char
750 move-beginning-of-line
754 move-beginning-of-line
760 mini-previous-history-element
762 mini-next-history-element
772 insert-current-candidate
778 .Sh INTERACTIVE COMMANDS
779 Follows the documentation for the interactive commands.
780 These commands can be bound to a key or executed with
781 .Ic execute-extended-command .
782 .Ss Movement commands
783 .Bl -tag -width execute-extended-command -compact
785 Move point one character backward.
786 .It Ic backward-paragraph
787 Move point one paragraph backward.
788 .It Ic beginning-of-buffer
789 Move point to the beginning of the buffer.
791 Move point to the end of the buffer.
793 Move point one character forward.
794 .It Ic forward-paragraph
795 Move point one paragraph forward.
796 .It Ic insert-current-candidate
797 Copy the current selection text as minibuffer input.
798 .It Ic move-beginning-of-line
799 Move point at the beginning of the current (visual) line.
800 .It Ic move-end-of-line
801 Move point at the end of the current (visual) line.
803 Move point to the next link.
804 .It Ic next-completion
805 Select the next completion.
807 Move point to the next heading.
809 Move point to the next (visual) line, in the same column if possible.
810 .It Ic previous-button
811 Move point to the previous link.
812 .It Ic previous-completion
813 Select the previous completion.
814 .It Ic previous-heading
815 Move point to the previous heading.
817 Move point to the previous (visual) line.
819 .Ss Bookmark-related commands
820 .Bl -tag -width execute-extended-command -compact
822 Save a page in the bookmark file.
823 It preloads the minibuffer with the current URL.
824 .It Ic list-bookmarks
825 Load the bookmarks page.
827 .Ss Client certificate-related commands
828 .Bl -tag -width execute-extended-command -compact
829 .It Ic client-certificate-info
830 Show the active client certificate.
831 .It Ic unload-certificate
832 Forget the certificate on this page.
833 .It Ic use-certificate
834 Use a certificate for the current page.
836 .Ss Tab-related commands
837 .Bl -tag -width execute-extended-command -compact
839 Close the current tab.
840 .It Ic tab-close-other
841 Close all tabs but the current one.
843 Move the current tab after the next one, wrapping around if
846 Move the current tab before the previous one, wrapping around if needed.
850 Focus next tab, wrapping around eventually.
852 Focus the previous tab, wrapping around eventually.
854 Switch to a tab using the minibuffer.
855 .It Ic tab-undo-close
856 Re-open the most recently closed tab, if any.
859 .Bl -tag -width execute-extended-command -compact
864 .It Ic dec-fill-column
865 Decrement fill-column by two.
866 .It Ic execute-extended-command
867 Execute an internal command.
869 Go to the home directory.
870 The home directory is assumed to be the first path component in the
873 If not found, loads the root directory.
874 .It Ic kill-telescope
877 .It Ic inc-fill-column
878 Increment fill-column by two.
880 Select and visit a link using the minibuffer.
881 .It Ic load-current-url
882 Edit the current URL.
885 Use the same heuristic as the URLs given as a command-line argument,
887 .Ic load-url-use-heuristic
888 option is unsed, in which case the URL is resolved using the current
891 Go forward in the page history.
893 Toggle olivetti mode (i.e. horizontal centering of the lines of the
896 Select the other window.
898 Go backward in the page history.
900 Follow link at point, or toggle the visibility of the following
901 preformatted block if called when the cursor is on the heading of the block.
902 .It Ic push-button-new-tab
903 Follow link at point in a new tab.
905 Redraw the screen, useful if some background program messed up the
908 Reload the current page.
909 .It Ic reply-last-input
910 Reply the last input request.
912 Go to the root directory.
914 Search using the preferred search engine.
916 Scroll down by one visual page.
917 .It Ic scroll-line-down
918 Scroll down by one line.
919 .It Ic scroll-line-up
920 Scroll up by one line.
922 Scroll up by one visual page.
923 .It Ic suspend-telescope
928 Jump to a line using the minibuffer.
930 Jump to a heading using the minibuffer.
932 Toggle side window with help about available keys and their associated
934 .It Ic toggle-pre-wrap
935 Toggle the wrapping of preformatted blocks.
937 Go up one level in the path hierarchy.
939 Save the current buffer to the disk.
941 .Ss Minibuffer commands
942 .Bl -tag -width execute-extended-command -compact
944 Abort the current minibuffer action.
945 .It Ic mini-complete-and-exit
946 Complete the current minibuffer action.
947 .It Ic mini-delete-backward-char
948 Delete the character before the point.
949 .It Ic mini-delete-char
950 Delete the character after the point.
951 .It Ic mini-goto-beginning
952 Select the first completion, if any.
954 Select the last completion, if any.
955 .It Ic mini-kill-line
956 Delete from point until the end of the line.
957 .It Ic mini-kill-whole-line
958 Delete the whole line.
959 .It Ic mini-next-history-element
960 Load the previous history element.
961 .It Ic mini-previous-history-element
962 Load the next history element.
965 The following aliases are available during
966 .Ic execute-extended-command :
967 .Bl -tag -width 16m -compact
976 .It Ic q No and Ic wq
984 is started, it inspects the following environment variables:
985 .Bl -tag -width NO_COLORS
987 The user's login directory.
989 To decide whether to use colors or not.
990 The content of the variable doesn't matter.
992 The user's terminal name.
993 .It Ev XDG_CACHE_HOME , Ev XDG_CONFIG_HOME , Ev XDG_DATA_HOME
994 If defined can alter the default location of the files used.
999 follows the XDG Base Directory Specification.
1002 exists, XDG is ignored and all the files are stored inside it.
1004 .Ev XDG_CACHE_HOME ,
1008 can further alter the location of these files.
1010 .Bl -tag -width Ds -compact
1011 .It Pa ~/.config/telescope/config
1012 Default configuration file.
1013 .It Pa ~/.local/share/telescope/pages/about_*.gmi
1014 Overrides for built-in about: pages.
1015 .It Pa ~/.local/share/telescope/bookmarks.gmi
1017 .It Pa ~/.local/share/telescope/known_hosts
1018 Hash of the certificates for all the known hosts.
1019 Each line contains three fields: hostname with optional port number,
1020 hash of the certificate and a numeric flag.
1021 .It Pa ~/.cache/telescope/lock
1022 Lock file used to prevent multiple instance of
1024 from running at the same time.
1025 .It Pa ~/.cache/telescope/session
1026 The list of tabs from the last session.
1029 It's possible to browse
1031 .Pq i.e. simple websites
1032 by using programs like the duckling-proxy by defining a proxy in
1033 .Pa ~/.config/telescope/config :
1034 .Bd -literal -offset indent
1035 proxy http via "gemini://127.0.0.1:1965"
1036 proxy https via "gemini://127.0.0.1:1965"
1041 without any configuration
1042 .Bd -literal -offset indent
1043 telescope -c /dev/null
1047 .%B XDG Base Directory Specification
1048 .%U https://specifications.freedesktop.org/basedir-spec/latest/
1050 .Sh ACKNOWLEDGEMENTS
1052 .Dq Trust, but verify (where appropriate)
1053 TOFU scheme was firstly suggested by thfr:
1054 .Lk gemini://thfr.info/gemini/modified-trust-verify.gmi .
1059 program was written by
1060 .An Omar Polo Aq Mt op@omarpolo.com .
1063 assumes a UTF-8 environment and doesn't try to cope with other encodings.
1064 This can cause strange rendering issues if you're lucky, or possibly
1065 weird thing happening depending on your locale and terminal emulator.
1067 The algorithm used for text-wrapping is naive and doesn't really work for
1068 languages that make heavily use of glyphs composed by multiple UNICODE
1071 There's no UI for out-of-band certificates validation.
