💾 Archived View for telescope.omarpolo.com › telescope.1.txt captured on 2022-04-28 at 18:46:11.
⬅️ Previous capture (2022-03-01)
-=-=-=-=-=-=-
TELESCOPE(1) General Commands Manual TELESCOPE(1)
NAME
telescope multi-protocol browser
SYNOPSIS
telescope [-ChnSv] [-c config] [URL]
DESCRIPTION
telescope is an interactive browser that supports the Finger, Gemini and
Gopher protocols. telescope features tabs, a minibuffer, interactive
completions, bookmarks and out-of-band TOFU verification.
The arguments are as follows:
-C, --colours Show all available colors and exit. This option can also
be spelled --colors.
-c config Specify an alternative configuration file. By default
~/.config/telescope/config is loaded.
-h, --help Display version, usage and exit.
-n Configtest mode. Only check the configuration file for
validity.
-S, --safe Safe (or sandbox) mode. Prevent telescope from
writing files to the disk and to acquire the lock,
allowing to run multiple instances at the same time.
telescope still loads the session file and the custom
about pages.
-v, --version Display version and exit.
UI CONCEPTS
telescope interface is divided into four areas: the tabline, the body,
the modeline and the echoarea/minibuffer.
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 < or > are shown at the
start/end of the tabline to indicate that there are more tabs in that
direction.
The body occupies the majority of the visible area. It contains the
current page and optionally a side window.
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, the document type, the scroll offset and the URL.
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 swiper or link-select are
invoked, the minibuffer area grows to show possible completions.
TOFU
telescope aims to use the Trust, but Verify (where appropriate)
approach for TOFU (Trust On First Use). The idea is to define three
level of verification for a certificate:
untrusted (!) the server fingerprint does NOT match the stored
value.
trusted (v) the server fingerprint matches the store one.
verified (V) the fingerprint matches and has been verified out-of-
band.
The trust level of the page is indicated in the modeline with the
indicated character.
Most of the time the trusted level is enough, but where is appropriate
users should be able to verify out-of-band the certificate.
At the moment, there is no built-in support for an out-of-band
verification though.
SUPPORTED PROTOCOLS
The following protocols are supported:
about: About pages are telescope internal page. See about:about for
a list of all these pages.
file:// File types know to telescope, 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 OpenBSD, only
files inside special directories (like /tmp or ~/Downloads)
are available.
finger:// Finger URLs are interpreted as follows:
the host is determined by the host name portion of the URL
if the user portion of the URL is provided, it's
interpreted as the user to finger, otherwise the path
component will be used
thus finger://user@hostname and finger://hostname/user are
treated as the same URL.
gemini:// Gemini is fully supported, with the exception of client-
certificates.
gopher:// Gopher support is limited to items type 0, 1 and 7. All text
is assumed to be encoded in UTF-8 (or ASCII).
User-entered URLs, given as argument on the command line or entered with
load-url, are intepreted with a simple heuristic:
if it's a proper absolute URL then use it as-is,
if it starts with ./ or / assume it's a file:// URL,
otherwise assume it's a Gemini URL.
CONFIGURATION FILE
During the startup, telescope reads the configuration file at
~/.config/telescope/config or ~/.telescope/config.
It's possible to load a custom configuration file using the -c flag.
telescope will also load a file called config-TERM, where TERM is the
name of the terminal type (i.e. the TERM environment variable), if it
exists.
The format of the configuration file is fairly flexible. The current
line can be extended over multiple ones using a backslash (\).
Comments can be put anywhere in the file using a hash mark (#), and
extend to the end of the current line, but backslashes can't be used to
extend comments over multiple lines.
The following constructs are available:
bind map key cmd
Bind key to the function cmd in the keymap map. Valid values for
map are global-map (i.e. when the user is viewing a page) and
minibuffer-map (i.e. when the minibuffer has the focus.) key
follows the same syntax described in DEFAULT KEY BINDINGS and all
the possible functions are listed in INTERACTIVE COMMANDS.
proxy proto via url
Use url as proxy for all URLs with protocol proto. url must be a
Gemini URI without path, query and fragment component.
set opt = val
Set the option opt to the value val. Valid options are:
autosave (integer) If greater than zero, save the session
after the specified amount of seconds after some
events happens (new or closed tabs, visited a link
...) Defaults to 20.
dont-wrap-pre (integer) If nonzero, don't wrap preformatted
blocks. Defaults to 0.
download-path (string) The default download path. Defaults to
/tmp.
emojify-link (integer) If nonzero, when the text of a link
starts with an emoji followed by a space, use that
emoji as line prefix. Defaults to 1.
enable-colors (integer) If nonzero, enable colours. Defaults to
0 if NO_COLORS is set, 1 otherwise.
fill-column (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.
fringe-ignore-offset
(integer) If nonzero, the fringe doesn't obey to
olivetti-mode. Defaults to 1.
hide-pre-blocks
(integer) If nonzero, hide by default the body of
the preformatted blocks. Defaults to zero.
push-button can be used to toggle the visibility
per-block.
hide-pre-closing-line
(integer) If nonzero, hide the closing line of
preformatted blocks. Defaults to 0.
hide-pre-context
(integer) If nonzero, hide the start and end line
of the preformatted blocks. If both hide-pre-
context and hide-pre-blocks are nonzero,
preformatted blocks are irremediably hidden.
Defaults to zero.
new-tab-url (string) URL for the new tab page. Defaults to
about:new.
max-killed-tabs
(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.
olivetti-mode (integer) If nonzero, enable olivetti-mode
Defaults to 1.
tab-bar-show (integer) If tab-bar-show is -1 hide the tab bar
permanently, if 0 show it unconditionally. If
it's 1, show the bar only when there is more than
one tab. Defaults to 1.
update-title (integer) If nonzero, set the terminal title to
the page title. Defaults to 1.
style name option
Change the styling of the element identified by name. Multiple
options may be specified within curly braces. Valid style
identifiers are:
line the area outside the lines in the
body of the page.
line.compl the completions.
line.compl.current the current completion.
line.help text in the *Help* buffer.
line.download.ongoing an ongoing download
line.download.done a completed download
line.download.info informational text in the
*Downloads* buffer.
line.fringe (virtual) lines draw after the end
of a buffer.
line.text text lines.
line.link link lines.
line.title1..3 headings
line.item item lines.
line.quote quotes.
line.pre.start the heading of a preformatted block.
line.pre the content of a preformatted block.
line.pre.end the closing line of a preformatted
block.
download the download pane
minibuffer the minibuffer.
modeline the modeline.
tabline the tabline.
tabline.tab the non-focused tabs.
tabline.current the focused tab.
Valid options are:
attr prefix [line [trail]]
Sets the text attributes. If only one value is given,
line and trail default to that; if two values are given
then trail defaults to prefix. Each attribute is a
comma-separated list of keywords:
normal no attributes.
standout best highlighting mode for the terminal.
underline underlines the text.
reverse reverses background/foreground colors.
blink makes the text blinking.
dim half bright.
bold extra bright or bold.
Only the style identifiers with the line. prefix accept
up to three attributes. The other will only use the
first one given.
bg prefix [line [trail]]
Sets the background color. Follows the same behaviour as
attr regarding the optional parameters. The colour is
one of black, red, green, yellow, blue, magenta, cyan and
white; colour0 to colour255 (or color0 to color255) from
the 256-colour set; default for the default colour.
fg prefix [line [trail]]
Sets the foreground color. It behaves just like bg.
prefix prfx [cont]
Sets the prefix for the current line type to prfx and
cont as the prefix for the continuation lines (i.e. when
a long line gets wrapped.) If cont is not given its value
will be the same of prfx.
DEFAULT KEY BINDINGS
The default key bindings are very similar to GNU Emacs, but care has been
taken to include also bindings familiar for vi(1) and 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.
Keys are usually a single character, like p or n, but some special
keys are accepted as well.
<up> Up arrow
<down> Down arrow
<left> Left arrow
<right> Right arrow
<prior> Previous page/Page up
<next> Next page/Page down
<home> Home
<end> End
<f0> thru <f63> Function keys
del or backspace Backspace
esc Escape
space or spc Space
enter or ret Enter
tab Tab
backtab Depends on the configuration of the terminal
emulator; usually shift tab.
GNU Emacs-like keys
C-p previous-line
C-n next-line
C-f forward-char
C-b backward-char
M-{ backward-paragraph
M-} forward-paragraph
C-a move-beginning-of-line
C-e move-end-of-line
M-v, M-space scroll-up
C-v, space scroll-down
M-< beginning-of-buffer
M-> end-of-buffer
C-x C-c kill-telescope
C-g clear-minibuf
M-x execute-extended-command
C-c { dec-fill-column
C-c } inc-fill-column
C-c p previous-heading
C-c n next-heading
> load-url
< load-current-url
C-x C-f load-url
C-x M-f load-current-url
C-x o other-window
C-x t 0 tab-close
C-x t 1 tab-close-other
C-x t 2 tab-new
C-x t o tab-next
C-x t O tab-previous
C-x t m tab-move
C-x t M tab-move-to
B, C-M-b previous-page
F, C-M-f next-page
<f7> a bookmark-page
<f7> <f7> list-bookmarks
C-z suspend-telescope
vi(1)-like keys
k previous-line
j next-line
l forward-char
h backward-char
{ backward-paragraph
} forward-paragraph
^ move-beginning-of-line
$ move-end-of-line
K scroll-line-up
J scroll-line-down
g g beginning-of-buffer
G end-of-buffer
g D tab-close
g N tab-new
g t tab-next
g T tab-previous
g M-t tab-move
g M-T tab-move-to
H previous-page
L next-page
u tab-undo-close
q kill-telescope
ESC clear-minibuf
: execute-extended-command
CUA-like keys
<up> previous-line
<down> next-line
<right> forward-char
<left> backward-char
<home> move-beginning-of-line
<end> move-end-of-line
<prior> scroll-up
<next> scroll-down
C-w tab-close
C-t tab-new
M-<prior> tab-previous
M-<next> tab-next
del previous-page
M-<left> previous-page
M-<right> next-page
<f5> reload-page
r reload-page
Neither Emacs nor vi specific
<f1> toggle-help
enter push-button
M-enter push-button-new-tab
M-tab previous-button
backtab previous-button
tab next-button
M-t tab-select
[ tab-previous
] tab-next
M-[ tab-move-to
M-] tab-move
M-l link-select
M-/ swiper
M-r reply-last-input
Minibuffer-specific keys
enter mini-complete-and-exit
C-g mini-abort
ESC mini-abort
C-d mini-delete-char
del mini-delete-backward-char
backspace mini-delete-backward-char
C-h mini-delete-backward-char
C-b backward-char
C-f forward-char
<left> backward-char
<right> forward-char
C-e move-end-of-line
C-a move-beginning-of-line
<end> move-end-of-line
<home> move-beginning-of-line
C-k mini-kill-line
M-p mini-previous-history-element
M-n mini-next-history-element
C-p previous-completion
C-n next-completion
<up> previous-completion
<down> next-completion
tab insert-current-candidate
M-< mini-goto-beginning
M-> mini-goto-end
INTERACTIVE COMMANDS
Follows the documentation for the interactive commands. These commands
can be bound to a key or executed with execute-extended-command.
Movement commands
backward-char Move point one character backward.
backward-paragraph Move point one paragraph backward.
beginning-of-buffer Move point to the beginning of the buffer.
end-of-buffer Move point to the end of the buffer.
forward-char Move point one character forward.
forward-paragraph Move point one paragraph forward.
insert-current-candidate Copy the current selection text as minibuffer
input.
move-beginning-of-line Move point at the beginning of the current
(visual) line.
move-end-of-line Move point at the end of the current (visual)
line.
next-button Move point to the next link.
next-completion Select the next completion.
next-heading Move point to the next heading.
next-line Move point to the next (visual) line, in the
same column if possible.
previous-button Move point to the previous link.
previous-completion Select the previous completion.
previous-heading Move point to the previous heading.
previous-line Move point to the previous (visual) line.
Bookmark-related commands
bookmark-page Save a page in the bookmark file. It preloads
the minibuffer with the current URL.
list-bookmarks Load the bookmarks page.
Tab-related commands
tab-close Close the current tab.
tab-close-other Close all tabs but the current one.
tab-move Move the current tab after the next one,
wrapping around if needed.
tab-move-to Move the current tab before the previous one,
wrapping around if needed.
tab-new Open a new tab.
tab-next Focus next tab, wrapping around eventually.
tab-previous Focus the previous tab, wrapping around
eventually.
tab-select Switch to a tab using the minibuffer.
tab-undo-close Re-open the most recently closed tab, if any.
Misc commands
cache-info Show cache stats.
clear-minibuf Clear the echo area.
dec-fill-column Decrement fill-column by two.
execute-extended-command Execute an internal command.
kill-telescope Quit telescope.
inc-fill-column Increment fill-column by two.
link-select Select and visit a link using the minibuffer.
load-current-url Edit the current URL.
load-url Prompt for an URL.
next-page Go forward in the page history.
olivetti-mode Toggle olivetti mode (i.e. horizontal centering
of the lines of the window.)
other-window Select the other window.
previous-page Go backward in the page history.
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.
push-button-new-tab Follow link at point in a new tab.
redraw Redraw the screen, useful if some background
program messed up the display.
reload-page Reload the current page.
reply-last-input Reply the last input request.
scroll-down Scroll down by one visual page.
scroll-line-down Scroll down by one line.
scroll-line-up Scroll up by one line.
scroll-up Scroll up by one visual page.
suspend-telescope Suspend the current telescope session.
swiper Jump to a line using the minibuffer.
toc Jump to a heading using the minibuffer.
toggle-help Toggle side window with help about available
keys and their associated interactive command.
toggle-pre-wrap Toggle the wrapping of preformatted blocks.
Minibuffer commands
mini-abort Abort the current minibuffer action.
mini-complete-and-exit Complete the current minibuffer action.
mini-delete-backward-char
Delete the character before the point.
mini-delete-char Delete the character after the point.
mini-goto-beginning Select the first completion, if any.
mini-goto-end Select the last completion, if any.
mini-kill-line Delete from point until the end of the line.
mini-next-history-element
Load the previous history element.
mini-previous-history-element
Load the next history element.
Aliases
The following aliases are available during execute-extended-command:
open load-url
tabn tab-next
tabnew tab-new
tabp tab-previous
q and wq kill-telescope
ENVIRONMENT
When telescope is started, it inspects the following environment
variables:
HOME The user's login directory.
NO_COLORS To decide whether to use colors or not. The content of the
variable doesn't matter.
TERM The user's terminal name.
XDG_CACHE_HOME, XDG_CONFIG_HOME, XDG_DATA_HOME
If defined can alter the default location of the files used.
FILES
By default telescope follows the XDG Base Directory Specification.
However, if ~/.telescope exists, XDG is ignored and all the files are
stored inside it. The usage of XDG_CACHE_HOME, XDG_CONFIG_HOME and
XDG_DATA_HOME can further alter the location of these files.
~/.config/telescope/config
Default configuration file.
~/.local/share/telescope/pages/about_*.gmi
Overrides for built-in about: pages.
~/.local/share/telescope/bookmarks.gmi
Bookmarks file.
~/.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.
~/.cache/telescope/lock
Lock file used to prevent multiple instance of telescope from
running at the same time.
~/.cache/telescope/session
The list of tabs from the last session.
EXAMPLES
It's possible to browse the small web (i.e. simple websites) by using
programs like the duckling-proxy by defining a proxy in
~/.config/telescope/config:
proxy http via "gemini://127.0.0.1:1965"
proxy https via "gemini://127.0.0.1:1965"
To load telescope without any configuration
telescope -c /dev/null
STANDARDS
XDG Base Directory Specification,
https://specifications.freedesktop.org/basedir-spec/latest/.
ACKNOWLEDGEMENTS
The Trust, but verify (where appropriate) TOFU scheme was firstly
suggested by thfr: gemini://thfr.info/gemini/modified-trust-verify.gmi.
AUTHORS
The telescope program was written by Omar Polo <op@omarpolo.com>.
CAVEATS
telescope 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.
The algorithm used for text-wrapping is naive and doesn't really work for
languages that make heavily use of glyphs composed by multiple UNICODE
codepoints.
BUGS
There's no UI for out-of-band certificates validation.
OpenBSD 7.1 January 5, 2022 OpenBSD 7.1