.\" 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 Chnv .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 xxxxxxxxxxxxx .It Fl C , Fl -colors Show all available colors and exit. .It Fl c Pa config Specify an alternative configuration file. By default .Pa $HOME/.telescope/config is loaded. .It Fl h , Fl -help Display version and usage. .It Fl n Configtest mode. Only check the configuration file for validity. .It Fl v , Fl -version Display version. .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 { 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 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 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 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 M-l link-select .It M-/ swiper .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 C-p previous-completion .It C-n next-completion .It previous-completion .It next-completion .It tab insert-current-candidate .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 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. .It Ic tab-select Switch to a tab using the minibuffer. .El .Ss Misc commands .Bl -tag -width execute-extended-command -compact .It Ic clear-minibuf Clears the echo area. .It Ic dec-fill-column Decrements fill-column by two. .It Ic execute-extended-command Prompts for a command name using the minibuffer. .It Ic kill-telescope Quit .Nm . .It Ic inc-fill-column Increments fill-column by two. .It Ic link-select Select and visit a link using the minibuffer. .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, 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 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 reload-page Reload the current page. .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 Select and jump to a heading of the page 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. .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 .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 variable , if available. .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 dont-wrap-pre .Pq integer If nonzero, don't wrap preformatted blocks. .It emojify-link .Pq integer If not zero, when the text of a link starts with an emoji followed by a space, use that emoji as line prefix. Defaults to 1. .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 hide-pre-blocks .Pq integer If nonzero, hide by default the body of the preformatted blocks. By default is zero. .Ic push-button can be used to toggle the visibility per-block. .It hide-pre-closing-line .Pq integer If nonzero, hide the closing line of preformatted blocks. .It 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. By default is zero. .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 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 16m -compact -offset Ds .It line for the area outside the lines in the body of the page. .It line.compl for the completion in the minibuffer .It line.compl.current for the current completion .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. .It minibuffer for the minibuffer .Dq i.e. the last line of the window .It modeline for the modeline .Dq i.e. the info line right above the minibuffer .It tabline for the tabline. .It tabline.tab for the non-focused tabs. .It tabline.current for 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 styles under 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 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/lock Lock file used to prevent multiple instance of .Nm from running at the same time. .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 # enable colors regardless of $NO_COLOR set enable-colors = 1 style line.item { prefix " • " " " } style line.link { prefix "→ " " " } style line.quote { prefix " ┃ " } .Ed .Pp 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 ~/.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 .