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: August 14 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/.telescope/config
45 Display version and usage.
48 Only check the configuration file for validity.
49 .It Fl v , Fl -version
54 interface is divided into four areas: the tabline, the body, the
55 modeline and the echoarea/minibuffer.
57 The tabline is always at the top of the screen and displays the tabs
58 separated by a vertical line.
59 When there are more tabs than the size of the window allow to display,
64 are shown at the start/end of the tabline to indicate that there are
65 more tabs in that direction.
67 The body occupies the majority of the visible area.
68 It contains the current page and optionally a side window.
70 The modeline is the second to last row of the screen.
71 It shows some information about the page: a spinner when the page is
72 loading, the trust level, the document type, the scroll offset and the
75 The echoarea is usually the last line of the screen.
76 Messages are often showed there, and link addresses too.
77 The echoarea is also used to obtain input from the user.
82 are invoked, the minibuffer area grows to show possible completions.
86 .Dq Trust, but Verify Pq where appropriate
89 .Pq Dq Trust On First Use .
90 The idea is to define three level of verification for a certificate:
94 the server fingerprint does NOT match the stored value.
97 the server fingerprint matches the store one.
100 the fingerprint matches and has been verified out-of-band.
103 The trust level of the page is indicated in the modeline with the
108 level is enough, but where is appropriate users should be able to
109 verify out-of-band the certificate.
111 At the moment, there is no built-in support for an out-of-band
113 .Sh SUPPORTED PROTOCOLS
114 The following protocols are supported:
115 .Bl -tag -width gemini://
120 See about:about for a list of all these pages.
124 such as .gmi, .gemini, .txt, .md, .markdown, .diff or .patch, can be
125 viewed inside the application.
126 Types of local files are detected solely based on the file extension.
127 On some systems, such as
129 only files inside special directories
130 .Pq like Pa /tmp No or Pa ~/Downloads
133 Finger URLs are interpreted as follows:
136 the host is determined by the host name portion of the URL
138 if the user portion of the URL is provided, it's interpreted as the
139 user to finger, otherwise the path component will be used
142 .Lk finger://user@hostname
144 .Lk finger://hostname/user
145 are treated as the same URL.
147 Gemini is fully supported, with the exception of client-certificates.
149 Gopher support is limited to items type 0, 1 and 7.
150 All text is assumed to be encoded in UTF-8 (or ASCII).
152 .Sh DEFAULT KEY BINDINGS
153 The default key bindings are very similar to GNU Emacs, but care has
154 been taken to include also bindings familiar for
159 In the following examples, C-x means Control-x, M-x means Meta-x,
160 where the Meta key may be either a special key on the keyboard or the
161 ALT key; otherwise ESC followed by the key X works as well, and C-M-x
162 means to press the key X together with both Control and Meta.
164 Keys are usually a single character, like
168 but some special keys are accepted as well.
170 .Bl -tag -width 16m -offset indent -compact
180 Previous page/Page up
200 Depends on the configuration of the terminal emulator; usually shift
203 .Ss GNU Emacs-like keys
204 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
218 move-beginning-of-line
234 execute-extended-command
278 .Ss Xr vi 1 Ns -like keys
279 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
293 move-beginning-of-line
325 execute-extended-command
328 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
338 move-beginning-of-line
362 .Ss Neither Emacs nor vi specific
363 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
387 .Ss Minibuffer-specific keys
388 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
390 mini-complete-and-exit
398 mini-delete-backward-char
400 mini-delete-backward-char
402 mini-delete-backward-char
414 move-beginning-of-line
418 move-beginning-of-line
422 mini-previous-history-element
424 mini-next-history-element
434 insert-current-candidate
440 .Sh INTERACTIVE COMMANDS
441 Follows the documentation for the interactive commands.
442 These commands can be bound to a key or executed with
443 .Ic execute-extended-command .
444 .Ss Movement commands
445 .Bl -tag -width execute-extended-command -compact
447 Move point one character backward.
448 .It Ic backward-paragraph
449 Move point one paragraph backward.
450 .It Ic beginning-of-buffer
451 Move point to the beginning of the buffer.
453 Move point to the end of the buffer.
455 Move point one character forward.
456 .It Ic forward-paragraph
457 Move point one paragraph forward.
458 .It Ic insert-current-candidate
459 Copy the current selection text as minibuffer input.
460 .It Ic move-beginning-of-line
461 Move point at the beginning of the current (visual) line.
462 .It Ic move-end-of-line
463 Move point at the end of the current (visual) line.
465 Move point to the next link.
466 .It Ic next-completion
467 Select the next completion.
469 Move point to the next heading.
471 Move point to the next (visual) line, in the same column if possible.
472 .It Ic previous-button
473 Move point to the previous link.
474 .It Ic previous-completion
475 Select the previous completion.
476 .It Ic previous-heading
477 Move point to the previous heading.
479 Move point to the previous (visual) line.
481 .Ss Bookmark-related commands
482 .Bl -tag -width execute-extended-command -compact
484 Save a page in the bookmark file.
485 It preloads the minibuffer with the current URL.
486 .It Ic list-bookmarks
487 Load the bookmarks page.
489 .Ss Tab-related commands
490 .Bl -tag -width execute-extended-command -compact
492 Close the current tab.
493 .It Ic tab-close-other
494 Close all tabs but the current one.
496 Move the current tab after the next one, wrapping around if
499 Move the current tab before the previous one, wrapping around if needed.
503 Focus next tab, wrapping around eventually.
505 Focus the previous tab, wrapping around eventually.
507 Switch to a tab using the minibuffer.
510 .Bl -tag -width execute-extended-command -compact
513 .It Ic dec-fill-column
514 Decrement fill-column by two.
515 .It Ic execute-extended-command
516 Execute an internal command.
517 .It Ic kill-telescope
520 .It Ic inc-fill-column
521 Increment fill-column by two.
523 Select and visit a link using the minibuffer.
524 .It Ic load-current-url
525 Edit the current URL.
529 Go forward in the page history.
531 Toggle olivetti mode (i.e. horizontal centering of the lines of the
534 Select the other window.
536 Go backward in the page history.
538 Follow link at point, or toggle the visibility of the following
539 preformatted block if called when the cursor is on the heading of the block.
540 .It Ic push-button-new-tab
541 Follow link at point in a new tab.
543 Redraw the screen, useful if some background program messed up the
546 Reload the current page.
548 Scroll down by one visual page.
549 .It Ic scroll-line-down
550 Scroll down by one line.
551 .It Ic scroll-line-up
552 Scroll up by one line.
554 Scroll up by one visual page.
555 .It Ic suspend-telescope
560 Jump to a line using the minibuffer.
562 Jump to a heading using the minibuffer.
564 Toggle side window with help about available keys and their associated
566 .It Ic toggle-pre-wrap
567 Toggle the wrapping of preformatted blocks.
569 .Ss Minibuffer commands
570 .Bl -tag -width execute-extended-command -compact
572 Abort the current minibuffer action.
573 .It Ic mini-complete-and-exit
574 Complete the current minibuffer action.
575 .It Ic mini-delete-backward-char
576 Delete the character before the point.
577 .It Ic mini-delete-char
578 Delete the character after the point.
579 .It Ic mini-goto-beginning
580 Select the first completion, if any.
582 Select the last completion, if any.
583 .It Ic mini-kill-line
584 Delete from point until the end of the line.
585 .It Ic mini-next-history-element
586 Load the previous history element.
587 .It Ic mini-previous-history-element
588 Load the next history element.
591 The following aliases are available during
592 .Ic execute-extended-command :
593 .Bl -tag -width 16m -compact
600 .It Ic q No and Ic wq
603 .Sh CONFIGURATION FILE
606 reads the configuration file at
607 .Pa ~/.telescope/config
608 or the one given with the
613 will also load a file called
617 is the name of the terminal type
618 .Pq i.e. the TERM environment variable ,
621 The format of the configuration file is fairly flexible.
622 The current line can be extended over multiple ones using a
625 Comments can be put anywhere in the file using a hash mark
627 and extend to the end of the current line, but backslashes can't be
628 used to extend comments over multiple lines.
630 The following constructs are available:
632 .It Ic bind Ar map Ar key Ar cmd
639 Valid values for map are
641 .Pq i.e. when the user is viewing a page
644 .Pq i.e. when the minibuffer has the focus.
646 follows the same syntax described in
647 .Sx DEFAULT KEY BINDINGS
648 and all the possible functions are listed in
649 .Sx INTERACTIVE COMMANDS .
650 .It Ic proxy Ar proto Ic via Ar url
653 as proxy for all URLs with
657 must be a Gemini URI without path, query and fragment component.
658 .It Ic set Ar opt No = Ar val
665 .Bl -tag -width twelveletters -compact
668 If greater than zero, save the session after the specified amount of
669 seconds after some events happens
670 .Pq new or closed tabs, visited a link ...
674 If nonzero, don't wrap preformatted blocks.
678 If nonzero, when the text of a link starts with an emoji followed by a
679 space, use that emoji as line prefix.
683 If nonzero, enable colours.
689 If greater than zero, lines of text will be formatted in a way that
690 don't exceed the given number of columns.
694 If nonzero, hide by default the body of the preformatted blocks.
697 can be used to toggle the visibility per-block.
698 .It hide-pre-closing-line
700 If nonzero, hide the closing line of preformatted blocks.
704 If nonzero, hide the start and end line of the preformatted blocks.
705 If both hide-pre-context and hide-pre-blocks are nonzero, preformatted
706 blocks are irremediably hidden.
710 URL for the new tab page.
720 If nonzero, set the terminal title to the page title.
723 .It Ic style Ar name Ar option
724 Change the styling of the element identified by
726 Multiple options may be specified within curly braces.
727 Valid style identifiers are:
728 .Bl -tag -width line.compl.current -compact -offset Ds
730 the area outside the lines in the body of the page.
733 .It line.compl.current
734 the current completion.
736 text in the *Help* buffer.
748 the heading of a preformatted block.
750 the content of a preformatted block.
752 the closing line of a preformatted block.
760 the non-focused tabs.
767 .It Ic attr Ar prefix Oo Ar line Oo Ar trail Oc Oc
768 Sets the text attributes.
769 If only one value is given,
773 default to that; if two values are given then
777 Each attribute is a comma-separated list of keywords:
778 .Bl -tag -width underline -compact -offset Ds
782 best highlighting mode for the terminal.
786 reverses background/foreground colors.
788 makes the text blinking.
792 extra bright or bold.
795 Only the style identifiers with the
797 prefix accept up to three attributes.
798 The other will only use the first one given.
799 .It Ic bg Ar prefix Oo Ar line Oo Ar trail Oc Oc
800 Sets the background color.
801 Follows the same behaviour as
803 regarding the optional parameters.
804 The colour is one of black, red, green, yellow, blue,
805 magenta, cyan and white; colour0 to colour255
806 .Pq or color0 to color255
807 from the 256-colour set;
808 default for the default colour.
809 .It Ic fg Ar prefix Oo Ar line Oo Ar trail Oc Oc
810 Sets the foreground color.
813 .It Ic prefix Ar prfx Op Ar cont
814 Sets the prefix for the current line type to
818 as the prefix for the continuation lines
819 .Pq i.e. when a long line gets wrapped.
822 is not given its value will be the same of
829 is started, it inspects the following environment variables:
830 .Bl -tag -width NO_COLORS
832 The user's login directory.
834 To decide whether to use colors or not.
835 The content of the variable doesn't matter.
837 The user's terminal name.
840 .Bl -tag -width Ds -compact
841 .It Pa ~/.telescope/bookmarks.gmi
843 .It Pa ~/.telescope/config
844 Default configuration file.
845 .It Pa ~/.telescope/known_hosts
846 Hash of the certificates for all the known hosts.
847 Each line contains three fields: hostname with optional port number,
848 hash of the certificate and a numeric flag.
849 .It Pa ~/.telescope/lock
850 Lock file used to prevent multiple instance of
852 from running at the same time.
853 .It Pa ~/.telescope/pages/about_*.gmi
854 Overrides for built-in about: pages.
855 .It Pa ~/.telescope/session
856 The list of tabs from the last session.
857 Every line identifies a tab and contains three space-separated fields:
858 the full URL, a comma-separated list of attributes and the cached
862 and loaded during startup.
865 It's possible to browse
867 .Pq i.e. simple websites
868 by using programs like the duckling-proxy by defining a proxy in
869 .Pa ~/.telescope/config :
870 .Bd -literal -offset indent
871 proxy http via "gemini://127.0.0.1:1965"
872 proxy https via "gemini://127.0.0.1:1965"
877 without any configuration
878 .Bd -literal -offset indent
879 telescope -c /dev/null
885 program was written by
886 .An Omar Polo Aq Mt op@omarpolo.com .
888 There's no UI for out-of-band certificates validation.
