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, the
80 document type, the scroll offset and the URL.
81 When a client certificate is in use, a
85 The echoarea is usually the last line of the screen.
86 Messages are often showed there, and link addresses too.
87 The echoarea is also used to obtain input from the user.
92 are invoked, the minibuffer area grows to show possible completions.
96 .Dq Trust, but Verify Pq where appropriate
99 .Pq Dq Trust On First Use .
100 The idea is to define three level of verification for a certificate:
104 the server fingerprint does not match the stored value.
107 the server fingerprint matches the store one.
110 the fingerprint matches and has been verified out-of-band.
113 The trust level of the page is indicated in the modeline with the
118 level is enough, but where is appropriate users should be able to
119 verify out-of-band the certificate.
121 At the moment, there is no built-in support for an out-of-band
123 .Sh SUPPORTED PROTOCOLS
124 The following protocols are supported:
125 .Bl -tag -width gemini://
130 See about:about for a list of all these pages.
134 such as .gmi, .gemini, .txt, .md, .markdown, .diff or .patch, can be
135 viewed inside the application.
136 Types of local files are detected solely based on the file extension.
137 On some systems, such as
139 only files inside special directories
140 .Pq like Pa /tmp No or Pa ~/Downloads
143 Finger URLs are interpreted as follows:
146 the host is determined by the host name portion of the URL
148 if the user portion of the URL is provided, it's interpreted as the
149 user to finger, otherwise the path component will be used
152 .Lk finger://user@hostname
154 .Lk finger://hostname/user
155 are treated as the same URL.
157 Gemini is fully supported.
159 Gopher support is limited to items type 0, 1 and 7.
160 All text is assumed to be encoded in UTF-8 (superset of ASCII).
163 User-entered URLs, given as argument on the command line or entered
166 by default are intepreted with a simple heuristic:
169 if it's a proper absolute URL then use it as-is,
175 assume it's a file:// URL,
177 otherwise treat it like a hostname with protocol
179 .Pq gemini by default .
183 .Ic load-url-use-heuristic
184 can be used to disable the use of heuristics.
185 .Sh CONFIGURATION FILE
188 reads the configuration file at
189 .Pa ~/.config/telescope/config
191 .Pa ~/.telescope/config .
193 It's possible to load a custom configuration file using the
198 will also load a file called
202 is the name of the terminal type
203 .Pq i.e. the TERM environment variable ,
206 The format of the configuration file is fairly flexible.
207 The current line can be extended over multiple ones using a
210 Comments can be put anywhere in the file using a hash mark
212 and extend to the end of the current line, but backslashes can't be
213 used to extend comments over multiple lines.
215 The following constructs are available:
217 .It Ic bind Ar map Ar key Ar cmd
224 Valid values for map are
226 .Pq i.e. when the user is viewing a page
229 .Pq i.e. when the minibuffer has the focus.
231 follows the same syntax described in
232 .Sx DEFAULT KEY BINDINGS
233 and all the possible functions are listed in
234 .Sx INTERACTIVE COMMANDS .
235 .It Ic proxy Ar proto Ic via Ar url
238 as proxy for all URLs with
242 must be a Gemini URI without path, query and fragment component.
243 .It Ic set Ar opt No = Ar val
250 .Bl -tag -width twelveletters -compact
253 If greater than zero, save the session after the specified amount of
254 seconds after some events happened
255 .Pq new or closed tabs, visited a link ...
257 .It Ic default-protocol
259 The default protocol assumed for the
266 If true, don't wrap preformatted blocks.
270 The default download path.
275 If true, when the text of a link starts with an emoji followed by a
276 space, use that emoji as line prefix.
280 If true, enable colours.
283 is set, true otherwise.
286 If greater than zero, lines of text will be formatted in a way that
287 don't exceed the given number of columns.
289 .It Ic fringe-ignore-offset
291 If true, the fringe doesn't obey to
294 .It Ic hide-pre-blocks
296 If true, hide by default the body of the preformatted blocks.
299 can be used to toggle the visibility per-block.
300 .It Ic hide-pre-closing-line
302 If true, hide the closing line of preformatted blocks.
304 .It Ic hide-pre-context
306 If true, hide the start and end line of the preformatted blocks.
311 are true, preformatted blocks are irremediably hidden.
315 URL for the new tab page.
318 .It Ic load-url-use-heuristic
320 If false, don't use euristics to resolve the URLs.
321 Non-absolute URLs given as command line argument will be resolved as
324 will resolve as relative to the current URL.
326 .It Ic max-killed-tabs
328 The maximum number of closed tabs to keep track of, defaults to 10.
329 Must be a positive number; if zero, don't save closed tabs at all.
335 .It Ic default-search-engine
337 URL of the preferred search engine, used by the
340 If it's a Gemini URI, the user query will be appended as query,
341 replacing it if present.
342 If it's a Gopher URI, the user query will be sent as gopher search
344 No other URI scheme are allowed.
347 If tab-bar-show is -1 hide the tab bar permanently, if 0 show it
349 If 1, show the bar only when there is more than one tab.
353 If true, set the terminal title to the page title.
356 .It Ic style Ar name Ar option
357 Change the styling of the element identified by
359 Multiple options may be specified within curly braces.
360 Valid style identifiers are:
361 .Bl -tag -width line.download.ongoing -compact -offset Ds
363 the area outside the lines in the body of the page.
366 .It line.compl.current
367 the current completion.
369 text in the *Help* buffer.
370 .It line.download.ongoing
372 .It line.download.done
374 .It line.download.info
375 informational text in the *Downloads* buffer.
378 lines draw after the end of a buffer.
390 the heading of a preformatted block.
392 the content of a preformatted block.
394 the closing line of a preformatted block.
404 the non-focused tabs.
411 .It Ic attr Ar prefix Oo Ar line Oo Ar trail Oc Oc
412 Sets the text attributes.
413 If only one value is given,
417 default to that; if two values are given then
421 Each attribute is a comma-separated list of keywords:
422 .Bl -tag -width underline -compact -offset Ds
426 best highlighting mode for the terminal.
430 reverses background/foreground colors.
432 makes the text blinking.
436 extra bright or bold.
439 Only the style identifiers with the
441 prefix accept up to three attributes.
442 The other will only use the first one given.
443 .It Ic bg Ar prefix Oo Ar line Oo Ar trail Oc Oc
444 Sets the background color.
445 Follows the same behaviour as
447 regarding the optional parameters.
448 The colour is one of black, red, green, yellow, blue,
449 magenta, cyan and white; colour0 to colour255
450 .Pq or color0 to color255
451 from the 256-colour set;
452 default for the default colour.
453 .It Ic fg Ar prefix Oo Ar line Oo Ar trail Oc Oc
454 Sets the foreground color.
457 .It Ic prefix Ar prfx Op Ar cont
458 Sets the prefix for the current line type to
462 as the prefix for the continuation lines
463 .Pq i.e. when a long line gets wrapped.
466 is not given its value will be the same of
470 .Sh DEFAULT KEY BINDINGS
471 The default key bindings are very similar to GNU Emacs, but care has
472 been taken to include also bindings familiar for
477 In the following examples, C-x means Control-x, M-x means Meta-x,
478 where the Meta key may be either a special key on the keyboard or the
479 ALT key; otherwise ESC followed by the key X works as well, and C-M-x
480 means to press the key X together with both Control and Meta.
482 Keys are usually a single character, like
486 but some special keys are accepted as well.
488 .Bl -tag -width 16m -offset indent -compact
498 Previous page/Page up
518 Depends on the configuration of the terminal emulator; usually shift
521 .Ss GNU Emacs-like keys
522 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
536 move-beginning-of-line
554 execute-extended-command
598 .Ss Xr vi 1 Ns -like keys
599 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
613 move-beginning-of-line
653 execute-extended-command
656 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
666 move-beginning-of-line
692 .Ss Neither Emacs nor vi specific
693 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
725 .Ss Minibuffer-specific keys
726 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
728 mini-complete-and-exit
736 mini-delete-backward-char
738 mini-delete-backward-char
740 mini-delete-backward-char
752 move-beginning-of-line
756 move-beginning-of-line
762 mini-previous-history-element
764 mini-next-history-element
774 insert-current-candidate
780 .Sh INTERACTIVE COMMANDS
781 Follows the documentation for the interactive commands.
782 These commands can be bound to a key or executed with
783 .Ic execute-extended-command .
784 .Ss Movement commands
785 .Bl -tag -width execute-extended-command -compact
787 Move point one character backward.
788 .It Ic backward-paragraph
789 Move point one paragraph backward.
790 .It Ic beginning-of-buffer
791 Move point to the beginning of the buffer.
793 Move point to the end of the buffer.
795 Move point one character forward.
796 .It Ic forward-paragraph
797 Move point one paragraph forward.
798 .It Ic insert-current-candidate
799 Copy the current selection text as minibuffer input.
800 .It Ic move-beginning-of-line
801 Move point at the beginning of the current (visual) line.
802 .It Ic move-end-of-line
803 Move point at the end of the current (visual) line.
805 Move point to the next link.
806 .It Ic next-completion
807 Select the next completion.
809 Move point to the next heading.
811 Move point to the next (visual) line, in the same column if possible.
812 .It Ic previous-button
813 Move point to the previous link.
814 .It Ic previous-completion
815 Select the previous completion.
816 .It Ic previous-heading
817 Move point to the previous heading.
819 Move point to the previous (visual) line.
821 .Ss Bookmark-related commands
822 .Bl -tag -width execute-extended-command -compact
824 Save a page in the bookmark file.
825 It preloads the minibuffer with the current URL.
826 .It Ic list-bookmarks
827 Load the bookmarks page.
829 .Ss Client certificate-related commands
830 .Bl -tag -width execute-extended-command -compact
831 .It Ic client-certificate-info
832 Show the active client certificate.
833 .It Ic unload-certificate
834 Forget the certificate on this page.
835 .It Ic use-certificate
836 Use a certificate for the current page.
838 .Ss Tab-related commands
839 .Bl -tag -width execute-extended-command -compact
841 Close the current tab.
842 .It Ic tab-close-other
843 Close all tabs but the current one.
845 Move the current tab after the next one, wrapping around if
848 Move the current tab before the previous one, wrapping around if needed.
852 Focus next tab, wrapping around eventually.
854 Focus the previous tab, wrapping around eventually.
856 Switch to a tab using the minibuffer.
857 .It Ic tab-undo-close
858 Re-open the most recently closed tab, if any.
861 .Bl -tag -width execute-extended-command -compact
866 .It Ic dec-fill-column
867 Decrement fill-column by two.
868 .It Ic execute-extended-command
869 Execute an internal command.
871 Go to the home directory.
872 The home directory is assumed to be the first path component in the
875 If not found, loads the root directory.
876 .It Ic kill-telescope
879 .It Ic inc-fill-column
880 Increment fill-column by two.
882 Select and visit a link using the minibuffer.
883 .It Ic load-current-url
884 Edit the current URL.
887 Use the same heuristic as the URLs given as a command-line argument,
889 .Ic load-url-use-heuristic
890 option is unsed, in which case the URL is resolved using the current
893 Go forward in the page history.
895 Toggle olivetti mode (i.e. horizontal centering of the lines of the
898 Select the other window.
900 Go backward in the page history.
902 Follow link at point, or toggle the visibility of the following
903 preformatted block if called when the cursor is on the heading of the block.
904 .It Ic push-button-new-tab
905 Follow link at point in a new tab.
907 Redraw the screen, useful if some background program messed up the
910 Reload the current page.
911 .It Ic reply-last-input
912 Reply the last input request.
914 Go to the root directory.
916 Search using the preferred search engine.
918 Scroll down by one visual page.
919 .It Ic scroll-line-down
920 Scroll down by one line.
921 .It Ic scroll-line-up
922 Scroll up by one line.
924 Scroll up by one visual page.
925 .It Ic suspend-telescope
930 Jump to a line using the minibuffer.
932 Jump to a heading using the minibuffer.
934 Toggle side window with help about available keys and their associated
936 .It Ic toggle-pre-wrap
937 Toggle the wrapping of preformatted blocks.
939 Go up one level in the path hierarchy.
941 Save the current buffer to the disk.
943 .Ss Minibuffer commands
944 .Bl -tag -width execute-extended-command -compact
946 Abort the current minibuffer action.
947 .It Ic mini-complete-and-exit
948 Complete the current minibuffer action.
949 .It Ic mini-delete-backward-char
950 Delete the character before the point.
951 .It Ic mini-delete-char
952 Delete the character after the point.
953 .It Ic mini-goto-beginning
954 Select the first completion, if any.
956 Select the last completion, if any.
957 .It Ic mini-kill-line
958 Delete from point until the end of the line.
959 .It Ic mini-kill-whole-line
960 Delete the whole line.
961 .It Ic mini-next-history-element
962 Load the previous history element.
963 .It Ic mini-previous-history-element
964 Load the next history element.
967 The following aliases are available during
968 .Ic execute-extended-command :
969 .Bl -tag -width 16m -compact
978 .It Ic q No and Ic wq
986 is started, it inspects the following environment variables:
987 .Bl -tag -width NO_COLORS
989 The user's login directory.
991 To decide whether to use colors or not.
992 The content of the variable doesn't matter.
994 The user's terminal name.
995 .It Ev XDG_CACHE_HOME , Ev XDG_CONFIG_HOME , Ev XDG_DATA_HOME
996 If defined can alter the default location of the files used.
1001 follows the XDG Base Directory Specification.
1004 exists, XDG is ignored and all the files are stored inside it.
1006 .Ev XDG_CACHE_HOME ,
1010 can further alter the location of these files.
1012 .Bl -tag -width Ds -compact
1013 .It Pa ~/.config/telescope/config
1014 Default configuration file.
1015 .It Pa ~/.config/telescope/certs.conf
1016 URLs to client certificate mappings.
1017 .It Pa ~/.local/share/telescope/pages/about_*.gmi
1018 Overrides for built-in about: pages.
1019 .It Pa ~/.local/share/telescope/bookmarks.gmi
1021 .It Pa ~/.local/share/telescope/certs/
1022 Directory where client certificates
1025 .It Pa ~/.local/share/telescope/known_hosts
1026 Hash of the certificates for all the known hosts.
1027 Each line contains three fields: hostname with optional port number,
1028 hash of the certificate and a numeric flag.
1029 .It Pa ~/.cache/telescope/lock
1030 Lock file used to prevent multiple instance of
1032 from running at the same time.
1033 .It Pa ~/.cache/telescope/session
1034 The list of tabs from the last session.
1037 It's possible to browse
1039 .Pq i.e. simple websites
1040 by using programs like the duckling-proxy by defining a proxy in
1041 .Pa ~/.config/telescope/config :
1042 .Bd -literal -offset indent
1043 proxy http via "gemini://127.0.0.1:1965"
1044 proxy https via "gemini://127.0.0.1:1965"
1049 without any configuration
1050 .Bd -literal -offset indent
1051 $ telescope -c /dev/null
1054 .Xr telescope-identity 1
1057 .%B XDG Base Directory Specification
1058 .%U https://specifications.freedesktop.org/basedir-spec/latest/
1060 .Sh ACKNOWLEDGEMENTS
1062 .Dq Trust, but verify (where appropriate)
1063 TOFU scheme was firstly suggested by thfr:
1064 .Lk gemini://thfr.info/gemini/modified-trust-verify.gmi .
1069 program was written by
1070 .An Omar Polo Aq Mt op@omarpolo.com .
1073 assumes a UTF-8 environment and doesn't try to cope with other encodings.
1074 This can cause strange rendering issues if you're lucky, or possibly
1075 weird thing happening depending on your locale and terminal emulator.
1077 There's no UI for out-of-band certificates validation.
