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
204 .Ss Xr vi 1 Ns -like keys
205 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
219 move-beginning-of-line
251 execute-extended-command
254 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
272 .Ss Neither Emacs nor vi specific
273 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
287 .Ss Minibuffer-specific keys
288 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
290 mini-complete-and-exit
298 mini-delete-backward-char
300 mini-delete-backward-char
302 mini-delete-backward-char
314 move-beginning-of-line
318 move-beginning-of-line
322 mini-previous-history-element
324 mini-next-history-element
326 mini-previous-history-element
328 mini-next-history-element
330 .Sh INTERACTIVE COMMANDS
331 Follows the documentation for the interactive commands.
332 These commands can be bound to a key or executed with
333 .Ic execute-extended-command .
334 .Ss Movement commands
335 .Bl -tag -width execute-extended-command -compact
337 Move point one character backward.
338 .It Ic backward-paragraph
339 Move point one paragraph backward.
340 .It Ic beginning-of-buffer
341 Move point to the beginning of the buffer.
343 Move point to the end of the buffer.
345 Move point one character forward.
346 .It Ic forward-paragraph
347 Move point one paragraph forward.
348 .It Ic move-beginning-of-line
349 Move point at the beginning of the current (visual) line.
350 .It Ic move-end-of-line
351 Move point at the end of the current (visual) line.
353 Move point to the next link.
355 Move point to the next heading.
357 Move point to the next (visual) line, in the same column if possible.
358 .It Ic previous-button
359 Move point to the previous link.
360 .It Ic previous-heading
361 Move point to the previous heading.
363 Move point to the previous (visual) line.
365 .Ss Bookmark-related commands
366 .Bl -tag -width execute-extended-command -compact
368 Add a link to the bookmark file.
369 It preloads the minibuffer with the current URL.
370 .It Ic list-bookmarks
371 Load the bookmarks page.
373 .Ss Tab-related commands
374 .Bl -tag -width execute-extended-command -compact
376 Close the current tab.
377 .It Ic tab-close-other
378 Close all tabs but the current one.
380 Move the current tab after the next one, wrapping around if
383 Move the current tab before the previous one, wrapping around if needed.
387 Focus next tab, wrapping around eventually.
389 Focus the previous tab, wrapping around eventually.
392 .Bl -tag -width execute-extended-command -compact
394 Clears the echo area.
395 .It Ic execute-extended-command
396 Prompts for a command name using the minibuffer.
397 .It Ic kill-telescope
400 .It Ic load-current-url
401 Prompts for an URL, the minibuffer is preloaded with the current
406 Load the next item in the history list.
408 Toggle olivetti mode (i.e. horizontal centering of the lines of the
411 Load the previous item in the history list.
413 Follow the link on the current line.
414 .It Ic push-button-new-tab
415 Follow the link on the current line on a new tab.
417 Redraw the screen, useful if some background program messed up the
420 Scroll down by one visual page.
421 .It Ic scroll-line-down
422 Scroll down by one line.
423 .It Ic scroll-line-up
424 Scroll up by one line.
426 Scroll up by one visual page.
428 Toggle side window with help about available keys and their associated
431 .Ss Minibuffer commands
432 .Bl -tag -width execute-extended-command -compact
434 Abort the current minibuffer action.
435 .It Ic mini-complete-and-exit
436 Complete the current minibuffer action.
437 .It Ic mini-delete-backward-char
438 Delete the character before the point.
439 .It Ic mini-delete-char
440 Delete the character after the point.
441 .It Ic mini-kill-line
442 Delete from the point until the end of the line.
443 .It Ic mini-next-history-element
444 Load the previous history element.
445 .It Ic mini-previous-history-element
446 Load the next history element.
449 The following aliases are available during
450 .Ic execute-extended-command :
451 .Bl -tag -width 16m -compact
458 .It Ic q No and Ic wq
461 .Sh CONFIGURATION FILE
464 reads the configuration file at
465 .Pa ~/.telescope/config
466 or the one given with the
470 The format of the configuration file is fairly flexible.
471 The current line can be extended over multiple ones using a
474 Comments can be put anywhere in the file using a hash mark
476 and extend to the end of the current line, but backslashes can't be
477 used to extend comments over multiple lines.
479 The following constructs are available:
481 .It Ic bind Ar map Ar key Ar cmd
488 Valid values for map are
490 .Pq i.e. when the user is viewing a page
493 .Pq i.e. when the minibuffer has the focus.
495 follows the same syntax described in
496 .Sx DEFAULT KEY BINDINGS
497 and all the possible functions are listed in
498 .Sx INTERACTIVE COMMANDS .
499 .It Ic proxy Ar proto Ic via Ar url
502 as proxy for all URLs with
506 must be a Gemini URI without path, query and fragment component.
507 .It Ic set Ar opt No = Ar val
514 .Bl -tag -width twelveletters -compact
517 If not zero, enable colours.
520 is not set, 0 otherwise.
523 If greater than zero, lines of text will be formatted in a way that
524 don't exceed the given number of columns.
528 URL for the new tab page.
538 .It Ic style Ar name Ar option
539 Change the styling of the element identified by
541 Multiple options may be specified within curly braces.
542 Valid style identifiers are:
543 .Bl -tag -width 14m -compact -offset Ds
555 for the heading of a preformatted block
557 for the content of a preformatted block
559 for the closing line of a preformatted block
564 .It Ic attr Ar prefix Oo Ar line Oo Ar trail Oc Oc
565 Sets the text attributes.
566 If only one value is given,
570 default to that; if two values are given then
574 Each attribute is a comma-separated list of keywords:
575 .Bl -tag -width underline -compact -offset Ds
579 best highlighting mode for the terminal.
583 reverses background/foreground colors.
585 makes the text blinking.
589 extra bright or bold.
591 .It Ic bg Ar prefix Oo Ar line Oo Ar trail Oc Oc
592 Sets the background color.
593 Follows the same behaviour as
595 regarding the optional parameters.
596 Supported colors are: default, black, red, green, yellow, blue,
597 magenta, cyan and white
598 .It Ic fg Ar prefix Oo Ar line Oo Ar trail Oc Oc
599 Sets the foreground color.
602 .It Ic prefix Ar prfx Op Ar cont
603 Sets the prefix for the given line to
607 as the prefix for the continuation lines
608 .Pq i.e. when a long line gets wrapped.
611 is not given its value will be the same of
616 .Bl -tag -width Ds -compact
617 .It Pa ~/.telescope/bookmarks.gmi
619 .It Pa ~/.telescope/config
620 Default configuration file.
621 .It Pa ~/.telescope/known_hosts
622 Contains a list of host keys for all the hosts the user has visited.
623 See the TOFU section for more info.
624 .It Pa ~/.telescope/session
625 Contains the list of opened tabs in the last session, one per line.
628 and loaded on startup.
631 The following is my config file:
632 .Bd -literal -offset indent
633 # ignore the NO_COLOR environment variable
634 set enable-colors = 1
643 attr normal underline
651 It's possible to browse
653 .Pq i.e. simple websites
654 by using programs like the duckling-proxy by defining a proxy in
655 .Pa ~/.telescope/config :
656 .Bd -literal -offset indent
657 proxy http via "gemini://localhost:1965"
658 proxy https via "gemini://localhost:1965"
663 without any configuration use
664 .Bd -literal -offset indent
665 telescope -c /dev/null
671 program was written by
672 .An Omar Polo Aq Mt op@omarpolo.com .
