.\" Copyright (c) 2021 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: March 28 2021$ .Dt TELESCOPE 1 .Os .Sh NAME .Nm telescope .Nd Gemini client .Sh SYNOPSIS .Nm .Bk -words .Op Fl hn .Op Fl c Pa config .Op Ar URL .Ek .Sh DESCRIPTION .Nm is an interactive browser for the Gemini protocol. It is able to process text/gemini and more in general every text/* file. .Nm also features tabs, bookmarks and out-of-band TOFU verification. .Pp The arguments are as follows: .Bl -tag -width tenletters .It Fl h Display version and usage. .It Fl n Configtest mode. Only check the configuration file for validity. .It Fl c Pa config Specify an alternative configuration file. By default .Pa $HOME/.telescope/config is loaded. .El .Sh TOFU .Nm aims to use the "Trust, but Verify (where appropriate)" approach. The idea is to define three level of verification for a certificate: .Bl -tag -width 12m .It untrusted the server fingerprint does NOT match the stored value .It trusted the server fingerprint matches the store one .It verified the fingerprint matches and has been verified out-of-band .El .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. .Pp Known certificates are store in .Pa ~/.telescope/known_hosts with a format similar to the .Xr ssh 1 Ns ' .Pa known_hosts file. Each line is a record and it's made up by three fields, separated by a single space, according to the following format: .Dq HOST HASH TRUSTED where: .Bl -tag -width 12m .It HOST the hostname, optionally followed by a colon (":") and a port number. .It HASH is the hash of the certificate, as outputted by .Xr tls_peer_cert_hash 3 . .It TRUSTED a single digit. 0 means trusted, 1 verified. .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 is shift tab though. .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-g clear-minibuf .It M-x execute-extended-command .It C-c p previous-heading .It C-c n next-heading .It > load-url .It C-x C-f load-url .It C-x M-f load-current-url .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 C-M-b previous-page .It C-M-f next-page .It a bookmark-page .It list-bookmarks .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 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 scroll-up .It scroll-down .It M- previous-page .It M- next-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 .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 M-p mini-previous-history-element .It M-n mini-next-history-element .It mini-previous-history-element .It mini-next-history-element .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 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-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-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 Add a link to 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. .El .Ss Misc commands .Bl -tag -width execute-extended-command -compact .It Ic clear-minibuf Clears the echo area. .It Ic execute-extended-command Prompts for a command name using the minibuffer. .It Ic kill-telescope Quit .Nm . .It Ic load-current-url Prompts for an URL, the minibuffer is preloaded with the current one. .It Ic load-url Prompts for an URL. .It Ic next-page Load the next item in the history list. .It Ic olivetti-mode Toggle olivetti mode (i.e. horizontal centering of the lines of the window.) .It Ic previous-page Load the previous item in the history list. .It Ic push-button Follow the link on the current line. .It Ic push-button-new-tab Follow the link on the current line on a new tab. .It Ic redraw Redraw the screen, useful if some background program messed up the display. .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 toggle-help Toggle side window with help about available keys and their associated interactive command. .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-kill-line Delete from the point until the end of the 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 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 .El .Sh CONFIGURATION FILE During the startup, .Nm reads the configuration file at .Pa ~/.telescope/config or the one given with the .Fl c flag. .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 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 enable-colors .Pq integer If not zero, enable colours. By default is 1 if .Ev NO_COLORS is not set, 0 otherwise. .It 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. By default is 80. .It new-tab-url .Pq string URL for the new tab page. By default is .Dq about:new . .It olivetti-mode .Pq integer Enable .Ic olivetti-mode if non zero. By default is 1. .El .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 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 14m -compact -offset Ds .It line.text for text lines .It line.link for link lines .It line.title1..3 for headings .It line.item for item lines .It line.quote for quotes .It line.pre.start for the heading of a preformatted block .It line.pre for the content of a preformatted block .It line.pre.end for the closing line of a preformatted block .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 .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. Supported colors are: default, black, red, green, yellow, blue, magenta, cyan and white .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 given line 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 FILES .Bl -tag -width Ds -compact .It Pa ~/.telescope/bookmarks.gmi Holds the bookmarks. .It Pa ~/.telescope/config Default configuration file. .It Pa ~/.telescope/known_hosts Contains a list of host keys for all the hosts the user has visited. See the TOFU section for more info. .It Pa ~/.telescope/session Contains the list of opened tabs in the last session, one per line. Gets written on .Ic kill-telescope and loaded on startup. .El .Sh EXAMPLES The following is my config file: .Bd -literal -offset indent # ignore the NO_COLOR environment variable set enable-colors = 1 style line.item { prefix " • " " " } style line.link { prefix "→ " " " fg blue attr normal underline } style line.quote { prefix " ┃ " } .Ed .Pp It's possible to browse .Dq the small web .Pq i.e. simple websites using programs like the duckling-proxy by defining a proxy in .Pa ~/.telescope/config : .Bd -literal -offset indent proxy http via "gemini://localhost:1965" proxy https via "gemini://localhost:1965" .Ed .Pp To load .Nm without any configuration use .Bd -literal -offset indent telescope -c /dev/null .Ed .Sh AUTHORS .An -nosplit The .Nm program was written by .An Omar Polo Aq Mt op@omarpolo.com .