diff options
Diffstat (limited to 'upstream/archlinux/man1/lesspipe.1')
| -rw-r--r-- | upstream/archlinux/man1/lesspipe.1 | 221 |
1 files changed, 221 insertions, 0 deletions
diff --git a/upstream/archlinux/man1/lesspipe.1 b/upstream/archlinux/man1/lesspipe.1 new file mode 100644 index 00000000..101db88f --- /dev/null +++ b/upstream/archlinux/man1/lesspipe.1 @@ -0,0 +1,221 @@ +.TH LESSPIPE.SH "1" "Jan 2023" "lesspipe.sh" "User Commands" +.SH NAME +lesspipe.sh \- a filter for less +.SH SYNOPSIS +.B lesspipe.sh +[\fIFILE[s]\fR]... +.SH DESCRIPTION +.PP +The aim of \fBlesspipe.sh\fP is to enhance the output of \fBless\fP. The choice +of the rules to be applied to modify the output are based on the file contents. +The file extension is respected only as a last resort. +Usually \fBlesspipe.sh\fP is called as an input filter to \fBless\fP. +.PP +With the help of that filter \fBless\fP +will display the uncompressed contents of compressed (\fIgzip, bzip2, +compress, zstd, lz4, lzip, xz, lzma or brotli\fP) files. For files +containing archives and directories, a table of contents will be displayed +(\fItar, ar, zip, i7-zip, rar, jar, rpm, deb ms-cabinet and iso formats\fP). +Many other files will be reformatted for display. It includes +\fIpdf, dvi, markdown, Office (MS and Openoffice)\fP suites formats, +\fINetCDF, matlab, html\fP and \fImedia (image, audio and video)\fP +formats. This does require helper programs being installed. +.PP +The filter can also be applied recursively to extract and display +files in archives on the fly. This works to a depth of 6 where applying a +decompression algorithm counts as a separate level. +.PP +If the file utility reports text with an encoding different from the one +used in the terminal then the text will be transformed using \fIiconv\fP into +the default encoding. This does assume the \fIfile\fP command gets the file +encoding right, which can be wrong in some situations. An appended colon +to the file name does suppress the conversion. +.PP +When using the programs \fBgit\fP, \fBvim\fP or \fBmutt\fP they can be +enabled to read non-text files by using lesspipe.sh. That is described in +the Wiki at \fIhttps://github.com/wofr06/lesspipe/wiki\fP. +.SH FILTER ACTIVATION +The filter is called from \fBless\fP provided the environment variable +\fBLESSOPEN\fP is set properly. For ksh like shells (\fIbash, zsh\fP) +the command +.RS +.I LESSOPEN="|lesspipe.sh %s"; export LESSOPEN +.RE +does activate the filter for less. Use the fully qualified path, if +\fBlesspipe.sh\fP is not in the search path. The command to set \fBLESSOPEN\fP +can also be displayed by calling \fBlesspipe.sh\fP without arguments. +This can even be used to set \fBLESSOPEN\fP directly: +.RS +.I eval `lesspipe.sh` +(bash) or +.RE +.RS +.I lesspipe.sh|source /dev/stdin +(zsh) +.RE +Having set the environment variable as described above, \fBless\fP +will then display textual information for a wide range of file formats. +.PP +The filter is normally not called if input is piped to less as in +.RS +.I cat somefile | less +.RE +As described in the man page of less, the filtering in a pipe can however +be forced by starting \fBLESSOPEN\fP with the characters \fI|-\fP. +.PP +\fBLESSOPEN\fP starting with the two characters \fI||\fP to handle empty files +and command errors is implemented only partly, usually on failures of +commands within \fBlesspipe.sh\fP the error messages get displayed. +.PP +The now obsolete variable \fBLESS_ADVANCED_PREPROCESSOR\fP +was used to decide, whether \fIhtml\fP, \fIxml\fP and \fIperl pod\fP should +be shown as pure text or not. This has been changed, these formats are now +always interpreted, unless a colon is appended to the file name. If the +correct file type (\fIhtml\fP, \fIxml\fP, \fIpod\fP) follows, the output can +get colorized (see below). +.PP +.RS +Example: \fIless index.html:html\fP +.RE +.PP +To suppress informal messages in the first line of the filter output the +ENV variable \fBLESSQUIET\fP can be set to a nonempty value. +.PP +To disengage the filter temporarily a colon can be appended to the file name. +If the file name contains a colon, then an equal sign should be used instead. +.SH OUTPUT COLORIZATION +The filter is able to do syntax highlighting for a wide variety of +file types. If installed, \fIbat\fP/\fIbatcat\fP is used for +coloring the output. If not, \fIpygmentize\fP, \fIsource-highlight\fP, +\fIcode2color\fP and \fIvimcolor\fP are tried in turn. +For bat/batcat the theme is set to \fIansi\fP and the style is set to +\fIplain\fP which comes closer to the unfiltered output of \fBless\fP. +These settings can be changed in \fI~/.config/bat/config\fP or by the +environment variables \fBBAT_STYLE\fP and \fBBAT_THEME\fP. +.PP +Among the colorizers +a preferred one can be forced for coloring by setting the ENV variable +\fBLESSCOLORIZER\fP to the name of the colorizer. For \fIpygmentize\fP and +\fIbat\fP/\fIbatcat\fP restricted option settings are allowed as follows: +.RS +.I LESSCOLORIZER='pygmentize -O style=foo' +.RE +.RS +.I LESSCOLORIZER='bat --style=foo --theme=bar' +.RE +Syntax highlighting is activated, if the environment variable \fBLESS\fP +exists and contains the option \fI-R\fP +or less is called with this option. This guarantees that escape sequences +get converted into colors and do not garble the display. Using the option +\fI-r\fP is not recommended, as the screen layout may be wrong, if long +lines are in the output. +.PP +Syntax highlighting can be switched off by +appending a colon after the file name, if the output was colorful. If the +wrong language was chosen for syntax highlighting, then another one can be +forced by appending a colon and a suffix to the file name. +.PP +In a pipe that method cannot be used. As a way out a last argument can be added +that gets inspected by \fBlesspipe.sh\fP. +A single colon (disengage filter) or :extension (force language) is possible as e.g with +.RS +.I command that generates c code | less - :c +.RE +.PP +When the conditions for syntax highlighting are met directory listings and +listings of tar file contents get colorized as well. +.PP +As \fBless\fP is used as a default browser in other programs the choice of the +colorizer can affect the output of those programs. +For \fIman\fP, \fIgit\fP, and \fIperldoc\fP) lesspipe.sh does no filtering. +.SH WATCHING GROWING FILES +As soon as \fBlesspipe.sh\fP +calls a program to convert the input the ability to watch growing files +(using the F command within less) is lost. This is usually wanted for log +files like syslog. To temporarily disengage \fBlesspipe.sh\fP +a colon as the last argument for \fBless\fP needs to be added as e.g in +.RS +.I less /var/log/syslog : +.RE +or \fBless\fP +can be called with the +F argument, which is equivalent to F within the pager: +.RS +.I less +F /var/log/syslog +.RE +Appending a colon to the file name does not work, as then the filter has to be engaged to at least remove that colon and use cat for the original file. +On the other hand non growing log files can be colorized using \fBccze\fP. +Its recognition as a log file is difficult if not ending in \fI.log\fP +but can be forced appending \fB:.log\fP to the file name as e.g in +.RS +.I less /var/log/syslog:.log +.RE +.SH ADVANCED USAGE +This version of \fBlesspipe.sh\fP +allows you to view individual files contained in a file archive, which itself +may even be contained in another archive. +.PP +The notation for viewing files in multifile archives is +.RS +.B less +\fIarchive_file\fP:\fIcontained_file\fP +.RE +or even +.RS +.B less +\fIsuper_archive\fP:\fIarchive_file\fP:\fIcontained_file\fP +.RE +To display the last file in the chain raw format, a colon (\fI:\fP) has to be +appended to the file name. If it does contain a colon, then the alternate +separator character equal sign (\fI=\fP) has to be used. +.PP +Again, this method of extracting and displaying files does not work if +\fBless\fP is called in an output pipe and \fBLESSOPEN\fP starts with the +\fB|-\fP characters. As already for syntax highlighting the solution is to use +a second argument that starts with a colon. Then the above command would +be written as +.RS +\fBcat \fIsuper_archive\fP | \fBless\fP - :\fIarchive\fP:\fIcontained_file\fP +.RE +.PP +.SH COMPLETING MECHANISM FOR ARCHIVE CONTENTS +With the provided \fIlesscomplete\fP (for \fBzsh\fP and \fBbash\fP), +\fI_less\fP (for \fBzsh\fP) and \fIless_completion\fP (for \fBbash\fP) files +a tab completion for files in archives can be accomplished. +Entering a colon (:) or an equal sign (=) after an archive +file name and then pressing the tab key triggers the completion mechanism. +This also works in chained archives. The files \fIlesscomplete\fP and +\fIless_completion\fP have to be in one of the directories listed in +\fB$PATH\fP and the function \fI_less\fP for \fBzsh\fP in a directory +listed by \fI$fpath\fP. The less_completion script has to +be sourced within a bash initialization script, e.g. in \fI~/.bashrc\fP. New +directories such as \fI~/scripts\fP and \fI~/.fpath\fP can be added using the +commands +.RS +\fBPATH\fP=\fI~/scripts:$PATH\fP and +\fBfpath\fP=\fI(~/.fpath $fpath)\fP +.RE +.SH USER DEFINED FILTERING +The lesspipe.sh filtering can be replaced or enhanced by a user defined +program. Such a program has to be called either \fB.lessfilter\fP (and be +placed in the users home directory), or \fBlessfilter\fP (and be accessible +from a directory mentioned in \fB$PATH\fP). +It has to be executable and has to end with an exit code 0, if the filtering +was done within that script. Otherwise, a nonzero exit code means the filtering +is left to lesspipe.sh. +.PP +This mechanism can be used to add filtering for new formats or e.g. inhibit +filtering for certain file types. +.SH AUTHOR +Wolfgang Friebel +.SH "REPORTING BUGS" +Report bugs to <wp.friebel AT gmail DOT com>. +.SH COPYRIGHT +Copyright \(co 2005-2023 Wolfgang Friebel +.br +This is free software; see the source for copying conditions. There is NO +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +.SH "SEE ALSO" +less(1) +.PP +A description of \fBlesspipe.sh\fP +is also contained in the file README contained in the source code package |