aboutsummaryrefslogtreecommitdiff
path: root/site/telescope.1.txt
diff options
context:
space:
mode:
Diffstat (limited to 'site/telescope.1.txt')
-rw-r--r--site/telescope.1.txt583
1 files changed, 583 insertions, 0 deletions
diff --git a/site/telescope.1.txt b/site/telescope.1.txt
new file mode 100644
index 0000000..855e913
--- /dev/null
+++ b/site/telescope.1.txt
@@ -0,0 +1,583 @@
+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
+
+ 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.
+ 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:
+ 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.0 January 5, 2022 OpenBSD 7.0