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
113 .Sh DEFAULT KEY BINDINGS
114 The default key bindings are very similar to GNU Emacs, but care has
115 been taken to include also bindings familiar for
120 In the following examples, C-x means Control-x, M-x means Meta-x,
121 where the Meta key may be either a special key on the keyboard or the
122 ALT key; otherwise ESC followed by the key X works as well, and C-M-x
123 means to press the key X together with both Control and Meta.
125 Keys are usually a single character, like
129 but some special keys are accepted as well.
131 .Bl -tag -width 16m -offset indent -compact
141 Previous page/Page up
161 Depends on the configuration of the terminal emulator; usually shift
164 .Ss GNU Emacs-like keys
165 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
179 move-beginning-of-line
195 execute-extended-command
239 .Ss Xr vi 1 Ns -like keys
240 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
254 move-beginning-of-line
286 execute-extended-command
289 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
299 move-beginning-of-line
323 .Ss Neither Emacs nor vi specific
324 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
348 .Ss Minibuffer-specific keys
349 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
351 mini-complete-and-exit
359 mini-delete-backward-char
361 mini-delete-backward-char
363 mini-delete-backward-char
375 move-beginning-of-line
379 move-beginning-of-line
383 mini-previous-history-element
385 mini-next-history-element
395 insert-current-candidate
401 .Sh INTERACTIVE COMMANDS
402 Follows the documentation for the interactive commands.
403 These commands can be bound to a key or executed with
404 .Ic execute-extended-command .
405 .Ss Movement commands
406 .Bl -tag -width execute-extended-command -compact
408 Move point one character backward.
409 .It Ic backward-paragraph
410 Move point one paragraph backward.
411 .It Ic beginning-of-buffer
412 Move point to the beginning of the buffer.
414 Move point to the end of the buffer.
416 Move point one character forward.
417 .It Ic forward-paragraph
418 Move point one paragraph forward.
419 .It Ic insert-current-candidate
420 Copy the current selection text as minibuffer input.
421 .It Ic move-beginning-of-line
422 Move point at the beginning of the current (visual) line.
423 .It Ic move-end-of-line
424 Move point at the end of the current (visual) line.
426 Move point to the next link.
427 .It Ic next-completion
428 Select the next completion.
430 Move point to the next heading.
432 Move point to the next (visual) line, in the same column if possible.
433 .It Ic previous-button
434 Move point to the previous link.
435 .It Ic previous-completion
436 Select the previous completion.
437 .It Ic previous-heading
438 Move point to the previous heading.
440 Move point to the previous (visual) line.
442 .Ss Bookmark-related commands
443 .Bl -tag -width execute-extended-command -compact
445 Save a page in the bookmark file.
446 It preloads the minibuffer with the current URL.
447 .It Ic list-bookmarks
448 Load the bookmarks page.
450 .Ss Tab-related commands
451 .Bl -tag -width execute-extended-command -compact
453 Close the current tab.
454 .It Ic tab-close-other
455 Close all tabs but the current one.
457 Move the current tab after the next one, wrapping around if
460 Move the current tab before the previous one, wrapping around if needed.
464 Focus next tab, wrapping around eventually.
466 Focus the previous tab, wrapping around eventually.
468 Switch to a tab using the minibuffer.
471 .Bl -tag -width execute-extended-command -compact
474 .It Ic dec-fill-column
475 Decrement fill-column by two.
476 .It Ic execute-extended-command
477 Execute an internal command.
478 .It Ic kill-telescope
481 .It Ic inc-fill-column
482 Increment fill-column by two.
484 Select and visit a link using the minibuffer.
485 .It Ic load-current-url
486 Edit the current URL.
490 Go forward in the page history.
492 Toggle olivetti mode (i.e. horizontal centering of the lines of the
495 Select the other window.
497 Go backward in the page history.
499 Follow link at point, or toggle the visibility of the following
500 preformatted block if called when the cursor is on the heading of the block.
501 .It Ic push-button-new-tab
502 Follow link at point in a new tab.
504 Redraw the screen, useful if some background program messed up the
507 Reload the current page.
509 Scroll down by one visual page.
510 .It Ic scroll-line-down
511 Scroll down by one line.
512 .It Ic scroll-line-up
513 Scroll up by one line.
515 Scroll up by one visual page.
516 .It Ic suspend-telescope
521 Jump to a line using the minibuffer.
523 Jump to a heading using the minibuffer.
525 Toggle side window with help about available keys and their associated
527 .It Ic toggle-pre-wrap
528 Toggle the wrapping of preformatted blocks.
530 .Ss Minibuffer commands
531 .Bl -tag -width execute-extended-command -compact
533 Abort the current minibuffer action.
534 .It Ic mini-complete-and-exit
535 Complete the current minibuffer action.
536 .It Ic mini-delete-backward-char
537 Delete the character before the point.
538 .It Ic mini-delete-char
539 Delete the character after the point.
540 .It Ic mini-goto-beginning
541 Select the first completion, if any.
543 Select the last completion, if any.
544 .It Ic mini-kill-line
545 Delete from point until the end of the line.
546 .It Ic mini-next-history-element
547 Load the previous history element.
548 .It Ic mini-previous-history-element
549 Load the next history element.
552 The following aliases are available during
553 .Ic execute-extended-command :
554 .Bl -tag -width 16m -compact
561 .It Ic q No and Ic wq
564 .Sh CONFIGURATION FILE
567 reads the configuration file at
568 .Pa ~/.telescope/config
569 or the one given with the
574 will also load a file called
578 is the name of the terminal type
579 .Pq i.e. the TERM environment variable ,
582 The format of the configuration file is fairly flexible.
583 The current line can be extended over multiple ones using a
586 Comments can be put anywhere in the file using a hash mark
588 and extend to the end of the current line, but backslashes can't be
589 used to extend comments over multiple lines.
591 The following constructs are available:
593 .It Ic bind Ar map Ar key Ar cmd
600 Valid values for map are
602 .Pq i.e. when the user is viewing a page
605 .Pq i.e. when the minibuffer has the focus.
607 follows the same syntax described in
608 .Sx DEFAULT KEY BINDINGS
609 and all the possible functions are listed in
610 .Sx INTERACTIVE COMMANDS .
611 .It Ic proxy Ar proto Ic via Ar url
614 as proxy for all URLs with
618 must be a Gemini URI without path, query and fragment component.
619 .It Ic set Ar opt No = Ar val
626 .Bl -tag -width twelveletters -compact
629 If nonzero, don't wrap preformatted blocks.
633 If nonzero, when the text of a link starts with an emoji followed by a
634 space, use that emoji as line prefix.
638 If nonzero, enable colours.
644 If greater than zero, lines of text will be formatted in a way that
645 don't exceed the given number of columns.
649 If nonzero, hide by default the body of the preformatted blocks.
652 can be used to toggle the visibility per-block.
653 .It hide-pre-closing-line
655 If nonzero, hide the closing line of preformatted blocks.
659 If nonzero, hide the start and end line of the preformatted blocks.
660 If both hide-pre-context and hide-pre-blocks are nonzero, preformatted
661 blocks are irremediably hidden.
665 URL for the new tab page.
675 If nonzero, set the terminal title to the page title.
678 .It Ic style Ar name Ar option
679 Change the styling of the element identified by
681 Multiple options may be specified within curly braces.
682 Valid style identifiers are:
683 .Bl -tag -width line.compl.current -compact -offset Ds
685 the area outside the lines in the body of the page.
688 .It line.compl.current
689 the current completion.
691 text in the *Help* buffer.
703 the heading of a preformatted block.
705 the content of a preformatted block.
707 the closing line of a preformatted block.
715 the non-focused tabs.
722 .It Ic attr Ar prefix Oo Ar line Oo Ar trail Oc Oc
723 Sets the text attributes.
724 If only one value is given,
728 default to that; if two values are given then
732 Each attribute is a comma-separated list of keywords:
733 .Bl -tag -width underline -compact -offset Ds
737 best highlighting mode for the terminal.
741 reverses background/foreground colors.
743 makes the text blinking.
747 extra bright or bold.
750 Only the style identifiers with the
752 prefix accept up to three attributes.
753 The other will only use the first one given.
754 .It Ic bg Ar prefix Oo Ar line Oo Ar trail Oc Oc
755 Sets the background color.
756 Follows the same behaviour as
758 regarding the optional parameters.
759 The colour is one of black, red, green, yellow, blue,
760 magenta, cyan and white; colour0 to colour255
761 .Pq or color0 to color255
762 from the 256-colour set;
763 default for the default colour.
764 .It Ic fg Ar prefix Oo Ar line Oo Ar trail Oc Oc
765 Sets the foreground color.
768 .It Ic prefix Ar prfx Op Ar cont
769 Sets the prefix for the current line type to
773 as the prefix for the continuation lines
774 .Pq i.e. when a long line gets wrapped.
777 is not given its value will be the same of
784 is started, it inspects the following environment variables:
785 .Bl -tag -width NO_COLORS
787 The user's login directory.
789 To decide whether to use colors or not.
790 The content of the variable doesn't matter.
792 The user's terminal name.
795 .Bl -tag -width Ds -compact
796 .It Pa ~/.telescope/bookmarks.gmi
798 .It Pa ~/.telescope/config
799 Default configuration file.
800 .It Pa ~/.telescope/known_hosts
801 Hash of the certificates for all the known hosts.
802 Each line contains three fields: hostname with optional port number,
803 hash of the certificate and a numeric flag.
804 .It Pa ~/.telescope/lock
805 Lock file used to prevent multiple instance of
807 from running at the same time.
808 .It Pa ~/.telescope/pages/about_*.gmi
809 Overrides for built-in about: pages.
810 .It Pa ~/.telescope/session
811 The list of tabs from the last session.
812 Every line identifies a tab and contains three space-separated fields:
813 the full URL, a comma-separated list of attributes and the cached
817 and loaded during startup.
820 It's possible to browse
822 .Pq i.e. simple websites
823 by using programs like the duckling-proxy by defining a proxy in
824 .Pa ~/.telescope/config :
825 .Bd -literal -offset indent
826 proxy http via "gemini://127.0.0.1:1965"
827 proxy https via "gemini://127.0.0.1:1965"
832 without any configuration
833 .Bd -literal -offset indent
834 telescope -c /dev/null
840 program was written by
841 .An Omar Polo Aq Mt op@omarpolo.com .
843 There's no UI for out-of-band certificates validation.
