Debian Codegraph @

upstream/mageia-cauldron/man1/lesspipe.1

raw
1 .TH LESSPIPE.SH "1" "August 2024" "lesspipe.sh" "User Commands"
2 .SH NAME
3 lesspipe.sh \- a filter for less
4 .SH SYNOPSIS
5 .B lesspipe.sh
6 [\fIFILE[s]\fR]...
7 .SH DESCRIPTION
8 .PP
9 The aim of \fBlesspipe.sh\fP is to enhance the output of \fBless\fP. The choice
10 of the rules to be applied to modify the output are based on the file contents.
11 The file extension is respected only as a last resort.
12 Usually \fBlesspipe.sh\fP is called as an input filter to \fBless\fP.
13 .PP
14 With the help of that filter \fBless\fP
15 will display the uncompressed contents of compressed (\fIgzip, bzip2,
16 compress, zstd, lz4, lzip, xz, lzma or brotli\fP) files. For files
17 containing archives and directories, a table of contents will be displayed
18 (\fItar, ar, zip, 7-zip, rar, jar, cpio, rpm, deb ms-cabinet, iso, appimage
19 and snap formats\fP).
20 Many other files will be reformatted for display. It includes
21 \fIpdf, dvi, markdown, Office (MS and Openoffice)\fP suites formats,
22 \fINetCDF, matlab, device tree blob, html, xml\fP and \fImedia (image, audio and
23 video)\fP formats. This does require helper programs being installed.
24 .PP
25 The filter can also be applied recursively to extract and display
26 files in archives on the fly. This works to a depth of 6 where applying a
27 decompression algorithm counts as a separate level.
28 .PP
29 If the file utility reports text with an encoding different from the one
30 used in the terminal then the text will be transformed using \fIiconv\fP into
31 the default encoding. This does assume the \fIfile\fP command gets the file
32 encoding right, which can be wrong in some situations. An appended colon
33 to the file name does suppress the conversion.
34 .PP
35 When using the programs \fBgit\fP, \fBvim\fP or \fBmutt\fP they can be
36 enabled to read non-text files by using lesspipe.sh. That is described in
37 the Wiki at \fIhttps://github.com/wofr06/lesspipe/wiki\fP.
38 .SH FILTER ACTIVATION
39 The filter is called from \fBless\fP provided the environment variable
40 \fBLESSOPEN\fP is set properly. For ksh like shells (\fIbash, zsh\fP)
41 the command
42 .RS
43 .I LESSOPEN="|lesspipe.sh %s"; export LESSOPEN
44 .RE
45 does activate the filter for less. Use the fully qualified path, if
46 \fBlesspipe.sh\fP is not in the search path. The command to set \fBLESSOPEN\fP
47 can also be displayed by calling \fBlesspipe.sh\fP without arguments.
48 This can even be used to set \fBLESSOPEN\fP directly:
49 .RS
50 .I eval `lesspipe.sh`
51 (bash) or
52 .RE
53 .RS
54 .I lesspipe.sh|source /dev/stdin
55 (zsh)
56 .RE
57 The above commands work only in the described manner if the file name is
58 \fBlesspipe.sh\fP.
59 If it is installed under a different name then calling it without an argument
60 will work as a filter with \fBLESSQUIET\fP set and expecting input from STDIN.
61 .PP
62 Having set the environment variable as described above, \fBless\fP
63 :will then display textual information for a wide range of file formats.
64 .PP
65 The filter is normally not called if input is piped to less as in
66 .RS
67 .I cat somefile | less
68 .RE
69 As described in the man page of less, the filtering in a pipe can however
70 be forced by starting \fBLESSOPEN\fP with the characters \fI|-\fP.
71 .PP
72 \fBLESSOPEN\fP starting with the two characters \fI||\fP to handle empty files
73 and command errors is implemented only partly, usually on failures of
74 commands within \fBlesspipe.sh\fP the error messages get displayed.
75 .PP
76 To suppress informal messages in the first line of the filter output the
77 ENV variable \fBLESSQUIET\fP can be set to a nonempty value.
78 .PP
79 To disengage the filter temporarily a colon can be appended to the file name.
80 If the file name contains a colon, then an equal sign should be used instead.
81 .SH HTML, XML and Perl POD Files
82 Files in the \fIhtml\fP, \fIxml\fP and \fIperl pod\fP format are always
83 rendered. Sometimes however the original contents of the file should be viewed
84 instead. As mentioned before that can be achieved by appending a colon to the
85 file name. If the correct file type (\fIhtml\fP, \fIxml\fP, \fIpod\fP) follows,
86 the output can get colorized (see also the section below).
87 .PP
88 .RS
89 Example: \fIless index.html:html\fP
90 .RE
91 .PP
92 If the binary \fIxmq\fP is installed, then \fIxml\fP is rendered differently,
93 so that the xml structure is better recognized. A similar display for
94 \fIhtml\fP contents using \fIxmq\fP is achieved by appending a colon to the
95 file name. To get the original html file contents, two colons are
96 required in this case.
97 .SH OUTPUT COLORIZATION
98 The filter is able to do syntax highlighting for a wide variety of
99 file types. If installed, \fInvimpager\fP is used for
100 colorizing the output. If not, \fIbat\fP/\fIbatcat\fP, \fIpygmentize\fP,
101 \fIsource-highlight\fP, \fIvimcolor\fP and \fIcode2color\fP are tried in turn.
102 For bat/batcat the theme is set to \fIansi\fP and the style is set to
103 \fIplain\fP which comes closer to the unfiltered output of \fBless\fP.
104 These settings can be changed in \fI~/.config/bat/config\fP or by the
105 environment variables \fBBAT_STYLE\fP and \fBBAT_THEME\fP.
106 .PP
107 Among the colorizers
108 a preferred one can be forced for colorizing by setting the ENV variable
109 \fBLESSCOLORIZER\fP to the name of the colorizer. For \fIpygmentize\fP and
110 \fIbat\fP/\fIbatcat\fP restricted option settings are allowed as follows:
111 .RS
112 .I LESSCOLORIZER='pygmentize -O style=foo' (-P allowed as well)
113 .RE
114 .RS
115 .I LESSCOLORIZER='bat --style=foo --theme=bar' (default is theme ansi, style plain)
116 .RE
117 Syntax highlighting is activated, if the environment variable \fBLESS\fP
118 exists and contains the option \fI-R\fP
119 or less is called with this option. This guarantees that escape sequences
120 get converted into colors and do not garble the display. Using the option
121 \fI-r\fP is not recommended, as the screen layout may be wrong, if long
122 lines are in the output.
123 .PP
124 Syntax highlighting can be switched off by
125 appending a colon after the file name, if the output was colorful. If the
126 wrong language was chosen for syntax highlighting, then another one can be
127 forced by appending a colon and a suffix to the file name.
128 .PP
129 In a pipe that method cannot be used. As a way out a last argument can be added
130 that gets inspected by \fBlesspipe.sh\fP.
131 A single colon (disengage filter) or :extension (force language) is possible as e.g with
132 .RS
133 .I command that generates c code | less - :c
134 .RE
135 .PP
136 When the conditions for syntax highlighting are met directory listings and
137 listings of tar file contents get colorized as well.
138 .PP
139 As \fBless\fP is used as a default browser in other programs (e.g. \fIman\fP,
140 \fIgit\fP, and \fIperldoc\fP)) \fBlesspipe.sh\fP may be engaged and alter
141 the output of those programs.
142 .SH WATCHING GROWING FILES
143 As soon as \fBlesspipe.sh\fP
144 calls a program to convert the input the ability to watch growing files
145 (using the F command within less) is lost. This is usually wanted for log
146 files like syslog. To temporarily disengage \fBlesspipe.sh\fP
147 a colon as the last argument for \fBless\fP needs to be added as e.g in
148 .RS
149 .I less /var/log/syslog :
150 .RE
151 or \fBless\fP
152 can be called with the +F argument, which is equivalent to F within the pager:
153 .RS
154 .I less +F /var/log/syslog
155 .RE
156 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.
157 On the other hand non growing log files can be colorized using \fBccze\fP.
158 Its recognition as a log file is difficult if not ending in \fI.log\fP
159 but can be forced appending \fB:.log\fP to the file name as e.g in
160 .RS
161 .I less /var/log/syslog:.log
162 .RE
163 .SH ADVANCED USAGE
164 This version of \fBlesspipe.sh\fP
165 allows you to view individual files contained in a file archive, which itself
166 may even be contained in another archive.
167 .PP
168 The notation for viewing files in multifile archives is
169 .RS
170 .B less
171 \fIarchive_file\fP:\fIcontained_file\fP
172 .RE
173 or even
174 .RS
175 .B less
176 \fIsuper_archive\fP:\fIarchive_file\fP:\fIcontained_file\fP
177 .RE
178 To display the last file in the chain raw format, a colon (\fI:\fP) has to be
179 appended to the file name. If it does contain a colon, then the alternate
180 separator character equal sign (\fI=\fP) has to be used.
181 .PP
182 Again, this method of extracting and displaying files does not work if
183 \fBless\fP is called in an output pipe and \fBLESSOPEN\fP starts with the
184 \fB|-\fP characters. As already for syntax highlighting the solution is to use
185 a second argument that starts with a colon. Then the above command would
186 be written as
187 .RS
188 \fBcat \fIsuper_archive\fP | \fBless\fP - :\fIarchive\fP:\fIcontained_file\fP
189 .RE
190 .PP
191 .SH COMPLETING MECHANISM FOR ARCHIVE CONTENTS
192 With the provided \fIlesscomplete\fP (for \fBzsh\fP and \fBbash\fP),
193 \fI_less\fP (for \fBzsh\fP) and \fIless_completion\fP (for \fBbash\fP) files
194 a tab completion for files in archives can be accomplished.
195 Entering a colon (:) or an equal sign (=) after an archive
196 file name and then pressing the tab key triggers the completion mechanism.
197 This also works in chained archives. The files \fIlesscomplete\fP and
198 \fIless_completion\fP have to be in one of the directories listed in
199 \fB$PATH\fP and the function \fI_less\fP for \fBzsh\fP in a directory
200 listed by \fI$fpath\fP. The less_completion script has to
201 be sourced within a bash initialization script, e.g. in \fI~/.bashrc\fP. New
202 directories such as \fI~/scripts\fP and \fI~/.fpath\fP can be added using the
203 commands
204 .RS
205 \fBPATH\fP=\fI~/scripts:$PATH\fP and
206 \fBfpath\fP=\fI(~/.fpath $fpath)\fP
207 .RE
208 .SH USER DEFINED FILTERING
209 The lesspipe.sh filtering can be replaced or enhanced by a user defined
210 program. Such a program has to be called either \fB.lessfilter\fP (and be
211 placed in the users home directory), or \fBlessfilter\fP (and be accessible
212 from a directory mentioned in \fB$PATH\fP).
213 It has to be executable and has to end with an exit code 0, if the filtering
214 was done within that script. Otherwise, a nonzero exit code means the filtering
215 is left to lesspipe.sh.
216 .PP
217 This mechanism can be used to add filtering for new formats or e.g. inhibit
218 filtering for certain file types.
219 .SH AUTHOR
220 Wolfgang Friebel
221 .SH "REPORTING BUGS"
222 Report bugs to <wp.friebel AT gmail DOT com>.
223 .SH COPYRIGHT
224 Copyright \(co 2005-2024 Wolfgang Friebel
225 .br
226 This is free software; see the source for copying conditions. There is NO
227 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
228 .SH "SEE ALSO"
229 less(1)
230 .PP
231 A description of \fBlesspipe.sh\fP
232 is also contained in the file README contained in the source code package