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, bookmarks and out-of-band TOFU verification.
34 The arguments are as follows:
35 .Bl -tag -width xxxxxxxxxxxxx
37 Show all available colors and exit.
39 Specify an alternative configuration file.
41 .Pa $HOME/.telescope/config
44 Display version and usage.
47 Only check the configuration file for validity.
48 .It Fl v , Fl -version
53 aims to use the "Trust, but Verify (where appropriate)" approach.
54 The idea is to define three level of verification for a certificate:
57 the server fingerprint does NOT match the stored value
59 the server fingerprint matches the store one
61 the fingerprint matches and has been verified out-of-band
66 level is enough, but where is appropriate users should be able to
67 verify out-of-band the certificate.
69 At the moment, there is no built-in support for an out-of-band
72 Known certificates are store in
73 .Pa ~/.telescope/known_hosts
74 with a format similar to the
78 Each line is a record and it's made up by three fields, separated by a
79 single space, according to the following format:
84 the hostname, optionally followed by a colon (":") and a port number.
86 is the hash of the certificate, as outputted by
87 .Xr tls_peer_cert_hash 3 .
90 0 means trusted, 1 verified.
92 .Sh DEFAULT KEY BINDINGS
93 The default key bindings are very similar to GNU Emacs, but care has
94 been taken to include also bindings familiar for
99 In the following examples, C-x means Control-x, M-x means Meta-x,
100 where the Meta key may be either a special key on the keyboard or the
101 ALT key; otherwise ESC followed by the key X works as well, and C-M-x
102 means to press the key X together with both Control and Meta.
104 Keys are usually a single character, like
108 but some special keys are accepted as well.
110 .Bl -tag -width 16m -offset indent -compact
120 Previous page/Page up
140 Depends on the configuration of the terminal emulator.
141 Usually is shift tab though.
143 .Ss GNU Emacs-like keys
144 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
158 move-beginning-of-line
174 execute-extended-command
216 .Ss Xr vi 1 Ns -like keys
217 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
231 move-beginning-of-line
263 execute-extended-command
266 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
276 move-beginning-of-line
300 .Ss Neither Emacs nor vi specific
301 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
321 .Ss Minibuffer-specific keys
322 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
324 mini-complete-and-exit
332 mini-delete-backward-char
334 mini-delete-backward-char
336 mini-delete-backward-char
348 move-beginning-of-line
352 move-beginning-of-line
356 mini-previous-history-element
358 mini-next-history-element
368 insert-current-candidate
370 .Sh INTERACTIVE COMMANDS
371 Follows the documentation for the interactive commands.
372 These commands can be bound to a key or executed with
373 .Ic execute-extended-command .
374 .Ss Movement commands
375 .Bl -tag -width execute-extended-command -compact
377 Move point one character backward.
378 .It Ic backward-paragraph
379 Move point one paragraph backward.
380 .It Ic beginning-of-buffer
381 Move point to the beginning of the buffer.
383 Move point to the end of the buffer.
385 Move point one character forward.
386 .It Ic forward-paragraph
387 Move point one paragraph forward.
388 .It Ic insert-current-candidate
389 Copy the current selection text as minibuffer input.
390 .It Ic move-beginning-of-line
391 Move point at the beginning of the current (visual) line.
392 .It Ic move-end-of-line
393 Move point at the end of the current (visual) line.
395 Move point to the next link.
396 .It Ic next-completion
397 Select the next completion.
399 Move point to the next heading.
401 Move point to the next (visual) line, in the same column if possible.
402 .It Ic previous-button
403 Move point to the previous link.
404 .It Ic previous-completion
405 Select the previous completion.
406 .It Ic previous-heading
407 Move point to the previous heading.
409 Move point to the previous (visual) line.
411 .Ss Bookmark-related commands
412 .Bl -tag -width execute-extended-command -compact
414 Add a link to the bookmark file.
415 It preloads the minibuffer with the current URL.
416 .It Ic list-bookmarks
417 Load the bookmarks page.
419 .Ss Tab-related commands
420 .Bl -tag -width execute-extended-command -compact
422 Close the current tab.
423 .It Ic tab-close-other
424 Close all tabs but the current one.
426 Move the current tab after the next one, wrapping around if
429 Move the current tab before the previous one, wrapping around if needed.
433 Focus next tab, wrapping around eventually.
435 Focus the previous tab, wrapping around eventually.
437 Switch to a tab using the minibuffer.
440 .Bl -tag -width execute-extended-command -compact
442 Clears the echo area.
443 .It Ic dec-fill-column
444 Decrements fill-column by two.
445 .It Ic execute-extended-command
446 Prompts for a command name using the minibuffer.
447 .It Ic kill-telescope
450 .It Ic inc-fill-column
451 Increments fill-column by two.
453 Select and visit a link using the minibuffer.
454 .It Ic load-current-url
455 Prompts for an URL, the minibuffer is preloaded with the current
460 Load the next item in the history list.
462 Toggle olivetti mode (i.e. horizontal centering of the lines of the
465 Load the previous item in the history list.
467 Follow the link on the current line, or toggle the visibility of the
468 following preformatted block if called when the cursor is on the
469 heading of the block.
470 .It Ic push-button-new-tab
471 Follow the link on the current line on a new tab.
473 Redraw the screen, useful if some background program messed up the
476 Reload the current page.
478 Scroll down by one visual page.
479 .It Ic scroll-line-down
480 Scroll down by one line.
481 .It Ic scroll-line-up
482 Scroll up by one line.
484 Scroll up by one visual page.
485 .It Ic suspend-telescope
490 Jump to a line using the minibuffer.
492 Select and jump to a heading of the page using the minibuffer.
494 Toggle side window with help about available keys and their associated
496 .It Ic toggle-pre-wrap
497 Toggle the wrapping of preformatted blocks.
499 .Ss Minibuffer commands
500 .Bl -tag -width execute-extended-command -compact
502 Abort the current minibuffer action.
503 .It Ic mini-complete-and-exit
504 Complete the current minibuffer action.
505 .It Ic mini-delete-backward-char
506 Delete the character before the point.
507 .It Ic mini-delete-char
508 Delete the character after the point.
509 .It Ic mini-kill-line
510 Delete from the point until the end of the line.
511 .It Ic mini-next-history-element
512 Load the previous history element.
513 .It Ic mini-previous-history-element
514 Load the next history element.
517 The following aliases are available during
518 .Ic execute-extended-command :
519 .Bl -tag -width 16m -compact
526 .It Ic q No and Ic wq
529 .Sh CONFIGURATION FILE
532 reads the configuration file at
533 .Pa ~/.telescope/config
534 or the one given with the
539 will also load a file called
543 is the name of the terminal type
544 .Pq i.e. the TERM variable ,
547 The format of the configuration file is fairly flexible.
548 The current line can be extended over multiple ones using a
551 Comments can be put anywhere in the file using a hash mark
553 and extend to the end of the current line, but backslashes can't be
554 used to extend comments over multiple lines.
556 The following constructs are available:
558 .It Ic bind Ar map Ar key Ar cmd
565 Valid values for map are
567 .Pq i.e. when the user is viewing a page
570 .Pq i.e. when the minibuffer has the focus.
572 follows the same syntax described in
573 .Sx DEFAULT KEY BINDINGS
574 and all the possible functions are listed in
575 .Sx INTERACTIVE COMMANDS .
576 .It Ic proxy Ar proto Ic via Ar url
579 as proxy for all URLs with
583 must be a Gemini URI without path, query and fragment component.
584 .It Ic set Ar opt No = Ar val
591 .Bl -tag -width twelveletters -compact
594 If nonzero, don't wrap preformatted blocks.
597 If not zero, when the text of a link starts with an emoji followed by
598 a space, use that emoji as line prefix.
602 If not zero, enable colours.
605 is not set, 0 otherwise.
608 If greater than zero, lines of text will be formatted in a way that
609 don't exceed the given number of columns.
613 If nonzero, hide by default the body of the preformatted blocks.
616 can be used to toggle the visibility per-block.
617 .It hide-pre-closing-line
619 If nonzero, hide the closing line of preformatted blocks.
622 If nonzero, hide the start and end line of the preformatted blocks.
623 If both hide-pre-context and hide-pre-blocks are nonzero, preformatted
624 blocks are irremediably hidden.
628 URL for the new tab page.
638 .It Ic style Ar name Ar option
639 Change the styling of the element identified by
641 Multiple options may be specified within curly braces.
642 Valid style identifiers are:
643 .Bl -tag -width 16m -compact -offset Ds
645 for the area outside the lines in the body of the page.
647 for the completion in the minibuffer
648 .It line.compl.current
649 for the current completion
661 for the heading of a preformatted block.
663 for the content of a preformatted block.
665 for the closing line of a preformatted block.
668 .Dq i.e. the last line of the window
671 .Dq i.e. the info line right above the minibuffer
675 for the non-focused tabs.
682 .It Ic attr Ar prefix Oo Ar line Oo Ar trail Oc Oc
683 Sets the text attributes.
684 If only one value is given,
688 default to that; if two values are given then
692 Each attribute is a comma-separated list of keywords:
693 .Bl -tag -width underline -compact -offset Ds
697 best highlighting mode for the terminal.
701 reverses background/foreground colors.
703 makes the text blinking.
707 extra bright or bold.
710 Only the styles under the
712 prefix accept up to three attributes.
713 The other will only use the first one given.
714 .It Ic bg Ar prefix Oo Ar line Oo Ar trail Oc Oc
715 Sets the background color.
716 Follows the same behaviour as
718 regarding the optional parameters.
719 The colour is one of black, red, green, yellow, blue,
720 magenta, cyan and white; colour0 to colour255
721 .Pq or color0 to color255
722 from the 256-colour set;
723 default for the default colour.
724 .It Ic fg Ar prefix Oo Ar line Oo Ar trail Oc Oc
725 Sets the foreground color.
728 .It Ic prefix Ar prfx Op Ar cont
729 Sets the prefix for the current line type to
733 as the prefix for the continuation lines
734 .Pq i.e. when a long line gets wrapped.
737 is not given its value will be the same of
742 .Bl -tag -width Ds -compact
743 .It Pa ~/.telescope/bookmarks.gmi
745 .It Pa ~/.telescope/config
746 Default configuration file.
747 .It Pa ~/.telescope/known_hosts
748 Contains a list of host keys for all the hosts the user has visited.
749 See the TOFU section for more info.
750 .It Pa ~/.telescope/lock
751 Lock file used to prevent multiple instance of
753 from running at the same time.
754 .It Pa ~/.telescope/session
755 Contains the list of opened tabs in the last session, one per line.
758 and loaded on startup.
761 The following is my config file:
762 .Bd -literal -offset indent
763 # enable colors regardless of $NO_COLOR
764 set enable-colors = 1
779 It's possible to browse
781 .Pq i.e. simple websites
782 by using programs like the duckling-proxy by defining a proxy in
783 .Pa ~/.telescope/config :
784 .Bd -literal -offset indent
785 proxy http via "gemini://localhost:1965"
786 proxy https via "gemini://localhost:1965"
791 without any configuration use
792 .Bd -literal -offset indent
793 telescope -c /dev/null
799 program was written by
800 .An Omar Polo Aq Mt op@omarpolo.com .
