aboutsummaryrefslogtreecommitdiff
path: root/telescope.1
blob: cfac1ccfba1560946f1cdaa0f54bfc5cea03c037 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
.\" Copyright (c) 2021 Omar Polo <op@omarpolo.com>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.Dd $Mdocdate: March 28 2021$
.Dt TELESCOPE 1
.Os
.Sh NAME
.Nm telescope
.Nd Gemini client
.Sh SYNOPSIS
.Nm
.Bk -words
.Op Fl hn
.Op Fl c Pa config
.Op Ar URL
.Ek
.Sh DESCRIPTION
.Nm
is an interactive browser for the Gemini protocol.
It is able to process text/gemini and more in general every text/* file.
.Nm
also features tabs, bookmarks and out-of-band TOFU verification.
.Pp
The arguments are as follows:
.Bl -tag -width tenletters
.It Fl h
Display version and usage.
.It Fl n
Configtest mode.
Only check the configuration file for validity.
.It Fl c Pa config
Specify an alternative configuration file.
By default
.Pa $HOME/.telescope/config
is loaded.
.El
.Sh TOFU
.Nm
aims to use the "Trust, but Verify (where appropriate)" approach.
The idea is to define three level of verification for a certificate:
.Bl -tag -width 12m
.It untrusted
the server fingerprint does NOT match the stored value
.It trusted
the server fingerprint matches the store one
.It verified
the fingerprint matches and has been verified out-of-band
.El
.Pp
Most of the time the
.Dq trusted
level is enough, but where is appropriate users should be able to
verify out-of-band the certificate.
.Pp
At the moment, there is no built-in support for an out-of-band
verification though.
.Pp
Known certificates are store in
.Pa ~/.telescope/known_hosts
with a format similar to the
.Xr ssh 1 Ns '
.Pa known_hosts
file.
Each line is a record and it's made up by three fields, separated by a
single space, according to the following format:
.Dq HOST HASH TRUSTED
where:
.Bl -tag -width 12m
.It HOST
the hostname, optionally followed by a colon (":") and a port number.
.It HASH
is the hash of the certificate, as outputted by
.Xr tls_peer_cert_hash 3 .
.It TRUSTED
a single digit.
0 means trusted, 1 verified.
.El
.Sh DEFAULT KEY BINDINGS
The default key bindings are very similar to GNU Emacs, but care has
been taken to include also bindings familiar for
.Xr vi 1
and
.Dq CUA
users.
In the following examples, C-x means Control-x, M-x means Meta-x,
where the Meta key may be either a special key on the keyboard or the
ALT key; otherwise ESC followed by the key X works as well, and C-M-x
means to press the key X together with both Control and Meta.
.Pp
Keys are usually a single character, like
.Sq p
or
.Sq n ,
but some special keys are accepted as well.
.Pp
.Bl -tag -width 16m -offset indent -compact
.It <up>
Up arrow
.It <down>
Down arrow
.It <left>
Left arrow
.It <right>
Right arrow
.It <prior>
Previous page/Page up
.It <next>
Next page/Page down
.It <home>
Home
.It <end>
End
.It <f0> thru <f63>
Function keys
.It del or backspace
Backspace
.It esc
Escape
.It space or spc
Space
.It enter or ret
Enter
.It tab
Tab
.It backtab
Depends on the configuration of the terminal emulator.
Usually is shift tab though.
.El
.Ss GNU Emacs-like keys
.Bl -tag -width xxxxxxxxxxxx -offset indent -compact
.It C-p
previous-line
.It C-n
next-line
.It C-f
forward-char
.It C-b
backward-char
.It M-{
backward-paragraph
.It M-}
forward-paragraph
.It C-a
move-beginning-of-line
.It C-e
move-end-of-line
.It M-v, M-space
scroll-up
.It C-v, space
scroll-down
.It M-<
beginning-of-buffer
.It M->
end-of-buffer
.It C-x C-c
kill-telescope
.It C-g
clear-minibuf
.It M-x
execute-extended-command
.It C-c p
previous-heading
.It C-c n
next-heading
.It >
load-url
.It C-x C-f
load-url
.It C-x M-f
load-current-url
.It C-x t 0
tab-close
.It C-x t 1
tab-close-other
.It C-x t 2
tab-new
.It C-x t o
tab-next
.It C-x t O
tab-previous
.It C-x t m
tab-move
.It C-x t M
tab-move-to
.It C-M-b
previous-page
.It C-M-f
next-page
.It <f7> a
bookmark-page
.It <f7> <f7>
list-bookmarks
.El
.Ss Xr vi 1 Ns -like keys
.Bl -tag -width xxxxxxxxxxxx -offset indent -compact
.It k
previous-line
.It j
next-line
.It l
forward-char
.It h
backward-char
.It {
backward-paragraph
.It }
forward-paragraph
.It ^
move-beginning-of-line
.It $
move-end-of-line
.It K
scroll-line-up
.It J
scroll-line-down
.It g g
beginning-of-buffer
.It G
end-of-buffer
.It g D
tab-close
.It g N
tab-new
.It g t
tab-next
.It g T
tab-previous
.It g M-t
tab-move
.It g M-T
tab-move-to
.It H
previous-page
.It L
next-page
.It q
kill-telescope
.It ESC
clear-minibuf
.It :
execute-extended-command
.El
.Ss CUA-like keys
.Bl -tag -width xxxxxxxxxxxx -offset indent -compact
.It <up>
previous-line
.It <down>
next-line
.It <right>
forward-char
.It <left>
backward-char
.It <prior>
scroll-up
.It <next>
scroll-down
.It M-<left>
previous-page
.It M-<right>
next-page
.El
.Ss Neither Emacs nor vi specific
.Bl -tag -width xxxxxxxxxxxx -offset indent -compact
.It <f1>
toggle-help
.It enter
push-button
.It M-enter
push-button-new-tab
.It M-tab
previous-button
.It backtab
previous-button
.It tab
next-button
.El
.Ss Minibuffer-specific keys
.Bl -tag -width xxxxxxxxxxxx -offset indent -compact
.It enter
mini-complete-and-exit
.It C-g
mini-abort
.It ESC
mini-abort
.It C-d
mini-delete-char
.It del
mini-delete-backward-char
.It backspace
mini-delete-backward-char
.It C-h
mini-delete-backward-char
.It C-b
backward-char
.It C-f
forward-char
.It <left>
backward-char
.It <right>
forward-char
.It C-e
move-end-of-line
.It C-a
move-beginning-of-line
.It <end>
move-end-of-line
.It <home>
move-beginning-of-line
.It C-k
mini-kill-line
.It M-p
mini-previous-history-element
.It M-n
mini-next-history-element
.It <up>
mini-previous-history-element
.It <down>
mini-next-history-element
.El
.Sh INTERACTIVE COMMANDS
Follows the documentation for the interactive commands.
These commands can be bound to a key or executed with
.Ic execute-extended-command .
.Ss Movement commands
.Bl -tag -width execute-extended-command -compact
.It Ic backward-char
Move point one character backward.
.It Ic backward-paragraph
Move point one paragraph backward.
.It Ic beginning-of-buffer
Move point to the beginning of the buffer.
.It Ic end-of-buffer
Move point to the end of the buffer.
.It Ic forward-char
Move point one character forward.
.It Ic forward-paragraph
Move point one paragraph forward.
.It Ic move-beginning-of-line
Move point at the beginning of the current (visual) line.
.It Ic move-end-of-line
Move point at the end of the current (visual) line.
.It Ic next-button
Move point to the next link.
.It Ic next-heading
Move point to the next heading.
.It Ic next-line
Move point to the next (visual) line, in the same column if possible.
.It Ic previous-button
Move point to the previous link.
.It Ic previous-heading
Move point to the previous heading.
.It Ic previous-line
Move point to the previous (visual) line.
.El
.Ss Bookmark-related commands
.Bl -tag -width execute-extended-command -compact
.It Ic bookmark-page
Add a link to the bookmark file.
It preloads the minibuffer with the current URL.
.It Ic list-bookmarks
Load the bookmarks page.
.El
.Ss Tab-related commands
.Bl -tag -width execute-extended-command -compact
.It Ic tab-close
Close the current tab.
.It Ic tab-close-other
Close all tabs but the current one.
.It Ic tab-move
Move the current tab after the next one, wrapping around if
needed.
.It Ic tab-move-to
Move the current tab before the previous one, wrapping around if needed.
.It Ic tab-new
Open a new tab.
.It Ic tab-next
Focus next tab, wrapping around eventually.
.It Ic tab-previous
Focus the previous tab, wrapping around eventually.
.El
.Ss Misc commands
.Bl -tag -width execute-extended-command -compact
.It Ic clear-minibuf
Clears the echo area.
.It Ic execute-extended-command
Prompts for a command name using the minibuffer.
.It Ic kill-telescope
Quit
.Nm .
.It Ic load-current-url
Prompts for an URL, the minibuffer is preloaded with the current
one.
.It Ic load-url
Prompts for an URL.
.It Ic next-page
Load the next item in the history list.
.It Ic olivetti-mode
Toggle olivetti mode (i.e. horizontal centering of the lines of the
window.)
.It Ic previous-page
Load the previous item in the history list.
.It Ic push-button
Follow the link on the current line.
.It Ic push-button-new-tab
Follow the link on the current line on a new tab.
.It Ic redraw
Redraw the screen, useful if some background program messed up the
display.
.It Ic scroll-down
Scroll down by one visual page.
.It Ic scroll-line-down
Scroll down by one line.
.It Ic scroll-line-up
Scroll up by one line.
.It Ic scroll-up
Scroll up by one visual page.
.It Ic toggle-help
Toggle side window with help about available keys and their associated
interactive command.
.El
.Ss Minibuffer commands
.Bl -tag -width execute-extended-command -compact
.It Ic mini-abort
Abort the current minibuffer action.
.It Ic mini-complete-and-exit
Complete the current minibuffer action.
.It Ic mini-delete-backward-char
Delete the character before the point.
.It Ic mini-delete-char
Delete the character after the point.
.It Ic mini-kill-line
Delete from the point until the end of the line.
.It Ic mini-next-history-element
Load the previous history element.
.It Ic mini-previous-history-element
Load the next history element.
.El
.Ss Aliases
The following aliases are available during
.Ic execute-extended-command :
.Bl -tag -width 16m -compact
.It Ic tabn
.Ic tab-next
.It Ic tabnew
.Ic tab-new
.It Ic tabp
.Ic tab-previous
.It Ic q No and Ic wq
.Ic kill-telescope
.El
.Sh CONFIGURATION FILE
During the startup,
.Nm
reads the configuration file at
.Pa ~/.telescope/config
or the one given with the
.Fl c
flag.
.Pp
The format of the configuration file is fairly flexible.
The current line can be extended over multiple ones using a
backslash
.Pq Sq \e .
Comments can be put anywhere in the file using a hash mark
.Pq Sq # ,
and extend to the end of the current line, but backslashes can't be
used to extend comments over multiple lines.
.Pp
The following constructs are available:
.Bl -tag -width Ds
.It Ic bind Ar map Ar key Ar cmd
Bind
.Ar key
to the function
.Ar cmd
in the keymap
.Ar map .
Valid values for map are
.Dq global-map
.Pq i.e. when the user is viewing a page
and
.Dq minibuffer-map
.Pq i.e. when the minibuffer has the focus.
.Ar key
follows the same syntax described in
.Sx DEFAULT KEY BINDINGS
and all the possible functions are listed in
.Sx INTERACTIVE COMMANDS .
.It Ic proxy Ar proto Ic via Ar url
Use
.Ar url
as proxy for all URLs with
protocol
.Ar proto .
.Ar url
must be a Gemini URI without path, query and fragment component.
.It Ic set Ar opt No = Ar val
Set the option
.Ar opt
to the value
.Ar val .
Valid options are:
.Pp
.Bl -tag -width twelveletters -compact
.It enable-colors
.Pq integer
If not zero, enable colours.
By default is 1 if
.Ev NO_COLORS
is not set, 0 otherwise.
.It fill-column
.Pq integer
If greater than zero, lines of text will be formatted in a way that
don't exceed the given number of columns.
By default is 80.
.It new-tab-url
.Pq string
URL for the new tab page.
By default is
.Dq about:new .
.It olivetti-mode
.Pq integer
Enable
.Ic olivetti-mode
if non zero.
By default is 1.
.El
.It Ic style Ar name Ar option
Change the styling of the element identified by
.Ar name .
Multiple options may be specified within curly braces.
Valid style identifiers are:
.Bl -tag -width 16m -compact -offset Ds
.It line
for the area outside the lines in the body of the page.
.It line.text
for text lines.
.It line.link
for link lines.
.It line.title1..3
for headingse
.It line.item
for item lines.
.It line.quote
for quotes.
.It line.pre.start
for the heading of a preformatted block.
.It line.pre
for the content of a preformatted block.
.It line.pre.end
for the closing line of a preformatted block.
.It minibuffer
for the minibuffer
.Dq i.e. the last line of the window
.It modeline
for the modeline
.Dq i.e. the info line right above the minibuffer
.It tabline
for the tabline.
.It tabline.tab
for the non-focused tabs.
.It tabline.current
for the focused tab.
.El
.Pp
Valid options are:
.Bl -tag -width Ds
.It Ic attr Ar prefix Oo Ar line Oo Ar trail Oc Oc
Sets the text attributes.
If only one value is given,
.Ar line
and
.Ar trail
default to that; if two values are given then
.Ar trail
defaults to
.Ar prefix .
Each attribute is a comma-separated list of keywords:
.Bl -tag -width underline -compact -offset Ds
.It Ic normal
no attributes.
.It Ic standout
best highlighting mode for the terminal.
.It Ic underline
underlines the text.
.It Ic reverse
reverses background/foreground colors.
.It Ic blink
makes the text blinking.
.It Ic dim
half bright.
.It Ic bold
extra bright or bold.
.El
.Pp
Only the styles under the
.Dq line.
prefix accept up to three attributes.
The other will only use the first one given.
.It Ic bg Ar prefix Oo Ar line Oo Ar trail Oc Oc
Sets the background color.
Follows the same behaviour as
.Ic attr
regarding the optional parameters.
The colour is one of black, red, green, yellow, blue,
magenta, cyan and white; colour0 to colour255
.Pq or color0 to color255
from the 256-colour set;
default for the default colour.
.It Ic fg Ar prefix Oo Ar line Oo Ar trail Oc Oc
Sets the foreground color.
It behaves just like
.Ic bg .
.It Ic prefix Ar prfx Op Ar cont
Sets the prefix for the current line type to
.Ar prfx
and
.Ar cont
as the prefix for the continuation lines
.Pq i.e. when a long line gets wrapped.
If
.Ar cont
is not given its value will be the same of
.Ar prfx .
.El
.El
.Sh FILES
.Bl -tag -width Ds -compact
.It Pa ~/.telescope/bookmarks.gmi
Holds the bookmarks.
.It Pa ~/.telescope/config
Default configuration file.
.It Pa ~/.telescope/known_hosts
Contains a list of host keys for all the hosts the user has visited.
See the TOFU section for more info.
.It Pa ~/.telescope/session
Contains the list of opened tabs in the last session, one per line.
Gets written on
.Ic kill-telescope
and loaded on startup.
.El
.Sh EXAMPLES
The following is my config file:
.Bd -literal -offset indent
# enable colors regardless of $NO_COLOR
set enable-colors = 1

style line.item {
	prefix " • " "   "
}

style line.link {
	prefix "→ " "  "
}

style line.quote {
	prefix " ┃ "
}
.Ed
.Pp
It's possible to browse
.Dq the small web
.Pq i.e. simple websites
by using programs like the duckling-proxy by defining a proxy in
.Pa ~/.telescope/config :
.Bd -literal -offset indent
proxy http via "gemini://localhost:1965"
proxy https via "gemini://localhost:1965"
.Ed
.Pp
To load
.Nm
without any configuration use
.Bd -literal -offset indent
telescope -c /dev/null
.Ed
.Sh AUTHORS
.An -nosplit
The
.Nm
program was written by
.An Omar Polo Aq Mt op@omarpolo.com .