Blob


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