telescope.1

.\" Copyright (c) 2021, 2022, 2024 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: February 23 2024$
.Dt TELESCOPE 1
.Os
.Sh NAME
.Nm telescope
.Nd multi-protocol browser
.Sh SYNOPSIS
.Nm
.Bk -words
.Op Fl hnSv
.Op Fl c Ar config
.Op Ar URL
.Ek
.Sh DESCRIPTION
.Nm
is a browser that supports the Finger, Gemini and Gopher protocols.
.Nm
features tabs, a minibuffer, interactive completions, bookmarks and
client certificates.
.Pp
The arguments are as follows:
.Bl -tag -width xxxxxxxxxxxxx
.It Fl c Ar config
Specify an alternative configuration file.
By default
.Pa ~/.config/telescope/config
is loaded.
.It Fl h , Fl -help
Display version, usage and exit.
.It Fl n
Configtest mode.
Only check the configuration file for validity.
.It Fl S , Fl -safe
.Dq Safe
.Pq or Dq sandbox
mode.
Prevent
.Nm
from writing files to the disk and to acquire the lock, allowing to
run multiple instances at the same time.
.Nm
still loads the session file and the custom about pages.
.It Fl v , Fl -version
Display version and exit.
.El
.Sh UI CONCEPTS
.Nm
interface is divided into four areas: the tabline, the body, the
modeline and the echoarea/minibuffer.
.Pp
The tabline is always at the top of the screen and displays the tabs
separated by a vertical line.
When there are more tabs than the size of the window allow to display,
the characters
.Sq \&<
or
.Sq \&>
are shown at the start/end of the tabline to indicate that there are
more tabs in that direction.
.Pp
The body occupies the majority of the visible area.
It contains the current page and optionally a side window.
.Pp
The modeline is the second to last row of the screen.
It shows some information about the page: a spinner when the page is
loading, the trust level, whether a client certificate is in use, a
warning indicator for faulty Gemini servers, document type, the
scroll offset and the URL.
When a client certificate is in use, a
.Sq C
character is showed.
Some Gemini servers have buggy TLS handling but some information might
still be available.
This information could be truncated.
In those circumstances, a
.Sq W
character is shown.
.Pp
The echoarea is usually the last line of the screen.
Messages are often showed there, and link addresses too.
The echoarea is also used to obtain input from the user.
When commands like
.Ic swiper
or
.Ic link-select
are invoked, the minibuffer area grows to show possible completions.
.Sh TOFU
.Nm
aims to use the
.Dq Trust, but Verify Pq where appropriate
approach for
TOFU
.Pq Dq Trust On First Use .
The idea is to define three level of verification for a certificate:
.Bl -tag -width 12m
.It untrusted
.Pq Sq \&!
the server fingerprint does not match the stored value.
.It trusted
.Pq Sq v
the server fingerprint matches the store one.
.It verified
.Pq Sq V
the fingerprint matches and has been verified out-of-band.
.El
.Pp
The trust level of the page is indicated in the modeline with the
indicated character.
.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.
.Sh SUPPORTED PROTOCOLS
The following protocols are supported:
.Bl -tag -width gemini://
.It about:
About pages are
.Nm
internal page.
See about:about for a list of all these pages.
.It file://
File types know to
.Nm ,
such as .gmi, .gemini, .txt, .md, .markdown, .diff or .patch, can be
viewed inside the application.
Types of local files are detected solely based on the file extension.
On some systems, such as
.Ox ,
only files inside special directories
.Pq like Pa /tmp No or Pa ~/Downloads
are available.
.It finger://
Finger URLs are interpreted as follows:
.Bl -bullet -compact
.It
the host is determined by the host name portion of the URL
.It
if the user portion of the URL is provided, it's interpreted as the
user to finger, otherwise the path component will be used
.El
thus
.Lk finger://user@hostname
and
.Lk finger://hostname/user
are treated as the same URL.
.It gemini://
Gemini is fully supported.
.It gopher://
Gopher support is limited to items type 0, 1 and 7.
All text is assumed to be encoded in UTF-8 (superset of ASCII).
.El
.Pp
User-entered URLs, given as argument on the command line or entered
with
.Ic load-url ,
by default are interpreted with a simple heuristic:
.Bl -bullet -compact
.It
if it's a proper absolute URL then use it as-is,
.It
if it starts with
.Dq ./
or
.Dq /
assume it's a file:// URL,
.It
otherwise treat it like a hostname with protocol
.Ic default-protocol
.Pq gemini by default .
.El
.Pp
The setting
.Ic load-url-use-heuristic
can be used to disable the use of heuristics.
.Sh MIME-TYPE HANDLING
Beyond the supported protocols which
.Nm
already understands, mime-types which
.Nm
cannot display can be opened using a
.Pa mailcap
file.
By default,
.Nm
will look for one of the following mailcap files in the following order:
.Pp
.Bl -tag -width Ds -compact
.It Pa ~/.mailcap
.It Pa /etc/mailcap
.It Pa /usr/etc/mailcap
.It Pa /usr/local/etc/mailcap
.El
.Pp
A default mailcap entry is always defined by
.Nm
which uses
.Xr xdg-open 1
as a fallback for mime-types not defined through a mailcap file, or if no
mailcap file was found.
.Pp
Refer to RFC 1524 for more information about the structure and format of this
file.
Note that
.Nm
currently only supports a small subset of this standard, honouring only the
.Pa needsterminal
and
.Pa copiousouput
flags.
.Sh CONFIGURATION FILE
During the startup,
.Nm
reads the configuration file at
.Pa ~/.config/telescope/config
or
.Pa ~/.telescope/config .
.Pp
It's possible to load a custom configuration file using the
.Fl c
flag.
.Pp
.Nm
will also load a file called
.Pa config-TERM ,
where
.Dq TERM
is the name of the terminal type
.Pq i.e. the TERM environment variable ,
if it exists.
.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 Ic autosave
.Pq integer
If greater than zero, save the session after the specified amount of
seconds after some events happened
.Pq new or closed tabs, visited a link ...
Defaults to 20.
.It Ic default-protocol
.Pq string
The default protocol assumed for the
.Ic load-url
heuristic.
Defaults to
.Dq gemini .
.It Ic default-search-engine
.Pq string
URL of the preferred search engine, used by the
.Cm search
command.
If it's a Gemini URI, the user query will be appended as query,
replacing it if present.
If it's a Gopher URI, the user query will be sent as gopher search
parameter.
No other URI scheme are allowed.
.It Ic dont-wrap-pre
.Pq boolean
If true, don't wrap preformatted blocks.
Defaults to false.
.It Ic download-path
.Pq string
The default download path.
Defaults to
.Pa /tmp .
.It Ic emojify-link
.Pq boolean
If true, when the text of a link starts with an emoji followed by a
space, use that emoji as line prefix.
Defaults to true.
.It Ic enable-colors
.Pq boolean
If true, enable colours.
Defaults to false if
.Ev NO_COLORS
is set, true otherwise.
.It Ic 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.
Defaults to 80.
.It Ic fringe-ignore-offset
.Pq boolean
If true, the fringe doesn't obey to
.Ic olivetti-mode .
Defaults to false.
.It Ic hide-pre-blocks
.Pq boolean
If true, hide by default the body of the preformatted blocks.
Defaults to false.
.Ic push-button
can be used to toggle the visibility per-block.
.It Ic hide-pre-closing-line
.Pq boolean
If true, hide the closing line of preformatted blocks.
Defaults to false.
.It Ic hide-pre-context
.Pq boolean
If true, hide the start and end line of the preformatted blocks.
If both
.Ic hide-pre-context
and
.Ic hide-pre-blocks
are true, preformatted blocks are irremediably hidden.
Defaults to false.
.It Ic new-tab-url
.Pq string
URL for the new tab page.
Defaults to
.Dq about:new .
.It Ic load-url-use-heuristic
.Pq boolean
If false, don't use heuristics to resolve the URLs.
Non-absolute URLs given as command line argument will be resolved as
file system paths,
.Ic load-url
will resolve as relative to the current URL.
Defaults to true.
.It Ic max-killed-tabs
.Pq integer
The maximum number of closed tabs to keep track of, defaults to 10.
Must be a positive number; if zero, don't save closed tabs at all.
.It Ic olivetti-mode
.Pq boolean
If true, enable
.Ic olivetti-mode .
Defaults to true.
.It Ic tab-bar-show
.Pq integer
If tab-bar-show is -1 hide the tab bar permanently, if 0 show it
unconditionally.
If 1, show the bar only when there is more than one tab.
Defaults to 1.
.It Ic update-title
.Pq boolean
If true, set the terminal title to the page title.
Defaults to true.
.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 line.download.ongoing -compact -offset Ds
.It line
the area outside the lines in the body of the page.
.It line.compl
the completions.
.It line.compl.current
the current completion.
.It line.help
text in the *Help* buffer.
.It line.download.ongoing
an ongoing download
.It line.download.done
a completed download
.It line.download.info
informational text in the *Downloads* buffer.
.It line.fringe
.Pq virtual
lines draw after the end of a buffer.
.It line.text
text lines.
.It line.link
link lines.
.It line.title1..3
headings
.It line.item
item lines.
.It line.quote
quotes.
.It line.pre.start
the heading of a preformatted block.
.It line.pre
the content of a preformatted block.
.It line.pre.end
the closing line of a preformatted block.
.It download
the download pane
.It minibuffer
the minibuffer.
.It modeline
the modeline.
.It tabline
the tabline.
.It tabline.tab
the non-focused tabs.
.It tabline.current
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 style identifiers with 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 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 shift
tab.
.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-x C-w
write-buffer
.It C-g
clear-minibuf
.It M-x
execute-extended-command
.It C-c {
dec-fill-column
.It C-c }
inc-fill-column
.It C-c p
previous-heading
.It C-c n
next-heading
.It >
load-url
.It <
load-current-url
.It C-x C-f
load-url
.It C-x M-f
load-current-url
.It C-x o
other-window
.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 B, C-M-b
previous-page
.It F, C-M-f
next-page
.It <f7> a
bookmark-page
.It <f7> <f7>
list-bookmarks
.It C-z
suspend-telescope
.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 u
up
.It g r
root
.It g h
home
.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 u
tab-undo-close
.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 <home>
move-beginning-of-line
.It <end>
move-end-of-line
.It <prior>
scroll-up
.It <next>
scroll-down
.It C-w
tab-close
.It C-t
tab-new
.It M-<prior>
tab-previous
.It M-<next>
tab-next
.It del
previous-page
.It M-<left>
previous-page
.It M-<right>
next-page
.It <f5>
reload-page
.It r
reload-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
.It M-t
tab-select
.It \&[
tab-previous
.It \&]
tab-next
.It M-\&[
tab-move-to
.It M-\&]
tab-move
.It M-l
link-select
.It M-/
swiper
.It M-r
reply-last-input
.It s
search
.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-x
mini-edit-external
.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 C-u
mini-kill-whole-line
.It M-p
mini-previous-history-element
.It M-n
mini-next-history-element
.It C-p
previous-completion
.It C-n
next-completion
.It <up>
previous-completion
.It <down>
next-completion
.It tab
insert-current-candidate
.It M-<
mini-goto-beginning
.It M->
mini-goto-end
.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 insert-current-candidate
Copy the current selection text as minibuffer input.
.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-completion
Select the next completion.
.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-completion
Select the previous completion.
.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
Save a page in the bookmark file.
It preloads the minibuffer with the current URL.
.It Ic list-bookmarks
Load the bookmarks page.
.El
.Ss Client certificate-related commands
.Bl -tag -width execute-extended-command -compact
.It Ic client-certificate-info
Show the active client certificate.
.It Ic unload-certificate
Forget the certificate on this page.
.It Ic use-certificate
Use a certificate for the current 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.
.It Ic tab-select
Switch to a tab using the minibuffer.
.It Ic tab-undo-close
Re-open the most recently closed tab, if any.
.El
.Ss Misc commands
.Bl -tag -width execute-extended-command -compact
.It Ic cache-info
Show cache stats.
.It Ic clear-minibuf
Clear the echo area.
.It Ic dec-fill-column
Decrement fill-column by two.
.It Ic execute-extended-command
Execute an internal command.
.It Ic home
Go to the home directory.
The home directory is assumed to be the first path component in the
.Sy ~username
form.
If not found, loads the root directory.
.It Ic kill-telescope
Quit
.Nm .
.It Ic inc-fill-column
Increment fill-column by two.
.It Ic link-select
Select and visit a link using the minibuffer.
.It Ic load-current-url
Edit the current URL.
.It Ic load-url
Prompt for an URL.
Use the same heuristic as the URLs given as a command-line argument,
unless the
.Ic load-url-use-heuristic
option is unsed, in which case the URL is resolved using the current
one as base.
.It Ic next-page
Go forward in the page history.
.It Ic olivetti-mode
Toggle olivetti mode (i.e. horizontal centering of the lines of the
window.)
.It Ic other-window
Select the other window.
.It Ic previous-page
Go backward in the page history.
.It Ic push-button
Follow link at point, or toggle the visibility of the following
preformatted block if called when the cursor is on the heading of the block.
.It Ic push-button-new-tab
Follow link at point in a new tab.
.It Ic redraw
Redraw the screen, useful if some background program messed up the
display.
.It Ic reload-page
Reload the current page.
.It Ic reply-last-input
Reply the last input request.
.It Ic root
Go to the root directory.
.It Ic search
Search using the preferred search engine.
.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 suspend-telescope
Suspend the current
.Nm
session.
.It Ic swiper
Jump to a line using the minibuffer.
.It Ic toc
Jump to a heading using the minibuffer.
.It Ic toggle-help
Toggle side window with help about available keys and their associated
interactive command.
.It Ic toggle-pre-wrap
Toggle the wrapping of preformatted blocks.
.It Ic toggle-styling
Toggle the styling of the page.
This remains in effect until toggled again.
.It Ic up
Go up one level in the path hierarchy.
.It Ic write-buffer
Save the current buffer to the disk.
.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-edit-external
Edit the minibuffer contents with an editor.
.It Ic mini-goto-beginning
Select the first completion, if any.
.It Ic mini-goto-end
Select the last completion, if any.
.It Ic mini-kill-line
Delete from point until the end of the line.
.It Ic mini-kill-whole-line
Delete the whole 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 open
.Ic load-url
.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
.It Ic w
.Ic write-buffer
.El
.Sh ENVIRONMENT
When
.Nm
is started, it inspects the following environment variables:
.Bl -tag -width NO_COLORS
.It Ev HOME
The user's login directory.
.It Ev NO_COLORS
To decide whether to use colors or not.
The content of the variable doesn't matter.
.It Ev TERM
The user's terminal name.
.It Ev VISUAL , Ev EDITOR
The editor spawned by the
.Ic mini-edit-external
command.
If not set,
.Xr ed 1
the standard text editor is used.
.It Ev XDG_CACHE_HOME , Ev XDG_CONFIG_HOME , Ev XDG_DATA_HOME
If defined can alter the default location of the files used.
.El
.Sh FILES
By default
.Nm
follows the XDG Base Directory Specification.
However, if
.Pa ~/.telescope
exists, XDG is ignored and all the files are stored inside it.
The usage of
.Ev XDG_CACHE_HOME ,
.Ev XDG_CONFIG_HOME
and
.Ev XDG_DATA_HOME
can further alter the location of these files.
.Pp
.Bl -tag -width Ds -compact
.It Pa ~/.config/telescope/config
Default configuration file.
.It Pa ~/.config/telescope/certs.conf
URLs to client certificate mappings.
.It Pa ~/.local/share/telescope/pages/about_*.gmi
Overrides for built-in about: pages.
.It Pa ~/.local/share/telescope/bookmarks.gmi
Bookmarks file.
.It Pa ~/.local/share/telescope/certs/
Directory where client certificates
.Pq identities
are stored.
.It Pa ~/.local/share/telescope/known_hosts
Hash of the certificates for all the known hosts.
Each line contains three fields: hostname with optional port number,
hash of the certificate and a numeric flag.
.It Pa ~/.cache/telescope/lock
Lock file used to prevent multiple instance of
.Nm
from running at the same time.
.It Pa ~/.cache/telescope/session
The list of tabs from the last session.
.El
.Sh EXAMPLES
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 ~/.config/telescope/config :
.Bd -literal -offset indent
proxy http via "gemini://127.0.0.1:1965"
proxy https via "gemini://127.0.0.1:1965"
.Ed
.Pp
To load
.Nm
without any configuration
.Bd -literal -offset indent
$ telescope -c /dev/null
.Ed
.Sh SEE ALSO
.Xr telescope-identity 1
.Xr xdg-open 1
.Sh STANDARDS
.Rs
.%B XDG Base Directory Specification
.%U https://specifications.freedesktop.org/basedir-spec/latest/
.Re
.Sh ACKNOWLEDGEMENTS
The
.Dq Trust, but verify (where appropriate)
TOFU scheme was firstly suggested by thfr:
.Lk gemini://thfr.info/gemini/modified-trust-verify.gmi .
.Sh AUTHORS
.An -nosplit
The
.Nm
program was written by
.An Omar Polo Aq Mt op@omarpolo.com .
.Sh CAVEATS
.Nm
assumes a UTF-8 environment and doesn't try to cope with other encodings.
This can cause strange rendering issues if you're lucky, or possibly
weird thing happening depending on your locale and terminal emulator.
.Sh BUGS
There's no UI for out-of-band certificates validation.