Blob


1 .\" Copyright (c) 2021, 2022 Omar Polo <op@omarpolo.com>
2 .\"
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.
6 .\"
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: January 05 2022$
15 .Dt TELESCOPE 1
16 .Os
17 .Sh NAME
18 .Nm telescope
19 .Nd multi-protocol browser
20 .Sh SYNOPSIS
21 .Nm
22 .Bk -words
23 .Op Fl ChnSv
24 .Op Fl c Ar config
25 .Op Ar URL
26 .Ek
27 .Sh DESCRIPTION
28 .Nm
29 is an interactive browser that supports the Finger, Gemini and Gopher
30 protocols.
31 .Nm
32 features tabs, a minibuffer, interactive completions, bookmarks and
33 out-of-band TOFU verification.
34 .Pp
35 The arguments are as follows:
36 .Bl -tag -width xxxxxxxxxxxxx
37 .It Fl C , Fl -colours
38 Show all available colors and exit.
39 This option can also be spelled
40 .Fl -colors .
41 .It Fl c Ar config
42 Specify an alternative configuration file.
43 By default
44 .Pa ~/.config/telescope/config
45 is loaded.
46 .It Fl h , Fl -help
47 Display version, usage and exit.
48 .It Fl n
49 Configtest mode.
50 Only check the configuration file for validity.
51 .It Fl S , Fl -safe
52 .Dq Safe
53 .Pq or Dq sandbox
54 mode.
55 Prevent
56 .Nm
57 from writing files to the disk and to acquire the lock, allowing to
58 run multiple instances at the same time.
59 .Nm
60 still loads the session file and the custom about pages.
61 .It Fl v , Fl -version
62 Display version and exit.
63 .El
64 .Sh UI CONCEPTS
65 .Nm
66 interface is divided into four areas: the tabline, the body, the
67 modeline and the echoarea/minibuffer.
68 .Pp
69 The tabline is always at the top of the screen and displays the tabs
70 separated by a vertical line.
71 When there are more tabs than the size of the window allow to display,
72 the characters
73 .Sq \&<
74 or
75 .Sq \&>
76 are shown at the start/end of the tabline to indicate that there are
77 more tabs in that direction.
78 .Pp
79 The body occupies the majority of the visible area.
80 It contains the current page and optionally a side window.
81 .Pp
82 The modeline is the second to last row of the screen.
83 It shows some information about the page: a spinner when the page is
84 loading, the trust level, the document type, the scroll offset and the
85 URL.
86 .Pp
87 The echoarea is usually the last line of the screen.
88 Messages are often showed there, and link addresses too.
89 The echoarea is also used to obtain input from the user.
90 When commands like
91 .Ic swiper
92 or
93 .Ic link-select
94 are invoked, the minibuffer area grows to show possible completions.
95 .Sh TOFU
96 .Nm
97 aims to use the
98 .Dq Trust, but Verify Pq where appropriate
99 approach for
100 TOFU
101 .Pq Dq Trust On First Use .
102 The idea is to define three level of verification for a certificate:
103 .Bl -tag -width 12m
104 .It untrusted
105 .Pq Sq \&!
106 the server fingerprint does NOT match the stored value.
107 .It trusted
108 .Pq Sq v
109 the server fingerprint matches the store one.
110 .It verified
111 .Pq Sq V
112 the fingerprint matches and has been verified out-of-band.
113 .El
114 .Pp
115 The trust level of the page is indicated in the modeline with the
116 indicated character.
117 .Pp
118 Most of the time the
119 .Dq trusted
120 level is enough, but where is appropriate users should be able to
121 verify out-of-band the certificate.
122 .Pp
123 At the moment, there is no built-in support for an out-of-band
124 verification though.
125 .Sh SUPPORTED PROTOCOLS
126 The following protocols are supported:
127 .Bl -tag -width gemini://
128 .It about:
129 About pages are
130 .Nm
131 internal page.
132 See about:about for a list of all these pages.
133 .It file://
134 File types know to
135 .Nm ,
136 such as .gmi, .gemini, .txt, .md, .markdown, .diff or .patch, can be
137 viewed inside the application.
138 Types of local files are detected solely based on the file extension.
139 On some systems, such as
140 .Ox ,
141 only files inside special directories
142 .Pq like Pa /tmp No or Pa ~/Downloads
143 are available.
144 .It finger://
145 Finger URLs are interpreted as follows:
146 .Bl -bullet -compact
147 .It
148 the host is determined by the host name portion of the URL
149 .It
150 if the user portion of the URL is provided, it's interpreted as the
151 user to finger, otherwise the path component will be used
152 .El
153 thus
154 .Lk finger://user@hostname
155 and
156 .Lk finger://hostname/user
157 are treated as the same URL.
158 .It gemini://
159 Gemini is fully supported, with the exception of client-certificates.
160 .It gopher://
161 Gopher support is limited to items type 0, 1 and 7.
162 All text is assumed to be encoded in UTF-8 (or ASCII).
163 .El
164 .Pp
165 User-entered URLs, given as argument on the command line or entered
166 with
167 .Ic load-url ,
168 are intepreted with a simple heuristic:
169 .Bl -bullet -compact
170 .It
171 if it's a proper absolute URL then use it as-is,
172 .It
173 if it starts with
174 .Dq ./
175 or
176 .Dq /
177 assume it's a file:// URL,
178 .It
179 otherwise assume it's a Gemini URL.
180 .El
181 .Sh CONFIGURATION FILE
182 During the startup,
183 .Nm
184 reads the configuration file at
185 .Pa ~/.config/telescope/config
186 or
187 .Pa ~/.telescope/config .
188 .Pp
189 It's possible to load a custom configuration file using the
190 .Fl c
191 flag.
192 .Pp
193 .Nm
194 will also load a file called
195 .Pa config-TERM ,
196 where
197 .Dq TERM
198 is the name of the terminal type
199 .Pq i.e. the TERM environment variable ,
200 if it exists.
201 .Pp
202 The format of the configuration file is fairly flexible.
203 The current line can be extended over multiple ones using a
204 backslash
205 .Pq Sq \e .
206 Comments can be put anywhere in the file using a hash mark
207 .Pq Sq # ,
208 and extend to the end of the current line, but backslashes can't be
209 used to extend comments over multiple lines.
210 .Pp
211 The following constructs are available:
212 .Bl -tag -width Ds
213 .It Ic bind Ar map Ar key Ar cmd
214 Bind
215 .Ar key
216 to the function
217 .Ar cmd
218 in the keymap
219 .Ar map .
220 Valid values for map are
221 .Dq global-map
222 .Pq i.e. when the user is viewing a page
223 and
224 .Dq minibuffer-map
225 .Pq i.e. when the minibuffer has the focus.
226 .Ar key
227 follows the same syntax described in
228 .Sx DEFAULT KEY BINDINGS
229 and all the possible functions are listed in
230 .Sx INTERACTIVE COMMANDS .
231 .It Ic proxy Ar proto Ic via Ar url
232 Use
233 .Ar url
234 as proxy for all URLs with
235 protocol
236 .Ar proto .
237 .Ar url
238 must be a Gemini URI without path, query and fragment component.
239 .It Ic set Ar opt No = Ar val
240 Set the option
241 .Ar opt
242 to the value
243 .Ar val .
244 Valid options are:
245 .Pp
246 .Bl -tag -width twelveletters -compact
247 .It Ic autosave
248 .Pq integer
249 If greater than zero, save the session after the specified amount of
250 seconds after some events happens
251 .Pq new or closed tabs, visited a link ...
252 Defaults to 20.
253 .It Ic dont-wrap-pre
254 .Pq integer
255 If nonzero, don't wrap preformatted blocks.
256 Defaults to 0.
257 .It Ic download-path
258 .Pq string
259 The default download path.
260 Defaults to
261 .Pa /tmp .
262 .It Ic emojify-link
263 .Pq integer
264 If nonzero, when the text of a link starts with an emoji followed by a
265 space, use that emoji as line prefix.
266 Defaults to 1.
267 .It Ic enable-colors
268 .Pq integer
269 If nonzero, enable colours.
270 Defaults to 0 if
271 .Ev NO_COLORS
272 is set, 1 otherwise.
273 .It Ic fill-column
274 .Pq integer
275 If greater than zero, lines of text will be formatted in a way that
276 don't exceed the given number of columns.
277 Defaults to 80.
278 .It Ic fringe-ignore-offset
279 .Pq integer
280 If nonzero, the fringe doesn't obey to
281 .Ic olivetti-mode .
282 Defaults to 1.
283 .It Ic hide-pre-blocks
284 .Pq integer
285 If nonzero, hide by default the body of the preformatted blocks.
286 Defaults to zero.
287 .Ic push-button
288 can be used to toggle the visibility per-block.
289 .It Ic hide-pre-closing-line
290 .Pq integer
291 If nonzero, hide the closing line of preformatted blocks.
292 Defaults to 0.
293 .It Ic hide-pre-context
294 .Pq integer
295 If nonzero, hide the start and end line of the preformatted blocks.
296 If both hide-pre-context and hide-pre-blocks are nonzero, preformatted
297 blocks are irremediably hidden.
298 Defaults to zero.
299 .It Ic new-tab-url
300 .Pq string
301 URL for the new tab page.
302 Defaults to
303 .Dq about:new .
304 .It Ic max-killed-tabs
305 .Pq integer
306 The maximum number of closed tabs to keep track of, defaults to 10.
307 Must be a positive number; if zero, don't save closed tabs at all.
308 .It Ic olivetti-mode
309 .Pq integer
310 If nonzero, enable
311 .Ic olivetti-mode
312 Defaults to 1.
313 .It Ic tab-bar-show
314 .Pq integer
315 If tab-bar-show is -1 hide the tab bar permanently, if 0 show it
316 unconditionally.
317 If it's 1, show the bar only when there is more than one tab.
318 Defaults to 1.
319 .It Ic update-title
320 .Pq integer
321 If nonzero, set the terminal title to the page title.
322 Defaults to 1.
323 .El
324 .It Ic style Ar name Ar option
325 Change the styling of the element identified by
326 .Ar name .
327 Multiple options may be specified within curly braces.
328 Valid style identifiers are:
329 .Bl -tag -width line.download.ongoing -compact -offset Ds
330 .It line
331 the area outside the lines in the body of the page.
332 .It line.compl
333 the completions.
334 .It line.compl.current
335 the current completion.
336 .It line.help
337 text in the *Help* buffer.
338 .It line.download.ongoing
339 an ongoing download
340 .It line.download.done
341 a completed download
342 .It line.download.info
343 informational text in the *Downloads* buffer.
344 .It line.fringe
345 .Pq virtual
346 lines draw after the end of a buffer.
347 .It line.text
348 text lines.
349 .It line.link
350 link lines.
351 .It line.title1..3
352 headings
353 .It line.item
354 item lines.
355 .It line.quote
356 quotes.
357 .It line.pre.start
358 the heading of a preformatted block.
359 .It line.pre
360 the content of a preformatted block.
361 .It line.pre.end
362 the closing line of a preformatted block.
363 .It download
364 the download pane
365 .It minibuffer
366 the minibuffer.
367 .It modeline
368 the modeline.
369 .It tabline
370 the tabline.
371 .It tabline.tab
372 the non-focused tabs.
373 .It tabline.current
374 the focused tab.
375 .El
376 .Pp
377 Valid options are:
378 .Bl -tag -width Ds
379 .It Ic attr Ar prefix Oo Ar line Oo Ar trail Oc Oc
380 Sets the text attributes.
381 If only one value is given,
382 .Ar line
383 and
384 .Ar trail
385 default to that; if two values are given then
386 .Ar trail
387 defaults to
388 .Ar prefix .
389 Each attribute is a comma-separated list of keywords:
390 .Bl -tag -width underline -compact -offset Ds
391 .It Ic normal
392 no attributes.
393 .It Ic standout
394 best highlighting mode for the terminal.
395 .It Ic underline
396 underlines the text.
397 .It Ic reverse
398 reverses background/foreground colors.
399 .It Ic blink
400 makes the text blinking.
401 .It Ic dim
402 half bright.
403 .It Ic bold
404 extra bright or bold.
405 .El
406 .Pp
407 Only the style identifiers with the
408 .Dq line.
409 prefix accept up to three attributes.
410 The other will only use the first one given.
411 .It Ic bg Ar prefix Oo Ar line Oo Ar trail Oc Oc
412 Sets the background color.
413 Follows the same behaviour as
414 .Ic attr
415 regarding the optional parameters.
416 The colour is one of black, red, green, yellow, blue,
417 magenta, cyan and white; colour0 to colour255
418 .Pq or color0 to color255
419 from the 256-colour set;
420 default for the default colour.
421 .It Ic fg Ar prefix Oo Ar line Oo Ar trail Oc Oc
422 Sets the foreground color.
423 It behaves just like
424 .Ic bg .
425 .It Ic prefix Ar prfx Op Ar cont
426 Sets the prefix for the current line type to
427 .Ar prfx
428 and
429 .Ar cont
430 as the prefix for the continuation lines
431 .Pq i.e. when a long line gets wrapped.
432 If
433 .Ar cont
434 is not given its value will be the same of
435 .Ar prfx .
436 .El
437 .El
438 .Sh DEFAULT KEY BINDINGS
439 The default key bindings are very similar to GNU Emacs, but care has
440 been taken to include also bindings familiar for
441 .Xr vi 1
442 and
443 .Dq CUA
444 users.
445 In the following examples, C-x means Control-x, M-x means Meta-x,
446 where the Meta key may be either a special key on the keyboard or the
447 ALT key; otherwise ESC followed by the key X works as well, and C-M-x
448 means to press the key X together with both Control and Meta.
449 .Pp
450 Keys are usually a single character, like
451 .Sq p
452 or
453 .Sq n ,
454 but some special keys are accepted as well.
455 .Pp
456 .Bl -tag -width 16m -offset indent -compact
457 .It <up>
458 Up arrow
459 .It <down>
460 Down arrow
461 .It <left>
462 Left arrow
463 .It <right>
464 Right arrow
465 .It <prior>
466 Previous page/Page up
467 .It <next>
468 Next page/Page down
469 .It <home>
470 Home
471 .It <end>
472 End
473 .It <f0> thru <f63>
474 Function keys
475 .It del or backspace
476 Backspace
477 .It esc
478 Escape
479 .It space or spc
480 Space
481 .It enter or ret
482 Enter
483 .It tab
484 Tab
485 .It backtab
486 Depends on the configuration of the terminal emulator; usually shift
487 tab.
488 .El
489 .Ss GNU Emacs-like keys
490 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
491 .It C-p
492 previous-line
493 .It C-n
494 next-line
495 .It C-f
496 forward-char
497 .It C-b
498 backward-char
499 .It M-{
500 backward-paragraph
501 .It M-}
502 forward-paragraph
503 .It C-a
504 move-beginning-of-line
505 .It C-e
506 move-end-of-line
507 .It M-v, M-space
508 scroll-up
509 .It C-v, space
510 scroll-down
511 .It M-<
512 beginning-of-buffer
513 .It M->
514 end-of-buffer
515 .It C-x C-c
516 kill-telescope
517 .It C-x C-w
518 write-buffer
519 .It C-g
520 clear-minibuf
521 .It M-x
522 execute-extended-command
523 .It C-c {
524 dec-fill-column
525 .It C-c }
526 inc-fill-column
527 .It C-c p
528 previous-heading
529 .It C-c n
530 next-heading
531 .It >
532 load-url
533 .It <
534 load-current-url
535 .It C-x C-f
536 load-url
537 .It C-x M-f
538 load-current-url
539 .It C-x o
540 other-window
541 .It C-x t 0
542 tab-close
543 .It C-x t 1
544 tab-close-other
545 .It C-x t 2
546 tab-new
547 .It C-x t o
548 tab-next
549 .It C-x t O
550 tab-previous
551 .It C-x t m
552 tab-move
553 .It C-x t M
554 tab-move-to
555 .It B, C-M-b
556 previous-page
557 .It F, C-M-f
558 next-page
559 .It <f7> a
560 bookmark-page
561 .It <f7> <f7>
562 list-bookmarks
563 .It C-z
564 suspend-telescope
565 .El
566 .Ss Xr vi 1 Ns -like keys
567 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
568 .It k
569 previous-line
570 .It j
571 next-line
572 .It l
573 forward-char
574 .It h
575 backward-char
576 .It {
577 backward-paragraph
578 .It }
579 forward-paragraph
580 .It ^
581 move-beginning-of-line
582 .It $
583 move-end-of-line
584 .It K
585 scroll-line-up
586 .It J
587 scroll-line-down
588 .It g g
589 beginning-of-buffer
590 .It G
591 end-of-buffer
592 .It g D
593 tab-close
594 .It g N
595 tab-new
596 .It g t
597 tab-next
598 .It g T
599 tab-previous
600 .It g M-t
601 tab-move
602 .It g M-T
603 tab-move-to
604 .It H
605 previous-page
606 .It L
607 next-page
608 .It u
609 tab-undo-close
610 .It q
611 kill-telescope
612 .It ESC
613 clear-minibuf
614 .It :
615 execute-extended-command
616 .El
617 .Ss CUA-like keys
618 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
619 .It <up>
620 previous-line
621 .It <down>
622 next-line
623 .It <right>
624 forward-char
625 .It <left>
626 backward-char
627 .It <home>
628 move-beginning-of-line
629 .It <end>
630 move-end-of-line
631 .It <prior>
632 scroll-up
633 .It <next>
634 scroll-down
635 .It C-w
636 tab-close
637 .It C-t
638 tab-new
639 .It M-<prior>
640 tab-previous
641 .It M-<next>
642 tab-next
643 .It del
644 previous-page
645 .It M-<left>
646 previous-page
647 .It M-<right>
648 next-page
649 .It <f5>
650 reload-page
651 .It r
652 reload-page
653 .El
654 .Ss Neither Emacs nor vi specific
655 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
656 .It <f1>
657 toggle-help
658 .It enter
659 push-button
660 .It M-enter
661 push-button-new-tab
662 .It M-tab
663 previous-button
664 .It backtab
665 previous-button
666 .It tab
667 next-button
668 .It M-t
669 tab-select
670 .It \&[
671 tab-previous
672 .It \&]
673 tab-next
674 .It M-\&[
675 tab-move-to
676 .It M-\&]
677 tab-move
678 .It M-l
679 link-select
680 .It M-/
681 swiper
682 .It M-r
683 reply-last-input
684 .El
685 .Ss Minibuffer-specific keys
686 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
687 .It enter
688 mini-complete-and-exit
689 .It C-g
690 mini-abort
691 .It ESC
692 mini-abort
693 .It C-d
694 mini-delete-char
695 .It del
696 mini-delete-backward-char
697 .It backspace
698 mini-delete-backward-char
699 .It C-h
700 mini-delete-backward-char
701 .It C-b
702 backward-char
703 .It C-f
704 forward-char
705 .It <left>
706 backward-char
707 .It <right>
708 forward-char
709 .It C-e
710 move-end-of-line
711 .It C-a
712 move-beginning-of-line
713 .It <end>
714 move-end-of-line
715 .It <home>
716 move-beginning-of-line
717 .It C-k
718 mini-kill-line
719 .It C-u
720 mini-kill-whole-line
721 .It M-p
722 mini-previous-history-element
723 .It M-n
724 mini-next-history-element
725 .It C-p
726 previous-completion
727 .It C-n
728 next-completion
729 .It <up>
730 previous-completion
731 .It <down>
732 next-completion
733 .It tab
734 insert-current-candidate
735 .It M-<
736 mini-goto-beginning
737 .It M->
738 mini-goto-end
739 .El
740 .Sh INTERACTIVE COMMANDS
741 Follows the documentation for the interactive commands.
742 These commands can be bound to a key or executed with
743 .Ic execute-extended-command .
744 .Ss Movement commands
745 .Bl -tag -width execute-extended-command -compact
746 .It Ic backward-char
747 Move point one character backward.
748 .It Ic backward-paragraph
749 Move point one paragraph backward.
750 .It Ic beginning-of-buffer
751 Move point to the beginning of the buffer.
752 .It Ic end-of-buffer
753 Move point to the end of the buffer.
754 .It Ic forward-char
755 Move point one character forward.
756 .It Ic forward-paragraph
757 Move point one paragraph forward.
758 .It Ic insert-current-candidate
759 Copy the current selection text as minibuffer input.
760 .It Ic move-beginning-of-line
761 Move point at the beginning of the current (visual) line.
762 .It Ic move-end-of-line
763 Move point at the end of the current (visual) line.
764 .It Ic next-button
765 Move point to the next link.
766 .It Ic next-completion
767 Select the next completion.
768 .It Ic next-heading
769 Move point to the next heading.
770 .It Ic next-line
771 Move point to the next (visual) line, in the same column if possible.
772 .It Ic previous-button
773 Move point to the previous link.
774 .It Ic previous-completion
775 Select the previous completion.
776 .It Ic previous-heading
777 Move point to the previous heading.
778 .It Ic previous-line
779 Move point to the previous (visual) line.
780 .El
781 .Ss Bookmark-related commands
782 .Bl -tag -width execute-extended-command -compact
783 .It Ic bookmark-page
784 Save a page in the bookmark file.
785 It preloads the minibuffer with the current URL.
786 .It Ic list-bookmarks
787 Load the bookmarks page.
788 .El
789 .Ss Tab-related commands
790 .Bl -tag -width execute-extended-command -compact
791 .It Ic tab-close
792 Close the current tab.
793 .It Ic tab-close-other
794 Close all tabs but the current one.
795 .It Ic tab-move
796 Move the current tab after the next one, wrapping around if
797 needed.
798 .It Ic tab-move-to
799 Move the current tab before the previous one, wrapping around if needed.
800 .It Ic tab-new
801 Open a new tab.
802 .It Ic tab-next
803 Focus next tab, wrapping around eventually.
804 .It Ic tab-previous
805 Focus the previous tab, wrapping around eventually.
806 .It Ic tab-select
807 Switch to a tab using the minibuffer.
808 .It Ic tab-undo-close
809 Re-open the most recently closed tab, if any.
810 .El
811 .Ss Misc commands
812 .Bl -tag -width execute-extended-command -compact
813 .It Ic cache-info
814 Show cache stats.
815 .It Ic clear-minibuf
816 Clear the echo area.
817 .It Ic dec-fill-column
818 Decrement fill-column by two.
819 .It Ic execute-extended-command
820 Execute an internal command.
821 .It Ic kill-telescope
822 Quit
823 .Nm .
824 .It Ic inc-fill-column
825 Increment fill-column by two.
826 .It Ic link-select
827 Select and visit a link using the minibuffer.
828 .It Ic load-current-url
829 Edit the current URL.
830 .It Ic load-url
831 Prompt for an URL.
832 .It Ic next-page
833 Go forward in the page history.
834 .It Ic olivetti-mode
835 Toggle olivetti mode (i.e. horizontal centering of the lines of the
836 window.)
837 .It Ic other-window
838 Select the other window.
839 .It Ic previous-page
840 Go backward in the page history.
841 .It Ic push-button
842 Follow link at point, or toggle the visibility of the following
843 preformatted block if called when the cursor is on the heading of the block.
844 .It Ic push-button-new-tab
845 Follow link at point in a new tab.
846 .It Ic redraw
847 Redraw the screen, useful if some background program messed up the
848 display.
849 .It Ic reload-page
850 Reload the current page.
851 .It Ic reply-last-input
852 Reply the last input request.
853 .It Ic scroll-down
854 Scroll down by one visual page.
855 .It Ic scroll-line-down
856 Scroll down by one line.
857 .It Ic scroll-line-up
858 Scroll up by one line.
859 .It Ic scroll-up
860 Scroll up by one visual page.
861 .It Ic suspend-telescope
862 Suspend the current
863 .Nm
864 session.
865 .It Ic swiper
866 Jump to a line using the minibuffer.
867 .It Ic toc
868 Jump to a heading using the minibuffer.
869 .It Ic toggle-help
870 Toggle side window with help about available keys and their associated
871 interactive command.
872 .It Ic toggle-pre-wrap
873 Toggle the wrapping of preformatted blocks.
874 .It Ic write-buffer
875 Save the current buffer to the disk.
876 .El
877 .Ss Minibuffer commands
878 .Bl -tag -width execute-extended-command -compact
879 .It Ic mini-abort
880 Abort the current minibuffer action.
881 .It Ic mini-complete-and-exit
882 Complete the current minibuffer action.
883 .It Ic mini-delete-backward-char
884 Delete the character before the point.
885 .It Ic mini-delete-char
886 Delete the character after the point.
887 .It Ic mini-goto-beginning
888 Select the first completion, if any.
889 .It Ic mini-goto-end
890 Select the last completion, if any.
891 .It Ic mini-kill-line
892 Delete from point until the end of the line.
893 .It Ic mini-kill-whole-line
894 Delete the whole line.
895 .It Ic mini-next-history-element
896 Load the previous history element.
897 .It Ic mini-previous-history-element
898 Load the next history element.
899 .El
900 .Ss Aliases
901 The following aliases are available during
902 .Ic execute-extended-command :
903 .Bl -tag -width 16m -compact
904 .It Ic open
905 .Ic load-url
906 .It Ic tabn
907 .Ic tab-next
908 .It Ic tabnew
909 .Ic tab-new
910 .It Ic tabp
911 .Ic tab-previous
912 .It Ic q No and Ic wq
913 .Ic kill-telescope
914 .It Ic w
915 .Ic write-buffer
916 .El
917 .Sh ENVIRONMENT
918 When
919 .Nm
920 is started, it inspects the following environment variables:
921 .Bl -tag -width NO_COLORS
922 .It Ev HOME
923 The user's login directory.
924 .It Ev NO_COLORS
925 To decide whether to use colors or not.
926 The content of the variable doesn't matter.
927 .It Ev TERM
928 The user's terminal name.
929 .It Ev XDG_CACHE_HOME , Ev XDG_CONFIG_HOME , Ev XDG_DATA_HOME
930 If defined can alter the default location of the files used.
931 .El
932 .Sh FILES
933 By default
934 .Nm
935 follows the XDG Base Directory Specification.
936 However, if
937 .Pa ~/.telescope
938 exists, XDG is ignored and all the files are stored inside it.
939 The usage of
940 .Ev XDG_CACHE_HOME ,
941 .Ev XDG_CONFIG_HOME
942 and
943 .Ev XDG_DATA_HOME
944 can further alter the location of these files.
945 .Pp
946 .Bl -tag -width Ds -compact
947 .It Pa ~/.config/telescope/config
948 Default configuration file.
949 .It Pa ~/.local/share/telescope/pages/about_*.gmi
950 Overrides for built-in about: pages.
951 .It Pa ~/.local/share/telescope/bookmarks.gmi
952 Bookmarks file.
953 .It Pa ~/.local/share/telescope/known_hosts
954 Hash of the certificates for all the known hosts.
955 Each line contains three fields: hostname with optional port number,
956 hash of the certificate and a numeric flag.
957 .It Pa ~/.cache/telescope/lock
958 Lock file used to prevent multiple instance of
959 .Nm
960 from running at the same time.
961 .It Pa ~/.cache/telescope/session
962 The list of tabs from the last session.
963 .El
964 .Sh EXAMPLES
965 It's possible to browse
966 .Dq the small web
967 .Pq i.e. simple websites
968 by using programs like the duckling-proxy by defining a proxy in
969 .Pa ~/.config/telescope/config :
970 .Bd -literal -offset indent
971 proxy http via "gemini://127.0.0.1:1965"
972 proxy https via "gemini://127.0.0.1:1965"
973 .Ed
974 .Pp
975 To load
976 .Nm
977 without any configuration
978 .Bd -literal -offset indent
979 telescope -c /dev/null
980 .Ed
981 .Sh STANDARDS
982 .Rs
983 .%B XDG Base Directory Specification
984 .%U https://specifications.freedesktop.org/basedir-spec/latest/
985 .Re
986 .Sh ACKNOWLEDGEMENTS
987 The
988 .Dq Trust, but verify (where appropriate)
989 TOFU scheme was firstly suggested by thfr:
990 .Lk gemini://thfr.info/gemini/modified-trust-verify.gmi .
991 .Sh AUTHORS
992 .An -nosplit
993 The
994 .Nm
995 program was written by
996 .An Omar Polo Aq Mt op@omarpolo.com .
997 .Sh CAVEATS
998 .Nm
999 assumes a UTF-8 environment and doesn't try to cope with other encodings.
1000 This can cause strange rendering issues if you're lucky, or possibly
1001 weird thing happening depending on your locale and terminal emulator.
1002 .Pp
1003 The algorithm used for text-wrapping is naive and doesn't really work for
1004 languages that make heavily use of glyphs composed by multiple UNICODE
1005 codepoints.
1006 .Sh BUGS
1007 There's no UI for out-of-band certificates validation.