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 tenletters
37 Display version and usage.
40 Only check the configuration file for validity.
42 Specify an alternative configuration file.
44 .Pa $HOME/.telescope/config
49 aims to use the "Trust, but Verify (where appropriate)" approach.
50 The idea is to define three level of verification for a certificate:
53 the server fingerprint does NOT match the stored value
55 the server fingerprint matches the store one
57 the fingerprint matches and has been verified out-of-band
62 level is enough, but where is appropriate users should be able to
63 verify out-of-band the certificate.
65 At the moment, there is no built-in support for an out-of-band
68 Known certificates are store in
69 .Pa ~/.telescope/known_hosts
70 with a format similar to the
74 Each line is a record and it's made up by three fields, separated by a
75 single space, according to the following format:
80 the hostname, optionally followed by a colon (":") and a port number.
82 is the hash of the certificate, as outputted by
83 .Xr tls_peer_cert_hash 3 .
86 0 means trusted, 1 verified.
88 .Sh DEFAULT KEY BINDINGS
89 The default key bindings are very similar to GNU Emacs, but care has
90 been taken to include also bindings familiar for
95 In the following examples, C-x means Control-x, M-x means Meta-x,
96 where the Meta key may be either a special key on the keyboard or the
97 ALT key; otherwise ESC followed by the key X works as well, and C-M-x
98 means to press the key X together with both Control and Meta.
100 Keys are usually a single character, like
104 but some special keys are accepted as well.
106 .Bl -tag -width 16m -offset indent -compact
116 Previous page/Page up
136 Depends on the configuration of the terminal emulator.
137 Usually is shift tab though.
139 .Ss GNU Emacs-like keys
140 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
154 move-beginning-of-line
170 execute-extended-command
210 .Ss Xr vi 1 Ns -like keys
211 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
225 move-beginning-of-line
257 execute-extended-command
260 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
290 .Ss Neither Emacs nor vi specific
291 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
311 .Ss Minibuffer-specific keys
312 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
314 mini-complete-and-exit
322 mini-delete-backward-char
324 mini-delete-backward-char
326 mini-delete-backward-char
338 move-beginning-of-line
342 move-beginning-of-line
346 mini-previous-history-element
348 mini-next-history-element
358 insert-current-candidate
360 .Sh INTERACTIVE COMMANDS
361 Follows the documentation for the interactive commands.
362 These commands can be bound to a key or executed with
363 .Ic execute-extended-command .
364 .Ss Movement commands
365 .Bl -tag -width execute-extended-command -compact
367 Move point one character backward.
368 .It Ic backward-paragraph
369 Move point one paragraph backward.
370 .It Ic beginning-of-buffer
371 Move point to the beginning of the buffer.
373 Move point to the end of the buffer.
375 Move point one character forward.
376 .It Ic forward-paragraph
377 Move point one paragraph forward.
378 .It Ic insert-current-candidate
379 Copy the current selection text as minibuffer input.
380 .It Ic move-beginning-of-line
381 Move point at the beginning of the current (visual) line.
382 .It Ic move-end-of-line
383 Move point at the end of the current (visual) line.
385 Move point to the next link.
386 .It Ic next-completion
387 Select the next completion.
389 Move point to the next heading.
391 Move point to the next (visual) line, in the same column if possible.
392 .It Ic previous-button
393 Move point to the previous link.
394 .It Ic previous-completion
395 Select the previous completion.
396 .It Ic previous-heading
397 Move point to the previous heading.
399 Move point to the previous (visual) line.
401 .Ss Bookmark-related commands
402 .Bl -tag -width execute-extended-command -compact
404 Add a link to the bookmark file.
405 It preloads the minibuffer with the current URL.
406 .It Ic list-bookmarks
407 Load the bookmarks page.
409 .Ss Tab-related commands
410 .Bl -tag -width execute-extended-command -compact
412 Close the current tab.
413 .It Ic tab-close-other
414 Close all tabs but the current one.
416 Move the current tab after the next one, wrapping around if
419 Move the current tab before the previous one, wrapping around if needed.
423 Focus next tab, wrapping around eventually.
425 Focus the previous tab, wrapping around eventually.
427 Switch to a tab using the minibuffer.
430 .Bl -tag -width execute-extended-command -compact
432 Clears the echo area.
433 .It Ic dec-fill-column
434 Decrements fill-column by two.
435 .It Ic execute-extended-command
436 Prompts for a command name using the minibuffer.
437 .It Ic kill-telescope
440 .It Ic inc-fill-column
441 Increments fill-column by two.
443 Select and visit a link using the minibuffer.
444 .It Ic load-current-url
445 Prompts for an URL, the minibuffer is preloaded with the current
450 Load the next item in the history list.
452 Toggle olivetti mode (i.e. horizontal centering of the lines of the
455 Load the previous item in the history list.
457 Follow the link on the current line, or toggle the visibility of the
458 following preformatted block if called when the cursor is on the
459 heading of the block.
460 .It Ic push-button-new-tab
461 Follow the link on the current line on a new tab.
463 Redraw the screen, useful if some background program messed up the
466 Reload the current page.
468 Scroll down by one visual page.
469 .It Ic scroll-line-down
470 Scroll down by one line.
471 .It Ic scroll-line-up
472 Scroll up by one line.
474 Scroll up by one visual page.
476 Jump to a line using the minibuffer.
478 Select and jump to a heading of the page using the minibuffer.
480 Toggle side window with help about available keys and their associated
483 .Ss Minibuffer commands
484 .Bl -tag -width execute-extended-command -compact
486 Abort the current minibuffer action.
487 .It Ic mini-complete-and-exit
488 Complete the current minibuffer action.
489 .It Ic mini-delete-backward-char
490 Delete the character before the point.
491 .It Ic mini-delete-char
492 Delete the character after the point.
493 .It Ic mini-kill-line
494 Delete from the point until the end of the line.
495 .It Ic mini-next-history-element
496 Load the previous history element.
497 .It Ic mini-previous-history-element
498 Load the next history element.
501 The following aliases are available during
502 .Ic execute-extended-command :
503 .Bl -tag -width 16m -compact
510 .It Ic q No and Ic wq
513 .Sh CONFIGURATION FILE
516 reads the configuration file at
517 .Pa ~/.telescope/config
518 or the one given with the
522 The format of the configuration file is fairly flexible.
523 The current line can be extended over multiple ones using a
526 Comments can be put anywhere in the file using a hash mark
528 and extend to the end of the current line, but backslashes can't be
529 used to extend comments over multiple lines.
531 The following constructs are available:
533 .It Ic bind Ar map Ar key Ar cmd
540 Valid values for map are
542 .Pq i.e. when the user is viewing a page
545 .Pq i.e. when the minibuffer has the focus.
547 follows the same syntax described in
548 .Sx DEFAULT KEY BINDINGS
549 and all the possible functions are listed in
550 .Sx INTERACTIVE COMMANDS .
551 .It Ic proxy Ar proto Ic via Ar url
554 as proxy for all URLs with
558 must be a Gemini URI without path, query and fragment component.
559 .It Ic set Ar opt No = Ar val
566 .Bl -tag -width twelveletters -compact
569 If not zero, enable colours.
572 is not set, 0 otherwise.
575 If greater than zero, lines of text will be formatted in a way that
576 don't exceed the given number of columns.
580 If nonzero, hide by default the body of the preformatted blocks.
583 can be used to toggle the visibility per-block.
586 If nonzero, hide the start and end line of the preformatted blocks.
587 If both hide-pre-context and hide-pre-blocks are nonzero, preformatted
588 blocks are irremediably hidden.
592 URL for the new tab page.
602 .It Ic style Ar name Ar option
603 Change the styling of the element identified by
605 Multiple options may be specified within curly braces.
606 Valid style identifiers are:
607 .Bl -tag -width 16m -compact -offset Ds
609 for the area outside the lines in the body of the page.
611 for the completion in the minibuffer
612 .It line.compl.current
613 for the current completion
625 for the heading of a preformatted block.
627 for the content of a preformatted block.
629 for the closing line of a preformatted block.
632 .Dq i.e. the last line of the window
635 .Dq i.e. the info line right above the minibuffer
639 for the non-focused tabs.
646 .It Ic attr Ar prefix Oo Ar line Oo Ar trail Oc Oc
647 Sets the text attributes.
648 If only one value is given,
652 default to that; if two values are given then
656 Each attribute is a comma-separated list of keywords:
657 .Bl -tag -width underline -compact -offset Ds
661 best highlighting mode for the terminal.
665 reverses background/foreground colors.
667 makes the text blinking.
671 extra bright or bold.
674 Only the styles under the
676 prefix accept up to three attributes.
677 The other will only use the first one given.
678 .It Ic bg Ar prefix Oo Ar line Oo Ar trail Oc Oc
679 Sets the background color.
680 Follows the same behaviour as
682 regarding the optional parameters.
683 The colour is one of black, red, green, yellow, blue,
684 magenta, cyan and white; colour0 to colour255
685 .Pq or color0 to color255
686 from the 256-colour set;
687 default for the default colour.
688 .It Ic fg Ar prefix Oo Ar line Oo Ar trail Oc Oc
689 Sets the foreground color.
692 .It Ic prefix Ar prfx Op Ar cont
693 Sets the prefix for the current line type to
697 as the prefix for the continuation lines
698 .Pq i.e. when a long line gets wrapped.
701 is not given its value will be the same of
706 .Bl -tag -width Ds -compact
707 .It Pa ~/.telescope/bookmarks.gmi
709 .It Pa ~/.telescope/config
710 Default configuration file.
711 .It Pa ~/.telescope/known_hosts
712 Contains a list of host keys for all the hosts the user has visited.
713 See the TOFU section for more info.
714 .It Pa ~/.telescope/session
715 Contains the list of opened tabs in the last session, one per line.
718 and loaded on startup.
721 The following is my config file:
722 .Bd -literal -offset indent
723 # enable colors regardless of $NO_COLOR
724 set enable-colors = 1
739 It's possible to browse
741 .Pq i.e. simple websites
742 by using programs like the duckling-proxy by defining a proxy in
743 .Pa ~/.telescope/config :
744 .Bd -literal -offset indent
745 proxy http via "gemini://localhost:1965"
746 proxy https via "gemini://localhost:1965"
751 without any configuration use
752 .Bd -literal -offset indent
753 telescope -c /dev/null
759 program was written by
760 .An Omar Polo Aq Mt op@omarpolo.com .
