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: March 28 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
115 has native support for querying finger servers.
116 While this is easily doable using the
118 utility, given that finger URLs do appear on occasion in the
119 gopherspace and in the geminispace, it's nice to be able to open them
123 interprets finger:// URLs as follows:
126 the host is determined by the host name portion of the URL
128 if the user portion of the URL is provided, it's interpreted as the
129 user to finger, otherwise the path component will be used
132 .Lk finger://user@hostname
134 .Lk finger://hostname/user
137 Gopher support is limited to items type 0, 1 and 7.
138 All text is assumed to be encoded in UTF-8 (or ASCII).
139 .Sh DEFAULT KEY BINDINGS
140 The default key bindings are very similar to GNU Emacs, but care has
141 been taken to include also bindings familiar for
146 In the following examples, C-x means Control-x, M-x means Meta-x,
147 where the Meta key may be either a special key on the keyboard or the
148 ALT key; otherwise ESC followed by the key X works as well, and C-M-x
149 means to press the key X together with both Control and Meta.
151 Keys are usually a single character, like
155 but some special keys are accepted as well.
157 .Bl -tag -width 16m -offset indent -compact
167 Previous page/Page up
187 Depends on the configuration of the terminal emulator; usually shift
190 .Ss GNU Emacs-like keys
191 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
205 move-beginning-of-line
221 execute-extended-command
265 .Ss Xr vi 1 Ns -like keys
266 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
280 move-beginning-of-line
312 execute-extended-command
315 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
325 move-beginning-of-line
349 .Ss Neither Emacs nor vi specific
350 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
374 .Ss Minibuffer-specific keys
375 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
377 mini-complete-and-exit
385 mini-delete-backward-char
387 mini-delete-backward-char
389 mini-delete-backward-char
401 move-beginning-of-line
405 move-beginning-of-line
409 mini-previous-history-element
411 mini-next-history-element
421 insert-current-candidate
427 .Sh INTERACTIVE COMMANDS
428 Follows the documentation for the interactive commands.
429 These commands can be bound to a key or executed with
430 .Ic execute-extended-command .
431 .Ss Movement commands
432 .Bl -tag -width execute-extended-command -compact
434 Move point one character backward.
435 .It Ic backward-paragraph
436 Move point one paragraph backward.
437 .It Ic beginning-of-buffer
438 Move point to the beginning of the buffer.
440 Move point to the end of the buffer.
442 Move point one character forward.
443 .It Ic forward-paragraph
444 Move point one paragraph forward.
445 .It Ic insert-current-candidate
446 Copy the current selection text as minibuffer input.
447 .It Ic move-beginning-of-line
448 Move point at the beginning of the current (visual) line.
449 .It Ic move-end-of-line
450 Move point at the end of the current (visual) line.
452 Move point to the next link.
453 .It Ic next-completion
454 Select the next completion.
456 Move point to the next heading.
458 Move point to the next (visual) line, in the same column if possible.
459 .It Ic previous-button
460 Move point to the previous link.
461 .It Ic previous-completion
462 Select the previous completion.
463 .It Ic previous-heading
464 Move point to the previous heading.
466 Move point to the previous (visual) line.
468 .Ss Bookmark-related commands
469 .Bl -tag -width execute-extended-command -compact
471 Save a page in the bookmark file.
472 It preloads the minibuffer with the current URL.
473 .It Ic list-bookmarks
474 Load the bookmarks page.
476 .Ss Tab-related commands
477 .Bl -tag -width execute-extended-command -compact
479 Close the current tab.
480 .It Ic tab-close-other
481 Close all tabs but the current one.
483 Move the current tab after the next one, wrapping around if
486 Move the current tab before the previous one, wrapping around if needed.
490 Focus next tab, wrapping around eventually.
492 Focus the previous tab, wrapping around eventually.
494 Switch to a tab using the minibuffer.
497 .Bl -tag -width execute-extended-command -compact
500 .It Ic dec-fill-column
501 Decrement fill-column by two.
502 .It Ic execute-extended-command
503 Execute an internal command.
504 .It Ic kill-telescope
507 .It Ic inc-fill-column
508 Increment fill-column by two.
510 Select and visit a link using the minibuffer.
511 .It Ic load-current-url
512 Edit the current URL.
516 Go forward in the page history.
518 Toggle olivetti mode (i.e. horizontal centering of the lines of the
521 Select the other window.
523 Go backward in the page history.
525 Follow link at point, or toggle the visibility of the following
526 preformatted block if called when the cursor is on the heading of the block.
527 .It Ic push-button-new-tab
528 Follow link at point in a new tab.
530 Redraw the screen, useful if some background program messed up the
533 Reload the current page.
535 Scroll down by one visual page.
536 .It Ic scroll-line-down
537 Scroll down by one line.
538 .It Ic scroll-line-up
539 Scroll up by one line.
541 Scroll up by one visual page.
542 .It Ic suspend-telescope
547 Jump to a line using the minibuffer.
549 Jump to a heading using the minibuffer.
551 Toggle side window with help about available keys and their associated
553 .It Ic toggle-pre-wrap
554 Toggle the wrapping of preformatted blocks.
556 .Ss Minibuffer commands
557 .Bl -tag -width execute-extended-command -compact
559 Abort the current minibuffer action.
560 .It Ic mini-complete-and-exit
561 Complete the current minibuffer action.
562 .It Ic mini-delete-backward-char
563 Delete the character before the point.
564 .It Ic mini-delete-char
565 Delete the character after the point.
566 .It Ic mini-goto-beginning
567 Select the first completion, if any.
569 Select the last completion, if any.
570 .It Ic mini-kill-line
571 Delete from point until the end of the line.
572 .It Ic mini-next-history-element
573 Load the previous history element.
574 .It Ic mini-previous-history-element
575 Load the next history element.
578 The following aliases are available during
579 .Ic execute-extended-command :
580 .Bl -tag -width 16m -compact
587 .It Ic q No and Ic wq
590 .Sh CONFIGURATION FILE
593 reads the configuration file at
594 .Pa ~/.telescope/config
595 or the one given with the
600 will also load a file called
604 is the name of the terminal type
605 .Pq i.e. the TERM environment variable ,
608 The format of the configuration file is fairly flexible.
609 The current line can be extended over multiple ones using a
612 Comments can be put anywhere in the file using a hash mark
614 and extend to the end of the current line, but backslashes can't be
615 used to extend comments over multiple lines.
617 The following constructs are available:
619 .It Ic bind Ar map Ar key Ar cmd
626 Valid values for map are
628 .Pq i.e. when the user is viewing a page
631 .Pq i.e. when the minibuffer has the focus.
633 follows the same syntax described in
634 .Sx DEFAULT KEY BINDINGS
635 and all the possible functions are listed in
636 .Sx INTERACTIVE COMMANDS .
637 .It Ic proxy Ar proto Ic via Ar url
640 as proxy for all URLs with
644 must be a Gemini URI without path, query and fragment component.
645 .It Ic set Ar opt No = Ar val
652 .Bl -tag -width twelveletters -compact
655 If nonzero, don't wrap preformatted blocks.
659 If nonzero, when the text of a link starts with an emoji followed by a
660 space, use that emoji as line prefix.
664 If nonzero, enable colours.
670 If greater than zero, lines of text will be formatted in a way that
671 don't exceed the given number of columns.
675 If nonzero, hide by default the body of the preformatted blocks.
678 can be used to toggle the visibility per-block.
679 .It hide-pre-closing-line
681 If nonzero, hide the closing line of preformatted blocks.
685 If nonzero, hide the start and end line of the preformatted blocks.
686 If both hide-pre-context and hide-pre-blocks are nonzero, preformatted
687 blocks are irremediably hidden.
691 URL for the new tab page.
701 If nonzero, set the terminal title to the page title.
704 .It Ic style Ar name Ar option
705 Change the styling of the element identified by
707 Multiple options may be specified within curly braces.
708 Valid style identifiers are:
709 .Bl -tag -width line.compl.current -compact -offset Ds
711 the area outside the lines in the body of the page.
714 .It line.compl.current
715 the current completion.
717 text in the *Help* buffer.
729 the heading of a preformatted block.
731 the content of a preformatted block.
733 the closing line of a preformatted block.
741 the non-focused tabs.
748 .It Ic attr Ar prefix Oo Ar line Oo Ar trail Oc Oc
749 Sets the text attributes.
750 If only one value is given,
754 default to that; if two values are given then
758 Each attribute is a comma-separated list of keywords:
759 .Bl -tag -width underline -compact -offset Ds
763 best highlighting mode for the terminal.
767 reverses background/foreground colors.
769 makes the text blinking.
773 extra bright or bold.
776 Only the style identifiers with the
778 prefix accept up to three attributes.
779 The other will only use the first one given.
780 .It Ic bg Ar prefix Oo Ar line Oo Ar trail Oc Oc
781 Sets the background color.
782 Follows the same behaviour as
784 regarding the optional parameters.
785 The colour is one of black, red, green, yellow, blue,
786 magenta, cyan and white; colour0 to colour255
787 .Pq or color0 to color255
788 from the 256-colour set;
789 default for the default colour.
790 .It Ic fg Ar prefix Oo Ar line Oo Ar trail Oc Oc
791 Sets the foreground color.
794 .It Ic prefix Ar prfx Op Ar cont
795 Sets the prefix for the current line type to
799 as the prefix for the continuation lines
800 .Pq i.e. when a long line gets wrapped.
803 is not given its value will be the same of
810 is started, it inspects the following environment variables:
811 .Bl -tag -width NO_COLORS
813 The user's login directory.
815 To decide whether to use colors or not.
816 The content of the variable doesn't matter.
818 The user's terminal name.
821 .Bl -tag -width Ds -compact
822 .It Pa ~/.telescope/bookmarks.gmi
824 .It Pa ~/.telescope/config
825 Default configuration file.
826 .It Pa ~/.telescope/known_hosts
827 Hash of the certificates for all the known hosts.
828 Each line contains three fields: hostname with optional port number,
829 hash of the certificate and a numeric flag.
830 .It Pa ~/.telescope/lock
831 Lock file used to prevent multiple instance of
833 from running at the same time.
834 .It Pa ~/.telescope/pages/about_*.gmi
835 Overrides for built-in about: pages.
836 .It Pa ~/.telescope/session
837 The list of tabs from the last session.
838 Every line identifies a tab and contains three space-separated fields:
839 the full URL, a comma-separated list of attributes and the cached
843 and loaded during startup.
846 It's possible to browse
848 .Pq i.e. simple websites
849 by using programs like the duckling-proxy by defining a proxy in
850 .Pa ~/.telescope/config :
851 .Bd -literal -offset indent
852 proxy http via "gemini://127.0.0.1:1965"
853 proxy https via "gemini://127.0.0.1:1965"
858 without any configuration
859 .Bd -literal -offset indent
860 telescope -c /dev/null
866 program was written by
867 .An Omar Polo Aq Mt op@omarpolo.com .
869 There's no UI for out-of-band certificates validation.
