.\" Copyright (c) 2021, 2022 Omar Polo .\" .\" 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: January 05 2022$ .Dt TELESCOPE 1 .Os .Sh NAME .Nm telescope .Nd multi-protocol browser .Sh SYNOPSIS .Nm .Bk -words .Op Fl ChnSv .Op Fl c Ar config .Op Ar URL .Ek .Sh DESCRIPTION .Nm is an interactive browser that supports the Finger, Gemini and Gopher protocols. .Nm features tabs, a minibuffer, interactive completions, bookmarks and out-of-band TOFU verification. .Pp The arguments are as follows: .Bl -tag -width xxxxxxxxxxxxx .It Fl C , Fl -colours Show all available colors and exit. This option can also be spelled .Fl -colors . .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, the document type, the scroll offset and the URL. .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, with the exception of client-certificates. .It gopher:// Gopher support is limited to items type 0, 1 and 7. All text is assumed to be encoded in UTF-8 (or ASCII). .El .Pp User-entered URLs, given as argument on the command line or entered with .Ic load-url , are intepreted 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 assume it's a Gemini URL. .El .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 happens .Pq new or closed tabs, visited a link ... Defaults to 20. .It Ic dont-wrap-pre .Pq integer If nonzero, don't wrap preformatted blocks. Defaults to 0. .It Ic download-path .Pq string The default download path. Defaults to .Pa /tmp . .It Ic emojify-link .Pq 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. .It Ic enable-colors .Pq integer If nonzero, enable colours. Defaults to 0 if .Ev NO_COLORS is set, 1 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 integer If nonzero, the fringe doesn't obey to .Ic olivetti-mode . Defaults to 1. .It Ic hide-pre-blocks .Pq integer If nonzero, hide by default the body of the preformatted blocks. Defaults to zero. .Ic push-button can be used to toggle the visibility per-block. .It Ic hide-pre-closing-line .Pq integer If nonzero, hide the closing line of preformatted blocks. Defaults to 0. .It Ic hide-pre-context .Pq 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. .It Ic new-tab-url .Pq string URL for the new tab page. Defaults to .Dq about:new . .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 integer If nonzero, enable .Ic olivetti-mode Defaults to 1. .It Ic tab-bar-show .Pq 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. .It Ic update-title .Pq integer If nonzero, set the terminal title to the page title. Defaults to 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 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 arrow .It Down arrow .It Left arrow .It Right arrow .It Previous page/Page up .It Next page/Page down .It Home .It End .It thru 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 a bookmark-page .It 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 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 previous-line .It next-line .It forward-char .It backward-char .It move-beginning-of-line .It move-end-of-line .It scroll-up .It scroll-down .It C-w tab-close .It C-t tab-new .It M- tab-previous .It M- tab-next .It del previous-page .It M- previous-page .It M- next-page .It reload-page .It r reload-page .El .Ss Neither Emacs nor vi specific .Bl -tag -width xxxxxxxxxxxx -offset indent -compact .It 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 .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 backward-char .It forward-char .It C-e move-end-of-line .It C-a move-beginning-of-line .It move-end-of-line .It 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 previous-completion .It 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 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 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. .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 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 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-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 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 ~/.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/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 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. .Pp 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. .Sh BUGS There's no UI for out-of-band certificates validation.