lesspipe.1

.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