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$
29 is an interactive browser for the Gemini protocol.
30 It is able to process text/gemini and more in general every text/* file.
32 also features tabs, a minibuffer, bookmarks and out-of-band TOFU
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
83 and navigate through them.
87 .Dq Trust, but Verify Pq where appropriate
90 .Pq Dq Trust On First Use .
91 The idea is to define three level of verification for a certificate:
95 the server fingerprint does NOT match the stored value.
98 the server fingerprint matches the store one.
101 the fingerprint matches and has been verified out-of-band.
104 The trust level of the page is indicated in the modeline with the
109 level is enough, but where is appropriate users should be able to
110 verify out-of-band the certificate.
112 At the moment, there is no built-in support for an out-of-band
114 .Sh DEFAULT KEY BINDINGS
115 The default key bindings are very similar to GNU Emacs, but care has
116 been taken to include also bindings familiar for
121 In the following examples, C-x means Control-x, M-x means Meta-x,
122 where the Meta key may be either a special key on the keyboard or the
123 ALT key; otherwise ESC followed by the key X works as well, and C-M-x
124 means to press the key X together with both Control and Meta.
126 Keys are usually a single character, like
130 but some special keys are accepted as well.
132 .Bl -tag -width 16m -offset indent -compact
142 Previous page/Page up
162 Depends on the configuration of the terminal emulator.
163 Usually is shift tab though.
165 .Ss GNU Emacs-like keys
166 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
180 move-beginning-of-line
196 execute-extended-command
240 .Ss Xr vi 1 Ns -like keys
241 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
255 move-beginning-of-line
287 execute-extended-command
290 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
300 move-beginning-of-line
324 .Ss Neither Emacs nor vi specific
325 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
349 .Ss Minibuffer-specific keys
350 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
352 mini-complete-and-exit
360 mini-delete-backward-char
362 mini-delete-backward-char
364 mini-delete-backward-char
376 move-beginning-of-line
380 move-beginning-of-line
384 mini-previous-history-element
386 mini-next-history-element
396 insert-current-candidate
402 .Sh INTERACTIVE COMMANDS
403 Follows the documentation for the interactive commands.
404 These commands can be bound to a key or executed with
405 .Ic execute-extended-command .
406 .Ss Movement commands
407 .Bl -tag -width execute-extended-command -compact
409 Move point one character backward.
410 .It Ic backward-paragraph
411 Move point one paragraph backward.
412 .It Ic beginning-of-buffer
413 Move point to the beginning of the buffer.
415 Move point to the end of the buffer.
417 Move point one character forward.
418 .It Ic forward-paragraph
419 Move point one paragraph forward.
420 .It Ic insert-current-candidate
421 Copy the current selection text as minibuffer input.
422 .It Ic move-beginning-of-line
423 Move point at the beginning of the current (visual) line.
424 .It Ic move-end-of-line
425 Move point at the end of the current (visual) line.
427 Move point to the next link.
428 .It Ic next-completion
429 Select the next completion.
431 Move point to the next heading.
433 Move point to the next (visual) line, in the same column if possible.
434 .It Ic previous-button
435 Move point to the previous link.
436 .It Ic previous-completion
437 Select the previous completion.
438 .It Ic previous-heading
439 Move point to the previous heading.
441 Move point to the previous (visual) line.
443 .Ss Bookmark-related commands
444 .Bl -tag -width execute-extended-command -compact
446 Save a page in the bookmark file.
447 It preloads the minibuffer with the current URL.
448 .It Ic list-bookmarks
449 Load the bookmarks page.
451 .Ss Tab-related commands
452 .Bl -tag -width execute-extended-command -compact
454 Close the current tab.
455 .It Ic tab-close-other
456 Close all tabs but the current one.
458 Move the current tab after the next one, wrapping around if
461 Move the current tab before the previous one, wrapping around if needed.
465 Focus next tab, wrapping around eventually.
467 Focus the previous tab, wrapping around eventually.
469 Switch to a tab using the minibuffer.
472 .Bl -tag -width execute-extended-command -compact
475 .It Ic dec-fill-column
476 Decrement fill-column by two.
477 .It Ic execute-extended-command
478 Execute an internal command.
479 .It Ic kill-telescope
482 .It Ic inc-fill-column
483 Increment fill-column by two.
485 Select and visit a link using the minibuffer.
486 .It Ic load-current-url
487 Edit the current URL.
491 Go forward in the page history.
493 Toggle olivetti mode (i.e. horizontal centering of the lines of the
496 Select the other window.
498 Go backward in the page history.
500 Follow link at point, or toggle the visibility of the following
501 preformatted block if called when the cursor is on the heading of the block.
502 .It Ic push-button-new-tab
503 Follow link at point in a new tab.
505 Redraw the screen, useful if some background program messed up the
508 Reload the current page.
510 Scroll down by one visual page.
511 .It Ic scroll-line-down
512 Scroll down by one line.
513 .It Ic scroll-line-up
514 Scroll up by one line.
516 Scroll up by one visual page.
517 .It Ic suspend-telescope
522 Jump to a line using the minibuffer.
524 Jump to a heading using the minibuffer.
526 Toggle side window with help about available keys and their associated
528 .It Ic toggle-pre-wrap
529 Toggle the wrapping of preformatted blocks.
531 .Ss Minibuffer commands
532 .Bl -tag -width execute-extended-command -compact
534 Abort the current minibuffer action.
535 .It Ic mini-complete-and-exit
536 Complete the current minibuffer action.
537 .It Ic mini-delete-backward-char
538 Delete the character before the point.
539 .It Ic mini-delete-char
540 Delete the character after the point.
541 .It Ic mini-goto-beginning
542 Select the first completion, if any.
544 Select the last completion, if any.
545 .It Ic mini-kill-line
546 Delete from point until the end of the line.
547 .It Ic mini-next-history-element
548 Load the previous history element.
549 .It Ic mini-previous-history-element
550 Load the next history element.
553 The following aliases are available during
554 .Ic execute-extended-command :
555 .Bl -tag -width 16m -compact
562 .It Ic q No and Ic wq
565 .Sh CONFIGURATION FILE
568 reads the configuration file at
569 .Pa ~/.telescope/config
570 or the one given with the
575 will also load a file called
579 is the name of the terminal type
580 .Pq i.e. the TERM environment variable ,
583 The format of the configuration file is fairly flexible.
584 The current line can be extended over multiple ones using a
587 Comments can be put anywhere in the file using a hash mark
589 and extend to the end of the current line, but backslashes can't be
590 used to extend comments over multiple lines.
592 The following constructs are available:
594 .It Ic bind Ar map Ar key Ar cmd
601 Valid values for map are
603 .Pq i.e. when the user is viewing a page
606 .Pq i.e. when the minibuffer has the focus.
608 follows the same syntax described in
609 .Sx DEFAULT KEY BINDINGS
610 and all the possible functions are listed in
611 .Sx INTERACTIVE COMMANDS .
612 .It Ic proxy Ar proto Ic via Ar url
615 as proxy for all URLs with
619 must be a Gemini URI without path, query and fragment component.
620 .It Ic set Ar opt No = Ar val
627 .Bl -tag -width twelveletters -compact
630 If nonzero, don't wrap preformatted blocks.
634 If nonzero, when the text of a link starts with an emoji followed by a
635 space, use that emoji as line prefix.
639 If nonzero, enable colours.
645 If greater than zero, lines of text will be formatted in a way that
646 don't exceed the given number of columns.
650 If nonzero, hide by default the body of the preformatted blocks.
653 can be used to toggle the visibility per-block.
654 .It hide-pre-closing-line
656 If nonzero, hide the closing line of preformatted blocks.
660 If nonzero, hide the start and end line of the preformatted blocks.
661 If both hide-pre-context and hide-pre-blocks are nonzero, preformatted
662 blocks are irremediably hidden.
666 URL for the new tab page.
676 If nonzero, set the terminal title to the page title.
679 .It Ic style Ar name Ar option
680 Change the styling of the element identified by
682 Multiple options may be specified within curly braces.
683 Valid style identifiers are:
684 .Bl -tag -width line.compl.current -compact -offset Ds
686 the area outside the lines in the body of the page.
689 .It line.compl.current
690 the current completion.
692 text in the *Help* buffer.
704 the heading of a preformatted block.
706 the content of a preformatted block.
708 the closing line of a preformatted block.
716 the non-focused tabs.
723 .It Ic attr Ar prefix Oo Ar line Oo Ar trail Oc Oc
724 Sets the text attributes.
725 If only one value is given,
729 default to that; if two values are given then
733 Each attribute is a comma-separated list of keywords:
734 .Bl -tag -width underline -compact -offset Ds
738 best highlighting mode for the terminal.
742 reverses background/foreground colors.
744 makes the text blinking.
748 extra bright or bold.
751 Only the style identifiers with the
753 prefix accept up to three attributes.
754 The other will only use the first one given.
755 .It Ic bg Ar prefix Oo Ar line Oo Ar trail Oc Oc
756 Sets the background color.
757 Follows the same behaviour as
759 regarding the optional parameters.
760 The colour is one of black, red, green, yellow, blue,
761 magenta, cyan and white; colour0 to colour255
762 .Pq or color0 to color255
763 from the 256-colour set;
764 default for the default colour.
765 .It Ic fg Ar prefix Oo Ar line Oo Ar trail Oc Oc
766 Sets the foreground color.
769 .It Ic prefix Ar prfx Op Ar cont
770 Sets the prefix for the current line type to
774 as the prefix for the continuation lines
775 .Pq i.e. when a long line gets wrapped.
778 is not given its value will be the same of
785 is started, it inspects the following environment variables:
786 .Bl -tag -width NO_COLORS
788 The user's login directory.
790 To decide whether to use colors or not.
791 The content of the variable doesn't matter.
793 The user's terminal name.
796 .Bl -tag -width Ds -compact
797 .It Pa ~/.telescope/bookmarks.gmi
799 .It Pa ~/.telescope/config
800 Default configuration file.
801 .It Pa ~/.telescope/known_hosts
802 Hash of the certificates for all the known hosts.
803 Each line contains three fields: hostname with optional port number,
804 hash of the certificate and a numeric flag.
805 .It Pa ~/.telescope/lock
806 Lock file used to prevent multiple instance of
808 from running at the same time.
809 .It Pa ~/.telescope/pages/about_*.gmi
810 Overrides for built-in about: pages.
811 .It Pa ~/.telescope/session
812 The list of tabs from the last session.
813 Every line identifies a tab and contains three space-separated fields:
814 the full URL, a comma-separated list of attributes and the cached
818 and loaded during startup.
821 It's possible to browse
823 .Pq i.e. simple websites
824 by using programs like the duckling-proxy by defining a proxy in
825 .Pa ~/.telescope/config :
826 .Bd -literal -offset indent
827 proxy http via "gemini://127.0.0.1:1965"
828 proxy https via "gemini://127.0.0.1:1965"
833 without any configuration
834 .Bd -literal -offset indent
835 telescope -c /dev/null
841 program was written by
842 .An Omar Polo Aq Mt op@omarpolo.com .
844 There's no UI for out-of-band certificates validation.
