telescope
—
multi-protocol browser
telescope |
[-Chnv ]
[-c config]
[URL] |
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
,
--colors
- Show all available colors and exit.
-c
config
- Specify an alternative configuration file. By default
$HOME/.telescope/config is loaded.
-h
,
--help
- Display version and usage.
-n
- Configtest mode. Only check the configuration file for validity.
-v
,
--version
- Display version.
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.
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.
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.
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.
- 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
- 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
- q
- kill-telescope
- ESC
- clear-minibuf
- :
- execute-extended-command
- <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
- M-<left>
- previous-page
- M-<right>
- next-page
- <f5>
- reload-page
- r
- reload-page
- <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
- 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
Follows the documentation for the interactive commands. These
commands can be bound to a key or executed with
execute-extended-command
.
bookmark-page
- Save a page in the bookmark file. It preloads the minibuffer with the
current URL.
list-bookmarks
- Load the bookmarks page.
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.
During the startup, telescope
reads the
configuration file at ~/.telescope/config or the one
given with 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.
- 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.
- 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”.
- olivetti-mode
- (integer) If nonzero, enable
olivetti-mode
Defaults to 1.
- set-title
- (integer) If nonzero, set the terminal title to the page title.
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.
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.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.
- 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.
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.
- ~/.telescope/bookmarks.gmi
- Bookmarks file.
- ~/.telescope/config
- Default configuration file.
- ~/.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.
- ~/.telescope/lock
- Lock file used to prevent multiple instance of
telescope
from running at the same time.
- ~/.telescope/pages/about_*.gmi
- Overrides for built-in about: pages.
- ~/.telescope/session
- The list of tabs from the last session. Every line identifies a tab and
contains three space-separated fields: the full URL, a comma-separated
list of attributes and the cached title. Is written by
kill-telescope
and loaded during startup.
It's possible to browse “the small web” (i.e. simple
websites) by using programs like the duckling-proxy by defining a proxy in
~/.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
There's no UI for out-of-band certificates validation.