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
208 .Ss Xr vi 1 Ns -like keys
209 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
223 move-beginning-of-line
255 execute-extended-command
258 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
276 .Ss Neither Emacs nor vi specific
277 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
291 .Ss Minibuffer-specific keys
292 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
294 mini-complete-and-exit
302 mini-delete-backward-char
304 mini-delete-backward-char
306 mini-delete-backward-char
318 move-beginning-of-line
322 move-beginning-of-line
326 mini-previous-history-element
328 mini-next-history-element
330 mini-previous-history-element
332 mini-next-history-element
334 .Sh INTERACTIVE COMMANDS
335 Follows the documentation for the interactive commands.
336 These commands can be bound to a key or executed with
337 .Ic execute-extended-command .
338 .Ss Movement commands
339 .Bl -tag -width execute-extended-command -compact
341 Move point one character backward.
342 .It Ic backward-paragraph
343 Move point one paragraph backward.
344 .It Ic beginning-of-buffer
345 Move point to the beginning of the buffer.
347 Move point to the end of the buffer.
349 Move point one character forward.
350 .It Ic forward-paragraph
351 Move point one paragraph forward.
352 .It Ic move-beginning-of-line
353 Move point at the beginning of the current (visual) line.
354 .It Ic move-end-of-line
355 Move point at the end of the current (visual) line.
357 Move point to the next link.
359 Move point to the next heading.
361 Move point to the next (visual) line, in the same column if possible.
362 .It Ic previous-button
363 Move point to the previous link.
364 .It Ic previous-heading
365 Move point to the previous heading.
367 Move point to the previous (visual) line.
369 .Ss Bookmark-related commands
370 .Bl -tag -width execute-extended-command -compact
372 Add a link to the bookmark file.
373 It preloads the minibuffer with the current URL.
374 .It Ic list-bookmarks
375 Load the bookmarks page.
377 .Ss Tab-related commands
378 .Bl -tag -width execute-extended-command -compact
380 Close the current tab.
381 .It Ic tab-close-other
382 Close all tabs but the current one.
384 Move the current tab after the next one, wrapping around if
387 Move the current tab before the previous one, wrapping around if needed.
391 Focus next tab, wrapping around eventually.
393 Focus the previous tab, wrapping around eventually.
396 .Bl -tag -width execute-extended-command -compact
398 Clears the echo area.
399 .It Ic dec-fill-column
400 Decrements fill-column by two.
401 .It Ic execute-extended-command
402 Prompts for a command name using the minibuffer.
403 .It Ic kill-telescope
406 .It Ic inc-fill-column
407 Increments fill-column by two.
408 .It Ic load-current-url
409 Prompts for an URL, the minibuffer is preloaded with the current
414 Load the next item in the history list.
416 Toggle olivetti mode (i.e. horizontal centering of the lines of the
419 Load the previous item in the history list.
421 Follow the link on the current line.
422 .It Ic push-button-new-tab
423 Follow the link on the current line on a new tab.
425 Redraw the screen, useful if some background program messed up the
428 Scroll down by one visual page.
429 .It Ic scroll-line-down
430 Scroll down by one line.
431 .It Ic scroll-line-up
432 Scroll up by one line.
434 Scroll up by one visual page.
436 Toggle side window with help about available keys and their associated
439 .Ss Minibuffer commands
440 .Bl -tag -width execute-extended-command -compact
442 Abort the current minibuffer action.
443 .It Ic mini-complete-and-exit
444 Complete the current minibuffer action.
445 .It Ic mini-delete-backward-char
446 Delete the character before the point.
447 .It Ic mini-delete-char
448 Delete the character after the point.
449 .It Ic mini-kill-line
450 Delete from the point until the end of the line.
451 .It Ic mini-next-history-element
452 Load the previous history element.
453 .It Ic mini-previous-history-element
454 Load the next history element.
457 The following aliases are available during
458 .Ic execute-extended-command :
459 .Bl -tag -width 16m -compact
466 .It Ic q No and Ic wq
469 .Sh CONFIGURATION FILE
472 reads the configuration file at
473 .Pa ~/.telescope/config
474 or the one given with the
478 The format of the configuration file is fairly flexible.
479 The current line can be extended over multiple ones using a
482 Comments can be put anywhere in the file using a hash mark
484 and extend to the end of the current line, but backslashes can't be
485 used to extend comments over multiple lines.
487 The following constructs are available:
489 .It Ic bind Ar map Ar key Ar cmd
496 Valid values for map are
498 .Pq i.e. when the user is viewing a page
501 .Pq i.e. when the minibuffer has the focus.
503 follows the same syntax described in
504 .Sx DEFAULT KEY BINDINGS
505 and all the possible functions are listed in
506 .Sx INTERACTIVE COMMANDS .
507 .It Ic proxy Ar proto Ic via Ar url
510 as proxy for all URLs with
514 must be a Gemini URI without path, query and fragment component.
515 .It Ic set Ar opt No = Ar val
522 .Bl -tag -width twelveletters -compact
525 If not zero, enable colours.
528 is not set, 0 otherwise.
531 If greater than zero, lines of text will be formatted in a way that
532 don't exceed the given number of columns.
536 URL for the new tab page.
546 .It Ic style Ar name Ar option
547 Change the styling of the element identified by
549 Multiple options may be specified within curly braces.
550 Valid style identifiers are:
551 .Bl -tag -width 16m -compact -offset Ds
553 for the area outside the lines in the body of the page.
565 for the heading of a preformatted block.
567 for the content of a preformatted block.
569 for the closing line of a preformatted block.
572 .Dq i.e. the last line of the window
575 .Dq i.e. the info line right above the minibuffer
579 for the non-focused tabs.
586 .It Ic attr Ar prefix Oo Ar line Oo Ar trail Oc Oc
587 Sets the text attributes.
588 If only one value is given,
592 default to that; if two values are given then
596 Each attribute is a comma-separated list of keywords:
597 .Bl -tag -width underline -compact -offset Ds
601 best highlighting mode for the terminal.
605 reverses background/foreground colors.
607 makes the text blinking.
611 extra bright or bold.
614 Only the styles under the
616 prefix accept up to three attributes.
617 The other will only use the first one given.
618 .It Ic bg Ar prefix Oo Ar line Oo Ar trail Oc Oc
619 Sets the background color.
620 Follows the same behaviour as
622 regarding the optional parameters.
623 The colour is one of black, red, green, yellow, blue,
624 magenta, cyan and white; colour0 to colour255
625 .Pq or color0 to color255
626 from the 256-colour set;
627 default for the default colour.
628 .It Ic fg Ar prefix Oo Ar line Oo Ar trail Oc Oc
629 Sets the foreground color.
632 .It Ic prefix Ar prfx Op Ar cont
633 Sets the prefix for the current line type to
637 as the prefix for the continuation lines
638 .Pq i.e. when a long line gets wrapped.
641 is not given its value will be the same of
646 .Bl -tag -width Ds -compact
647 .It Pa ~/.telescope/bookmarks.gmi
649 .It Pa ~/.telescope/config
650 Default configuration file.
651 .It Pa ~/.telescope/known_hosts
652 Contains a list of host keys for all the hosts the user has visited.
653 See the TOFU section for more info.
654 .It Pa ~/.telescope/session
655 Contains the list of opened tabs in the last session, one per line.
658 and loaded on startup.
661 The following is my config file:
662 .Bd -literal -offset indent
663 # enable colors regardless of $NO_COLOR
664 set enable-colors = 1
679 It's possible to browse
681 .Pq i.e. simple websites
682 by using programs like the duckling-proxy by defining a proxy in
683 .Pa ~/.telescope/config :
684 .Bd -literal -offset indent
685 proxy http via "gemini://localhost:1965"
686 proxy https via "gemini://localhost:1965"
691 without any configuration use
692 .Bd -literal -offset indent
693 telescope -c /dev/null
699 program was written by
700 .An Omar Polo Aq Mt op@omarpolo.com .
