Blob
Date:
Fri Apr 15 09:13:28 2022
UTC
Message:
add mini-kill-whole-line
.\" Copyright (c) 2021, 2022 Omar Polo <op@omarpolo.com>.\".\" 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.Nmis an interactive browser that supports the Finger, Gemini and Gopherprotocols..Nmfeatures tabs, a minibuffer, interactive completions, bookmarks andout-of-band TOFU verification..PpThe arguments are as follows:.Bl -tag -width xxxxxxxxxxxxx.It Fl C , Fl -coloursShow all available colors and exit.This option can also be spelled.Fl -colors ..It Fl c Ar configSpecify an alternative configuration file.By default.Pa ~/.config/telescope/configis loaded..It Fl h , Fl -helpDisplay version, usage and exit..It Fl nConfigtest mode.Only check the configuration file for validity..It Fl S , Fl -safe.Dq Safe.Pq or Dq sandboxmode.Prevent.Nmfrom writing files to the disk and to acquire the lock, allowing torun multiple instances at the same time..Nmstill loads the session file and the custom about pages..It Fl v , Fl -versionDisplay version and exit..El.Sh UI CONCEPTS.Nminterface is divided into four areas: the tabline, the body, themodeline and the echoarea/minibuffer..PpThe tabline is always at the top of the screen and displays the tabsseparated 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 aremore tabs in that direction..PpThe body occupies the majority of the visible area.It contains the current page and optionally a side window..PpThe modeline is the second to last row of the screen.It shows some information about the page: a spinner when the page isloading, the trust level, the document type, the scroll offset and theURL..PpThe 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 swiperor.Ic link-selectare invoked, the minibuffer area grows to show possible completions..Sh TOFU.Nmaims to use the.Dq Trust, but Verify Pq where appropriateapproach forTOFU.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 vthe server fingerprint matches the store one..It verified.Pq Sq Vthe fingerprint matches and has been verified out-of-band..El.PpThe trust level of the page is indicated in the modeline with theindicated character..PpMost of the time the.Dq trustedlevel is enough, but where is appropriate users should be able toverify out-of-band the certificate..PpAt the moment, there is no built-in support for an out-of-bandverification though..Sh SUPPORTED PROTOCOLSThe following protocols are supported:.Bl -tag -width gemini://.It about:About pages are.Nminternal 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 beviewed 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 ~/Downloadsare available..It finger://Finger URLs are interpreted as follows:.Bl -bullet -compact.Itthe host is determined by the host name portion of the URL.Itif the user portion of the URL is provided, it's interpreted as theuser to finger, otherwise the path component will be used.Elthus.Lk finger://user@hostnameand.Lk finger://hostname/userare 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.PpUser-entered URLs, given as argument on the command line or enteredwith.Ic load-url ,are intepreted with a simple heuristic:.Bl -bullet -compact.Itif it's a proper absolute URL then use it as-is,.Itif it starts with.Dq ./or.Dq /assume it's a file:// URL,.Itotherwise assume it's a Gemini URL..El.Sh CONFIGURATION FILEDuring the startup,.Nmreads the configuration file at.Pa ~/.config/telescope/configor.Pa ~/.telescope/config ..PpIt's possible to load a custom configuration file using the.Fl cflag..Pp.Nmwill also load a file called.Pa config-TERM ,where.Dq TERMis the name of the terminal type.Pq i.e. the TERM environment variable ,if it exists..PpThe format of the configuration file is fairly flexible.The current line can be extended over multiple ones using abackslash.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 beused to extend comments over multiple lines..PpThe following constructs are available:.Bl -tag -width Ds.It Ic bind Ar map Ar key Ar cmdBind.Ar keyto the function.Ar cmdin the keymap.Ar map .Valid values for map are.Dq global-map.Pq i.e. when the user is viewing a pageand.Dq minibuffer-map.Pq i.e. when the minibuffer has the focus..Ar keyfollows the same syntax described in.Sx DEFAULT KEY BINDINGSand all the possible functions are listed in.Sx INTERACTIVE COMMANDS ..It Ic proxy Ar proto Ic via Ar urlUse.Ar urlas proxy for all URLs withprotocol.Ar proto ..Ar urlmust be a Gemini URI without path, query and fragment component..It Ic set Ar opt No = Ar valSet the option.Ar optto the value.Ar val .Valid options are:.Pp.Bl -tag -width twelveletters -compact.It Ic autosave.Pq integerIf greater than zero, save the session after the specified amount ofseconds after some events happens.Pq new or closed tabs, visited a link ...Defaults to 20..It Ic dont-wrap-pre.Pq integerIf nonzero, don't wrap preformatted blocks.Defaults to 0..It Ic download-path.Pq stringThe default download path.Defaults to.Pa /tmp ..It Ic emojify-link.Pq integerIf nonzero, when the text of a link starts with an emoji followed by aspace, use that emoji as line prefix.Defaults to 1..It Ic enable-colors.Pq integerIf nonzero, enable colours.Defaults to 0 if.Ev NO_COLORSis set, 1 otherwise..It Ic fill-column.Pq integerIf greater than zero, lines of text will be formatted in a way thatdon't exceed the given number of columns.Defaults to 80..It Ic fringe-ignore-offset.Pq integerIf nonzero, the fringe doesn't obey to.Ic olivetti-mode .Defaults to 1..It Ic hide-pre-blocks.Pq integerIf nonzero, hide by default the body of the preformatted blocks.Defaults to zero..Ic push-buttoncan be used to toggle the visibility per-block..It Ic hide-pre-closing-line.Pq integerIf nonzero, hide the closing line of preformatted blocks.Defaults to 0..It Ic hide-pre-context.Pq integerIf nonzero, hide the start and end line of the preformatted blocks.If both hide-pre-context and hide-pre-blocks are nonzero, preformattedblocks are irremediably hidden.Defaults to zero..It Ic new-tab-url.Pq stringURL for the new tab page.Defaults to.Dq about:new ..It Ic max-killed-tabs.Pq integerThe 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 integerIf nonzero, enable.Ic olivetti-modeDefaults to 1..It Ic tab-bar-show.Pq integerIf tab-bar-show is -1 hide the tab bar permanently, if 0 show itunconditionally.If it's 1, show the bar only when there is more than one tab.Defaults to 1..It Ic update-title.Pq integerIf nonzero, set the terminal title to the page title.Defaults to 1..El.It Ic style Ar name Ar optionChange 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 linethe area outside the lines in the body of the page..It line.complthe completions..It line.compl.currentthe current completion..It line.helptext in the *Help* buffer..It line.download.ongoingan ongoing download.It line.download.donea completed download.It line.download.infoinformational text in the *Downloads* buffer..It line.fringe.Pq virtuallines draw after the end of a buffer..It line.texttext lines..It line.linklink lines..It line.title1..3headings.It line.itemitem lines..It line.quotequotes..It line.pre.startthe heading of a preformatted block..It line.prethe content of a preformatted block..It line.pre.endthe closing line of a preformatted block..It downloadthe download pane.It minibufferthe minibuffer..It modelinethe modeline..It tablinethe tabline..It tabline.tabthe non-focused tabs..It tabline.currentthe focused tab..El.PpValid options are:.Bl -tag -width Ds.It Ic attr Ar prefix Oo Ar line Oo Ar trail Oc OcSets the text attributes.If only one value is given,.Ar lineand.Ar traildefault to that; if two values are given then.Ar traildefaults to.Ar prefix .Each attribute is a comma-separated list of keywords:.Bl -tag -width underline -compact -offset Ds.It Ic normalno attributes..It Ic standoutbest highlighting mode for the terminal..It Ic underlineunderlines the text..It Ic reversereverses background/foreground colors..It Ic blinkmakes the text blinking..It Ic dimhalf bright..It Ic boldextra bright or bold..El.PpOnly 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 OcSets the background color.Follows the same behaviour as.Ic attrregarding the optional parameters.The colour is one of black, red, green, yellow, blue,magenta, cyan and white; colour0 to colour255.Pq or color0 to color255from the 256-colour set;default for the default colour..It Ic fg Ar prefix Oo Ar line Oo Ar trail Oc OcSets the foreground color.It behaves just like.Ic bg ..It Ic prefix Ar prfx Op Ar contSets the prefix for the current line type to.Ar prfxand.Ar contas the prefix for the continuation lines.Pq i.e. when a long line gets wrapped.If.Ar contis not given its value will be the same of.Ar prfx ..El.El.Sh DEFAULT KEY BINDINGSThe default key bindings are very similar to GNU Emacs, but care hasbeen taken to include also bindings familiar for.Xr vi 1and.Dq CUAusers.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 theALT key; otherwise ESC followed by the key X works as well, and C-M-xmeans to press the key X together with both Control and Meta..PpKeys are usually a single character, like.Sq por.Sq n ,but some special keys are accepted as well..Pp.Bl -tag -width 16m -offset indent -compact.It <up>Up arrow.It <down>Down arrow.It <left>Left arrow.It <right>Right arrow.It <prior>Previous page/Page up.It <next>Next page/Page down.It <home>Home.It <end>End.It <f0> thru <f63>Function keys.It del or backspaceBackspace.It escEscape.It space or spcSpace.It enter or retEnter.It tabTab.It backtabDepends on the configuration of the terminal emulator; usually shifttab..El.Ss GNU Emacs-like keys.Bl -tag -width xxxxxxxxxxxx -offset indent -compact.It C-pprevious-line.It C-nnext-line.It C-fforward-char.It C-bbackward-char.It M-{backward-paragraph.It M-}forward-paragraph.It C-amove-beginning-of-line.It C-emove-end-of-line.It M-v, M-spacescroll-up.It C-v, spacescroll-down.It M-<beginning-of-buffer.It M->end-of-buffer.It C-x C-ckill-telescope.It C-x C-wwrite-buffer.It C-gclear-minibuf.It M-xexecute-extended-command.It C-c {dec-fill-column.It C-c }inc-fill-column.It C-c pprevious-heading.It C-c nnext-heading.It >load-url.It <load-current-url.It C-x C-fload-url.It C-x M-fload-current-url.It C-x oother-window.It C-x t 0tab-close.It C-x t 1tab-close-other.It C-x t 2tab-new.It C-x t otab-next.It C-x t Otab-previous.It C-x t mtab-move.It C-x t Mtab-move-to.It B, C-M-bprevious-page.It F, C-M-fnext-page.It <f7> abookmark-page.It <f7> <f7>list-bookmarks.It C-zsuspend-telescope.El.Ss Xr vi 1 Ns -like keys.Bl -tag -width xxxxxxxxxxxx -offset indent -compact.It kprevious-line.It jnext-line.It lforward-char.It hbackward-char.It {backward-paragraph.It }forward-paragraph.It ^move-beginning-of-line.It $move-end-of-line.It Kscroll-line-up.It Jscroll-line-down.It g gbeginning-of-buffer.It Gend-of-buffer.It g Dtab-close.It g Ntab-new.It g ttab-next.It g Ttab-previous.It g M-ttab-move.It g M-Ttab-move-to.It Hprevious-page.It Lnext-page.It utab-undo-close.It qkill-telescope.It ESCclear-minibuf.It :execute-extended-command.El.Ss CUA-like keys.Bl -tag -width xxxxxxxxxxxx -offset indent -compact.It <up>previous-line.It <down>next-line.It <right>forward-char.It <left>backward-char.It <home>move-beginning-of-line.It <end>move-end-of-line.It <prior>scroll-up.It <next>scroll-down.It C-wtab-close.It C-ttab-new.It M-<prior>tab-previous.It M-<next>tab-next.It delprevious-page.It M-<left>previous-page.It M-<right>next-page.It <f5>reload-page.It rreload-page.El.Ss Neither Emacs nor vi specific.Bl -tag -width xxxxxxxxxxxx -offset indent -compact.It <f1>toggle-help.It enterpush-button.It M-enterpush-button-new-tab.It M-tabprevious-button.It backtabprevious-button.It tabnext-button.It M-ttab-select.It \&[tab-previous.It \&]tab-next.It M-\&[tab-move-to.It M-\&]tab-move.It M-llink-select.It M-/swiper.It M-rreply-last-input.El.Ss Minibuffer-specific keys.Bl -tag -width xxxxxxxxxxxx -offset indent -compact.It entermini-complete-and-exit.It C-gmini-abort.It ESCmini-abort.It C-dmini-delete-char.It delmini-delete-backward-char.It backspacemini-delete-backward-char.It C-hmini-delete-backward-char.It C-bbackward-char.It C-fforward-char.It <left>backward-char.It <right>forward-char.It C-emove-end-of-line.It C-amove-beginning-of-line.It <end>move-end-of-line.It <home>move-beginning-of-line.It C-kmini-kill-line.It C-umini-kill-whole-line.It M-pmini-previous-history-element.It M-nmini-next-history-element.It C-pprevious-completion.It C-nnext-completion.It <up>previous-completion.It <down>next-completion.It tabinsert-current-candidate.It M-<mini-goto-beginning.It M->mini-goto-end.El.Sh INTERACTIVE COMMANDSFollows 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-charMove point one character backward..It Ic backward-paragraphMove point one paragraph backward..It Ic beginning-of-bufferMove point to the beginning of the buffer..It Ic end-of-bufferMove point to the end of the buffer..It Ic forward-charMove point one character forward..It Ic forward-paragraphMove point one paragraph forward..It Ic insert-current-candidateCopy the current selection text as minibuffer input..It Ic move-beginning-of-lineMove point at the beginning of the current (visual) line..It Ic move-end-of-lineMove point at the end of the current (visual) line..It Ic next-buttonMove point to the next link..It Ic next-completionSelect the next completion..It Ic next-headingMove point to the next heading..It Ic next-lineMove point to the next (visual) line, in the same column if possible..It Ic previous-buttonMove point to the previous link..It Ic previous-completionSelect the previous completion..It Ic previous-headingMove point to the previous heading..It Ic previous-lineMove point to the previous (visual) line..El.Ss Bookmark-related commands.Bl -tag -width execute-extended-command -compact.It Ic bookmark-pageSave a page in the bookmark file.It preloads the minibuffer with the current URL..It Ic list-bookmarksLoad the bookmarks page..El.Ss Tab-related commands.Bl -tag -width execute-extended-command -compact.It Ic tab-closeClose the current tab..It Ic tab-close-otherClose all tabs but the current one..It Ic tab-moveMove the current tab after the next one, wrapping around ifneeded..It Ic tab-move-toMove the current tab before the previous one, wrapping around if needed..It Ic tab-newOpen a new tab..It Ic tab-nextFocus next tab, wrapping around eventually..It Ic tab-previousFocus the previous tab, wrapping around eventually..It Ic tab-selectSwitch to a tab using the minibuffer..It Ic tab-undo-closeRe-open the most recently closed tab, if any..El.Ss Misc commands.Bl -tag -width execute-extended-command -compact.It Ic cache-infoShow cache stats..It Ic clear-minibufClear the echo area..It Ic dec-fill-columnDecrement fill-column by two..It Ic execute-extended-commandExecute an internal command..It Ic kill-telescopeQuit.Nm ..It Ic inc-fill-columnIncrement fill-column by two..It Ic link-selectSelect and visit a link using the minibuffer..It Ic load-current-urlEdit the current URL..It Ic load-urlPrompt for an URL..It Ic next-pageGo forward in the page history..It Ic olivetti-modeToggle olivetti mode (i.e. horizontal centering of the lines of thewindow.).It Ic other-windowSelect the other window..It Ic previous-pageGo backward in the page history..It Ic push-buttonFollow link at point, or toggle the visibility of the followingpreformatted block if called when the cursor is on the heading of the block..It Ic push-button-new-tabFollow link at point in a new tab..It Ic redrawRedraw the screen, useful if some background program messed up thedisplay..It Ic reload-pageReload the current page..It Ic reply-last-inputReply the last input request..It Ic scroll-downScroll down by one visual page..It Ic scroll-line-downScroll down by one line..It Ic scroll-line-upScroll up by one line..It Ic scroll-upScroll up by one visual page..It Ic suspend-telescopeSuspend the current.Nmsession..It Ic swiperJump to a line using the minibuffer..It Ic tocJump to a heading using the minibuffer..It Ic toggle-helpToggle side window with help about available keys and their associatedinteractive command..It Ic toggle-pre-wrapToggle the wrapping of preformatted blocks..It Ic write-bufferSave the current buffer to the disk..El.Ss Minibuffer commands.Bl -tag -width execute-extended-command -compact.It Ic mini-abortAbort the current minibuffer action..It Ic mini-complete-and-exitComplete the current minibuffer action..It Ic mini-delete-backward-charDelete the character before the point..It Ic mini-delete-charDelete the character after the point..It Ic mini-goto-beginningSelect the first completion, if any..It Ic mini-goto-endSelect the last completion, if any..It Ic mini-kill-lineDelete from point until the end of the line..It Ic mini-kill-whole-lineDelete the whole line..It Ic mini-next-history-elementLoad the previous history element..It Ic mini-previous-history-elementLoad the next history element..El.Ss AliasesThe 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 ENVIRONMENTWhen.Nmis started, it inspects the following environment variables:.Bl -tag -width NO_COLORS.It Ev HOMEThe user's login directory..It Ev NO_COLORSTo decide whether to use colors or not.The content of the variable doesn't matter..It Ev TERMThe user's terminal name..It Ev XDG_CACHE_HOME , Ev XDG_CONFIG_HOME , Ev XDG_DATA_HOMEIf defined can alter the default location of the files used..El.Sh FILESBy default.Nmfollows the XDG Base Directory Specification.However, if.Pa ~/.telescopeexists, XDG is ignored and all the files are stored inside it.The usage of.Ev XDG_CACHE_HOME ,.Ev XDG_CONFIG_HOMEand.Ev XDG_DATA_HOMEcan further alter the location of these files..Pp.Bl -tag -width Ds -compact.It Pa ~/.config/telescope/configDefault configuration file..It Pa ~/.local/share/telescope/pages/about_*.gmiOverrides for built-in about: pages..It Pa ~/.local/share/telescope/bookmarks.gmiBookmarks file..It Pa ~/.local/share/telescope/known_hostsHash 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/lockLock file used to prevent multiple instance of.Nmfrom running at the same time..It Pa ~/.cache/telescope/sessionThe list of tabs from the last session..El.Sh EXAMPLESIt's possible to browse.Dq the small web.Pq i.e. simple websitesby using programs like the duckling-proxy by defining a proxy in.Pa ~/.config/telescope/config :.Bd -literal -offset indentproxy http via "gemini://127.0.0.1:1965"proxy https via "gemini://127.0.0.1:1965".Ed.PpTo load.Nmwithout any configuration.Bd -literal -offset indenttelescope -c /dev/null.Ed.Sh STANDARDS.Rs.%B XDG Base Directory Specification.%U https://specifications.freedesktop.org/basedir-spec/latest/.Re.Sh ACKNOWLEDGEMENTSThe.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 -nosplitThe.Nmprogram was written by.An Omar Polo Aq Mt op@omarpolo.com ..Sh CAVEATS.Nmassumes a UTF-8 environment and doesn't try to cope with other encodings.This can cause strange rendering issues if you're lucky, or possiblyweird thing happening depending on your locale and terminal emulator..PpThe algorithm used for text-wrapping is naive and doesn't really work forlanguages that make heavily use of glyphs composed by multiple UNICODEcodepoints..Sh BUGSThere's no UI for out-of-band certificates validation.
Omar Polo