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: October 8 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/.config/telescope/config
45 Display version and usage.
48 Only check the configuration file for validity.
55 from writing files to the disk and to acquire the lock, allowing to
56 run multiple instances at the same time.
58 still loads the session file and the custom about pages.
59 .It Fl v , Fl -version
64 interface is divided into four areas: the tabline, the body, the
65 modeline and the echoarea/minibuffer.
67 The tabline is always at the top of the screen and displays the tabs
68 separated by a vertical line.
69 When there are more tabs than the size of the window allow to display,
74 are shown at the start/end of the tabline to indicate that there are
75 more tabs in that direction.
77 The body occupies the majority of the visible area.
78 It contains the current page and optionally a side window.
80 The modeline is the second to last row of the screen.
81 It shows some information about the page: a spinner when the page is
82 loading, the trust level, the document type, the scroll offset and the
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, with the exception of client-certificates.
159 Gopher support is limited to items type 0, 1 and 7.
160 All text is assumed to be encoded in UTF-8 (or ASCII).
163 User-entered URLs, given as argument on the command line or entered
166 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 assume it's a Gemini URL.
179 .Sh CONFIGURATION FILE
182 reads the configuration file at
183 .Pa ~/.config/telescope/config
185 .Pa ~/.telescope/config .
187 It's possible to load a custom configuration file using the
192 will also load a file called
196 is the name of the terminal type
197 .Pq i.e. the TERM environment variable ,
200 The format of the configuration file is fairly flexible.
201 The current line can be extended over multiple ones using a
204 Comments can be put anywhere in the file using a hash mark
206 and extend to the end of the current line, but backslashes can't be
207 used to extend comments over multiple lines.
209 The following constructs are available:
211 .It Ic bind Ar map Ar key Ar cmd
218 Valid values for map are
220 .Pq i.e. when the user is viewing a page
223 .Pq i.e. when the minibuffer has the focus.
225 follows the same syntax described in
226 .Sx DEFAULT KEY BINDINGS
227 and all the possible functions are listed in
228 .Sx INTERACTIVE COMMANDS .
229 .It Ic proxy Ar proto Ic via Ar url
232 as proxy for all URLs with
236 must be a Gemini URI without path, query and fragment component.
237 .It Ic set Ar opt No = Ar val
244 .Bl -tag -width twelveletters -compact
247 If greater than zero, save the session after the specified amount of
248 seconds after some events happens
249 .Pq new or closed tabs, visited a link ...
253 If nonzero, don't wrap preformatted blocks.
257 The default download path.
262 If nonzero, when the text of a link starts with an emoji followed by a
263 space, use that emoji as line prefix.
267 If nonzero, enable colours.
273 If greater than zero, lines of text will be formatted in a way that
274 don't exceed the given number of columns.
278 If nonzero, hide by default the body of the preformatted blocks.
281 can be used to toggle the visibility per-block.
282 .It hide-pre-closing-line
284 If nonzero, hide the closing line of preformatted blocks.
288 If nonzero, hide the start and end line of the preformatted blocks.
289 If both hide-pre-context and hide-pre-blocks are nonzero, preformatted
290 blocks are irremediably hidden.
294 URL for the new tab page.
304 If nonzero, set the terminal title to the page title.
308 If tab-bar-show is -1 hide the tab bar permanently, if 0 show it
310 If it's 1, show the bar only when there is more than one tab.
313 .It Ic style Ar name Ar option
314 Change the styling of the element identified by
316 Multiple options may be specified within curly braces.
317 Valid style identifiers are:
318 .Bl -tag -width line.download.ongoing -compact -offset Ds
320 the area outside the lines in the body of the page.
323 .It line.compl.current
324 the current completion.
326 text in the *Help* buffer.
327 .It line.download.ongoing
329 .It line.download.done
331 .It line.download.info
332 informational text in the *Downloads* buffer.
344 the heading of a preformatted block.
346 the content of a preformatted block.
348 the closing line of a preformatted block.
358 the non-focused tabs.
365 .It Ic attr Ar prefix Oo Ar line Oo Ar trail Oc Oc
366 Sets the text attributes.
367 If only one value is given,
371 default to that; if two values are given then
375 Each attribute is a comma-separated list of keywords:
376 .Bl -tag -width underline -compact -offset Ds
380 best highlighting mode for the terminal.
384 reverses background/foreground colors.
386 makes the text blinking.
390 extra bright or bold.
393 Only the style identifiers with the
395 prefix accept up to three attributes.
396 The other will only use the first one given.
397 .It Ic bg Ar prefix Oo Ar line Oo Ar trail Oc Oc
398 Sets the background color.
399 Follows the same behaviour as
401 regarding the optional parameters.
402 The colour is one of black, red, green, yellow, blue,
403 magenta, cyan and white; colour0 to colour255
404 .Pq or color0 to color255
405 from the 256-colour set;
406 default for the default colour.
407 .It Ic fg Ar prefix Oo Ar line Oo Ar trail Oc Oc
408 Sets the foreground color.
411 .It Ic prefix Ar prfx Op Ar cont
412 Sets the prefix for the current line type to
416 as the prefix for the continuation lines
417 .Pq i.e. when a long line gets wrapped.
420 is not given its value will be the same of
424 .Sh DEFAULT KEY BINDINGS
425 The default key bindings are very similar to GNU Emacs, but care has
426 been taken to include also bindings familiar for
431 In the following examples, C-x means Control-x, M-x means Meta-x,
432 where the Meta key may be either a special key on the keyboard or the
433 ALT key; otherwise ESC followed by the key X works as well, and C-M-x
434 means to press the key X together with both Control and Meta.
436 Keys are usually a single character, like
440 but some special keys are accepted as well.
442 .Bl -tag -width 16m -offset indent -compact
452 Previous page/Page up
472 Depends on the configuration of the terminal emulator; usually shift
475 .Ss GNU Emacs-like keys
476 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
490 move-beginning-of-line
506 execute-extended-command
550 .Ss Xr vi 1 Ns -like keys
551 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
565 move-beginning-of-line
597 execute-extended-command
600 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
610 move-beginning-of-line
634 .Ss Neither Emacs nor vi specific
635 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
663 .Ss Minibuffer-specific keys
664 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
666 mini-complete-and-exit
674 mini-delete-backward-char
676 mini-delete-backward-char
678 mini-delete-backward-char
690 move-beginning-of-line
694 move-beginning-of-line
698 mini-previous-history-element
700 mini-next-history-element
710 insert-current-candidate
716 .Sh INTERACTIVE COMMANDS
717 Follows the documentation for the interactive commands.
718 These commands can be bound to a key or executed with
719 .Ic execute-extended-command .
720 .Ss Movement commands
721 .Bl -tag -width execute-extended-command -compact
723 Move point one character backward.
724 .It Ic backward-paragraph
725 Move point one paragraph backward.
726 .It Ic beginning-of-buffer
727 Move point to the beginning of the buffer.
729 Move point to the end of the buffer.
731 Move point one character forward.
732 .It Ic forward-paragraph
733 Move point one paragraph forward.
734 .It Ic insert-current-candidate
735 Copy the current selection text as minibuffer input.
736 .It Ic move-beginning-of-line
737 Move point at the beginning of the current (visual) line.
738 .It Ic move-end-of-line
739 Move point at the end of the current (visual) line.
741 Move point to the next link.
742 .It Ic next-completion
743 Select the next completion.
745 Move point to the next heading.
747 Move point to the next (visual) line, in the same column if possible.
748 .It Ic previous-button
749 Move point to the previous link.
750 .It Ic previous-completion
751 Select the previous completion.
752 .It Ic previous-heading
753 Move point to the previous heading.
755 Move point to the previous (visual) line.
757 .Ss Bookmark-related commands
758 .Bl -tag -width execute-extended-command -compact
760 Save a page in the bookmark file.
761 It preloads the minibuffer with the current URL.
762 .It Ic list-bookmarks
763 Load the bookmarks page.
765 .Ss Tab-related commands
766 .Bl -tag -width execute-extended-command -compact
768 Close the current tab.
769 .It Ic tab-close-other
770 Close all tabs but the current one.
772 Move the current tab after the next one, wrapping around if
775 Move the current tab before the previous one, wrapping around if needed.
779 Focus next tab, wrapping around eventually.
781 Focus the previous tab, wrapping around eventually.
783 Switch to a tab using the minibuffer.
786 .Bl -tag -width execute-extended-command -compact
789 .It Ic dec-fill-column
790 Decrement fill-column by two.
791 .It Ic execute-extended-command
792 Execute an internal command.
793 .It Ic kill-telescope
796 .It Ic inc-fill-column
797 Increment fill-column by two.
799 Select and visit a link using the minibuffer.
800 .It Ic load-current-url
801 Edit the current URL.
805 Go forward in the page history.
807 Toggle olivetti mode (i.e. horizontal centering of the lines of the
810 Select the other window.
812 Go backward in the page history.
814 Follow link at point, or toggle the visibility of the following
815 preformatted block if called when the cursor is on the heading of the block.
816 .It Ic push-button-new-tab
817 Follow link at point in a new tab.
819 Redraw the screen, useful if some background program messed up the
822 Reload the current page.
824 Scroll down by one visual page.
825 .It Ic scroll-line-down
826 Scroll down by one line.
827 .It Ic scroll-line-up
828 Scroll up by one line.
830 Scroll up by one visual page.
831 .It Ic suspend-telescope
836 Jump to a line using the minibuffer.
838 Jump to a heading using the minibuffer.
840 Toggle side window with help about available keys and their associated
842 .It Ic toggle-pre-wrap
843 Toggle the wrapping of preformatted blocks.
845 .Ss Minibuffer commands
846 .Bl -tag -width execute-extended-command -compact
848 Abort the current minibuffer action.
849 .It Ic mini-complete-and-exit
850 Complete the current minibuffer action.
851 .It Ic mini-delete-backward-char
852 Delete the character before the point.
853 .It Ic mini-delete-char
854 Delete the character after the point.
855 .It Ic mini-goto-beginning
856 Select the first completion, if any.
858 Select the last completion, if any.
859 .It Ic mini-kill-line
860 Delete from point until the end of the line.
861 .It Ic mini-next-history-element
862 Load the previous history element.
863 .It Ic mini-previous-history-element
864 Load the next history element.
867 The following aliases are available during
868 .Ic execute-extended-command :
869 .Bl -tag -width 16m -compact
876 .It Ic q No and Ic wq
882 is started, it inspects the following environment variables:
883 .Bl -tag -width NO_COLORS
885 The user's login directory.
887 To decide whether to use colors or not.
888 The content of the variable doesn't matter.
890 The user's terminal name.
891 .It Ev XDG_CACHE_HOME , Ev XDG_CONFIG_HOME , Ev XDG_DATA_HOME
892 If defined can alter the default location of the files used.
897 follows the XDG Base Directory Specification.
900 exists, XDG is ignored and all the files are stored inside it.
906 can further alter the location of these files.
908 .Bl -tag -width Ds -compact
909 .It Pa ~/.config/telescope/config
910 Default configuration file.
911 .It Pa ~/.local/share/telescope/pages/about_*.gmi
912 Overrides for built-in about: pages.
913 .It Pa ~/.local/share/telescope/bookmarks.gmi
915 .It Pa ~/.local/share/telescope/known_hosts
916 Hash of the certificates for all the known hosts.
917 Each line contains three fields: hostname with optional port number,
918 hash of the certificate and a numeric flag.
919 .It Pa ~/.cache/telescope/lock
920 Lock file used to prevent multiple instance of
922 from running at the same time.
923 .It Pa ~/.cache/telescope/session
924 The list of tabs from the last session.
925 Every line identifies a tab and contains three space-separated fields:
926 the full URL, a comma-separated list of attributes and the cached
930 and loaded during startup.
933 It's possible to browse
935 .Pq i.e. simple websites
936 by using programs like the duckling-proxy by defining a proxy in
937 .Pa ~/.config/telescope/config :
938 .Bd -literal -offset indent
939 proxy http via "gemini://127.0.0.1:1965"
940 proxy https via "gemini://127.0.0.1:1965"
945 without any configuration
946 .Bd -literal -offset indent
947 telescope -c /dev/null
951 .%B XDG Base Directory Specification
952 .%U https://specifications.freedesktop.org/basedir-spec/latest/
958 program was written by
959 .An Omar Polo Aq Mt op@omarpolo.com .
961 There's no UI for out-of-band certificates validation.
