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 23 2024$
19 .Nd multi-protocol browser
29 is a browser that supports the Finger, Gemini and Gopher protocols.
31 features tabs, a minibuffer, interactive completions, bookmarks and
34 The arguments are as follows:
35 .Bl -tag -width xxxxxxxxxxxxx
37 Specify an alternative configuration file.
39 .Pa ~/.config/telescope/config
42 Display version, usage and exit.
45 Only check the configuration file for validity.
52 from writing files to the disk and to acquire the lock, allowing to
53 run multiple instances at the same time.
55 still loads the session file and the custom about pages.
56 .It Fl v , Fl -version
57 Display version and exit.
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, whether a client certificate is in use, a
80 warning indicator for faulty Gemini servers, document type, the
81 scroll offset and the URL.
82 When a client certificate is in use, a
85 Some Gemini servers have buggy TLS handling but some information might
87 This information could be truncated.
88 In those circumstances, a
92 The echoarea is usually the last line of the screen.
93 Messages are often showed there, and link addresses too.
94 The echoarea is also used to obtain input from the user.
99 are invoked, the minibuffer area grows to show possible completions.
103 .Dq Trust, but Verify Pq where appropriate
106 .Pq Dq Trust On First Use .
107 The idea is to define three level of verification for a certificate:
111 the server fingerprint does not match the stored value.
114 the server fingerprint matches the store one.
117 the fingerprint matches and has been verified out-of-band.
120 The trust level of the page is indicated in the modeline with the
125 level is enough, but where is appropriate users should be able to
126 verify out-of-band the certificate.
128 At the moment, there is no built-in support for an out-of-band
130 .Sh SUPPORTED PROTOCOLS
131 The following protocols are supported:
132 .Bl -tag -width gemini://
137 See about:about for a list of all these pages.
141 such as .gmi, .gemini, .txt, .md, .markdown, .diff or .patch, can be
142 viewed inside the application.
143 Types of local files are detected solely based on the file extension.
144 On some systems, such as
146 only files inside special directories
147 .Pq like Pa /tmp No or Pa ~/Downloads
150 Finger URLs are interpreted as follows:
153 the host is determined by the host name portion of the URL
155 if the user portion of the URL is provided, it's interpreted as the
156 user to finger, otherwise the path component will be used
159 .Lk finger://user@hostname
161 .Lk finger://hostname/user
162 are treated as the same URL.
164 Gemini is fully supported.
166 Gopher support is limited to items type 0, 1 and 7.
167 All text is assumed to be encoded in UTF-8 (superset of ASCII).
170 User-entered URLs, given as argument on the command line or entered
173 by default are interpreted with a simple heuristic:
176 if it's a proper absolute URL then use it as-is,
182 assume it's a file:// URL,
184 otherwise treat it like a hostname with protocol
186 .Pq gemini by default .
190 .Ic load-url-use-heuristic
191 can be used to disable the use of heuristics.
192 .Sh MIME-TYPE HANDLING
193 Beyond the supported protocols which
195 already understands, mime-types which
197 cannot display can be opened using a
202 will look for one of the following mailcap files in the following order:
204 .Bl -tag -width Ds -compact
207 .It Pa /usr/etc/mailcap
208 .It Pa /usr/local/etc/mailcap
211 A default mailcap entry is always defined by
215 as a fallback for mime-types not defined through a mailcap file, or if no
216 mailcap file was found.
218 Refer to RFC 1524 for more information about the structure and format of this
222 currently only supports a small subset of this standard, honouring only the
227 .Sh CONFIGURATION FILE
230 reads the configuration file at
231 .Pa ~/.config/telescope/config
233 .Pa ~/.telescope/config .
235 It's possible to load a custom configuration file using the
240 will also load a file called
244 is the name of the terminal type
245 .Pq i.e. the TERM environment variable ,
248 The format of the configuration file is fairly flexible.
249 The current line can be extended over multiple ones using a
252 Comments can be put anywhere in the file using a hash mark
254 and extend to the end of the current line, but backslashes can't be
255 used to extend comments over multiple lines.
257 The following constructs are available:
259 .It Ic bind Ar map Ar key Ar cmd
266 Valid values for map are
268 .Pq i.e. when the user is viewing a page
271 .Pq i.e. when the minibuffer has the focus.
273 follows the same syntax described in
274 .Sx DEFAULT KEY BINDINGS
275 and all the possible functions are listed in
276 .Sx INTERACTIVE COMMANDS .
277 .It Ic proxy Ar proto Ic via Ar url
280 as proxy for all URLs with
284 must be a Gemini URI without path, query and fragment component.
285 .It Ic set Ar opt No = Ar val
292 .Bl -tag -width twelveletters -compact
295 If greater than zero, save the session after the specified amount of
296 seconds after some events happened
297 .Pq new or closed tabs, visited a link ...
299 .It Ic default-protocol
301 The default protocol assumed for the
306 .It Ic default-search-engine
308 URL of the preferred search engine, used by the
311 If it's a Gemini URI, the user query will be appended as query,
312 replacing it if present.
313 If it's a Gopher URI, the user query will be sent as gopher search
315 No other URI scheme are allowed.
318 If true, don't wrap preformatted blocks.
322 The default download path.
327 If true, when the text of a link starts with an emoji followed by a
328 space, use that emoji as line prefix.
332 If true, enable colours.
335 is set, true otherwise.
338 If greater than zero, lines of text will be formatted in a way that
339 don't exceed the given number of columns.
341 .It Ic fringe-ignore-offset
343 If true, the fringe doesn't obey to
346 .It Ic hide-pre-blocks
348 If true, hide by default the body of the preformatted blocks.
351 can be used to toggle the visibility per-block.
352 .It Ic hide-pre-closing-line
354 If true, hide the closing line of preformatted blocks.
356 .It Ic hide-pre-context
358 If true, hide the start and end line of the preformatted blocks.
363 are true, preformatted blocks are irremediably hidden.
367 URL for the new tab page.
370 .It Ic load-url-use-heuristic
372 If false, don't use heuristics to resolve the URLs.
373 Non-absolute URLs given as command line argument will be resolved as
376 will resolve as relative to the current URL.
378 .It Ic max-killed-tabs
380 The maximum number of closed tabs to keep track of, defaults to 10.
381 Must be a positive number; if zero, don't save closed tabs at all.
389 If tab-bar-show is -1 hide the tab bar permanently, if 0 show it
391 If 1, show the bar only when there is more than one tab.
395 If true, set the terminal title to the page title.
398 .It Ic style Ar name Ar option
399 Change the styling of the element identified by
401 Multiple options may be specified within curly braces.
402 Valid style identifiers are:
403 .Bl -tag -width line.download.ongoing -compact -offset Ds
405 the area outside the lines in the body of the page.
408 .It line.compl.current
409 the current completion.
411 text in the *Help* buffer.
412 .It line.download.ongoing
414 .It line.download.done
416 .It line.download.info
417 informational text in the *Downloads* buffer.
420 lines draw after the end of a buffer.
432 the heading of a preformatted block.
434 the content of a preformatted block.
436 the closing line of a preformatted block.
446 the non-focused tabs.
453 .It Ic attr Ar prefix Oo Ar line Oo Ar trail Oc Oc
454 Sets the text attributes.
455 If only one value is given,
459 default to that; if two values are given then
463 Each attribute is a comma-separated list of keywords:
464 .Bl -tag -width underline -compact -offset Ds
468 best highlighting mode for the terminal.
472 reverses background/foreground colors.
474 makes the text blinking.
478 extra bright or bold.
481 Only the style identifiers with the
483 prefix accept up to three attributes.
484 The other will only use the first one given.
485 .It Ic bg Ar prefix Oo Ar line Oo Ar trail Oc Oc
486 Sets the background color.
487 Follows the same behaviour as
489 regarding the optional parameters.
490 The colour is one of black, red, green, yellow, blue,
491 magenta, cyan and white; colour0 to colour255
492 .Pq or color0 to color255
493 from the 256-colour set;
494 default for the default colour.
495 .It Ic fg Ar prefix Oo Ar line Oo Ar trail Oc Oc
496 Sets the foreground color.
499 .It Ic prefix Ar prfx Op Ar cont
500 Sets the prefix for the current line type to
504 as the prefix for the continuation lines
505 .Pq i.e. when a long line gets wrapped.
508 is not given its value will be the same of
512 .Sh DEFAULT KEY BINDINGS
513 The default key bindings are very similar to GNU Emacs, but care has
514 been taken to include also bindings familiar for
519 In the following examples, C-x means Control-x, M-x means Meta-x,
520 where the Meta key may be either a special key on the keyboard or the
521 ALT key; otherwise ESC followed by the key X works as well, and C-M-x
522 means to press the key X together with both Control and Meta.
524 Keys are usually a single character, like
528 but some special keys are accepted as well.
530 .Bl -tag -width 16m -offset indent -compact
540 Previous page/Page up
560 Depends on the configuration of the terminal emulator; usually shift
563 .Ss GNU Emacs-like keys
564 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
578 move-beginning-of-line
596 execute-extended-command
640 .Ss Xr vi 1 Ns -like keys
641 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
655 move-beginning-of-line
695 execute-extended-command
698 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
708 move-beginning-of-line
734 .Ss Neither Emacs nor vi specific
735 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
767 .Ss Minibuffer-specific keys
768 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
770 mini-complete-and-exit
778 mini-delete-backward-char
780 mini-delete-backward-char
782 mini-delete-backward-char
796 move-beginning-of-line
800 move-beginning-of-line
806 mini-previous-history-element
808 mini-next-history-element
818 insert-current-candidate
824 .Sh INTERACTIVE COMMANDS
825 Follows the documentation for the interactive commands.
826 These commands can be bound to a key or executed with
827 .Ic execute-extended-command .
828 .Ss Movement commands
829 .Bl -tag -width execute-extended-command -compact
831 Move point one character backward.
832 .It Ic backward-paragraph
833 Move point one paragraph backward.
834 .It Ic beginning-of-buffer
835 Move point to the beginning of the buffer.
837 Move point to the end of the buffer.
839 Move point one character forward.
840 .It Ic forward-paragraph
841 Move point one paragraph forward.
842 .It Ic insert-current-candidate
843 Copy the current selection text as minibuffer input.
844 .It Ic move-beginning-of-line
845 Move point at the beginning of the current (visual) line.
846 .It Ic move-end-of-line
847 Move point at the end of the current (visual) line.
849 Move point to the next link.
850 .It Ic next-completion
851 Select the next completion.
853 Move point to the next heading.
855 Move point to the next (visual) line, in the same column if possible.
856 .It Ic previous-button
857 Move point to the previous link.
858 .It Ic previous-completion
859 Select the previous completion.
860 .It Ic previous-heading
861 Move point to the previous heading.
863 Move point to the previous (visual) line.
865 .Ss Bookmark-related commands
866 .Bl -tag -width execute-extended-command -compact
868 Save a page in the bookmark file.
869 It preloads the minibuffer with the current URL.
870 .It Ic list-bookmarks
871 Load the bookmarks page.
873 .Ss Client certificate-related commands
874 .Bl -tag -width execute-extended-command -compact
875 .It Ic client-certificate-info
876 Show the active client certificate.
877 .It Ic unload-certificate
878 Forget the certificate on this page.
879 .It Ic use-certificate
880 Use a certificate for the current page.
882 .Ss Tab-related commands
883 .Bl -tag -width execute-extended-command -compact
885 Close the current tab.
886 .It Ic tab-close-other
887 Close all tabs but the current one.
889 Move the current tab after the next one, wrapping around if
892 Move the current tab before the previous one, wrapping around if needed.
896 Focus next tab, wrapping around eventually.
898 Focus the previous tab, wrapping around eventually.
900 Switch to a tab using the minibuffer.
901 .It Ic tab-undo-close
902 Re-open the most recently closed tab, if any.
905 .Bl -tag -width execute-extended-command -compact
910 .It Ic dec-fill-column
911 Decrement fill-column by two.
912 .It Ic execute-extended-command
913 Execute an internal command.
915 Go to the home directory.
916 The home directory is assumed to be the first path component in the
919 If not found, loads the root directory.
920 .It Ic kill-telescope
923 .It Ic inc-fill-column
924 Increment fill-column by two.
926 Select and visit a link using the minibuffer.
927 .It Ic load-current-url
928 Edit the current URL.
931 Use the same heuristic as the URLs given as a command-line argument,
933 .Ic load-url-use-heuristic
934 option is unsed, in which case the URL is resolved using the current
937 Go forward in the page history.
939 Toggle olivetti mode (i.e. horizontal centering of the lines of the
942 Select the other window.
944 Go backward in the page history.
946 Follow link at point, or toggle the visibility of the following
947 preformatted block if called when the cursor is on the heading of the block.
948 .It Ic push-button-new-tab
949 Follow link at point in a new tab.
951 Redraw the screen, useful if some background program messed up the
954 Reload the current page.
955 .It Ic reply-last-input
956 Reply the last input request.
958 Go to the root directory.
960 Search using the preferred search engine.
962 Scroll down by one visual page.
963 .It Ic scroll-line-down
964 Scroll down by one line.
965 .It Ic scroll-line-up
966 Scroll up by one line.
968 Scroll up by one visual page.
969 .It Ic suspend-telescope
974 Jump to a line using the minibuffer.
976 Jump to a heading using the minibuffer.
978 Toggle side window with help about available keys and their associated
980 .It Ic toggle-pre-wrap
981 Toggle the wrapping of preformatted blocks.
982 .It Ic toggle-styling
983 Toggle the styling of the page.
984 This remains in effect until toggled again.
986 Go up one level in the path hierarchy.
988 Save the current buffer to the disk.
990 .Ss Minibuffer commands
991 .Bl -tag -width execute-extended-command -compact
993 Abort the current minibuffer action.
994 .It Ic mini-complete-and-exit
995 Complete the current minibuffer action.
996 .It Ic mini-delete-backward-char
997 Delete the character before the point.
998 .It Ic mini-delete-char
999 Delete the character after the point.
1000 .It Ic mini-edit-external
1001 Edit the minibuffer contents with an editor.
1002 .It Ic mini-goto-beginning
1003 Select the first completion, if any.
1004 .It Ic mini-goto-end
1005 Select the last completion, if any.
1006 .It Ic mini-kill-line
1007 Delete from point until the end of the line.
1008 .It Ic mini-kill-whole-line
1009 Delete the whole line.
1010 .It Ic mini-next-history-element
1011 Load the previous history element.
1012 .It Ic mini-previous-history-element
1013 Load the next history element.
1016 The following aliases are available during
1017 .Ic execute-extended-command :
1018 .Bl -tag -width 16m -compact
1027 .It Ic q No and Ic wq
1035 is started, it inspects the following environment variables:
1036 .Bl -tag -width NO_COLORS
1038 The user's login directory.
1040 To decide whether to use colors or not.
1041 The content of the variable doesn't matter.
1043 The user's terminal name.
1044 .It Ev VISUAL , Ev EDITOR
1045 The editor spawned by the
1046 .Ic mini-edit-external
1050 the standard text editor is used.
1051 .It Ev XDG_CACHE_HOME , Ev XDG_CONFIG_HOME , Ev XDG_DATA_HOME
1052 If defined can alter the default location of the files used.
1057 follows the XDG Base Directory Specification.
1060 exists, XDG is ignored and all the files are stored inside it.
1062 .Ev XDG_CACHE_HOME ,
1066 can further alter the location of these files.
1068 .Bl -tag -width Ds -compact
1069 .It Pa ~/.config/telescope/config
1070 Default configuration file.
1071 .It Pa ~/.config/telescope/certs.conf
1072 URLs to client certificate mappings.
1073 .It Pa ~/.local/share/telescope/pages/about_*.gmi
1074 Overrides for built-in about: pages.
1075 .It Pa ~/.local/share/telescope/bookmarks.gmi
1077 .It Pa ~/.local/share/telescope/certs/
1078 Directory where client certificates
1081 .It Pa ~/.local/share/telescope/known_hosts
1082 Hash of the certificates for all the known hosts.
1083 Each line contains three fields: hostname with optional port number,
1084 hash of the certificate and a numeric flag.
1085 .It Pa ~/.cache/telescope/lock
1086 Lock file used to prevent multiple instance of
1088 from running at the same time.
1089 .It Pa ~/.cache/telescope/session
1090 The list of tabs from the last session.
1093 It's possible to browse
1095 .Pq i.e. simple websites
1096 by using programs like the duckling-proxy by defining a proxy in
1097 .Pa ~/.config/telescope/config :
1098 .Bd -literal -offset indent
1099 proxy http via "gemini://127.0.0.1:1965"
1100 proxy https via "gemini://127.0.0.1:1965"
1105 without any configuration
1106 .Bd -literal -offset indent
1107 $ telescope -c /dev/null
1110 .Xr telescope-identity 1
1114 .%B XDG Base Directory Specification
1115 .%U https://specifications.freedesktop.org/basedir-spec/latest/
1117 .Sh ACKNOWLEDGEMENTS
1119 .Dq Trust, but verify (where appropriate)
1120 TOFU scheme was firstly suggested by thfr:
1121 .Lk gemini://thfr.info/gemini/modified-trust-verify.gmi .
1126 program was written by
1127 .An Omar Polo Aq Mt op@omarpolo.com .
1130 assumes a UTF-8 environment and doesn't try to cope with other encodings.
1131 This can cause strange rendering issues if you're lucky, or possibly
1132 weird thing happening depending on your locale and terminal emulator.
1134 There's no UI for out-of-band certificates validation.
