lesspipe.sh, a preprocessor for less
====================================
Version: 1.60
Author : Wolfgang Friebel, DESY (Wolfgang.Friebel AT desy.de)
License: GPL
Latest version available from:
http://freshmeat.net/projects/lesspipe/ or
http://sourceforge.net/projects/lesspipe/
To report bugs or make proposals to improve lesspipe please contact
the author by email.
Contents
========
1. Introduction
2. Usage
3. Required programs
4. Supported file formats
4.1 Supported compression methods
4.2 List of preprocessed file types
4.3 Conversion of files with alternate character encodings
5. Syntax highlighting
5.1 List of supported languages
5.2 Syntax highlighting alternatives
6. Displaying files with special characters in the file name
7. Examples
8. Other documentation about lesspipe
9. External links
9.1 URLs to some utilities
9.2 References
10. Contributors
1. Introduction
===============
To browse files under UNIX the excellent viewer less [1] can be used. By
setting the environment variable LESSOPEN, less can be enhanced by external
filters to become even more powerful. Most Linux distributions come already
preconfigured with a "lesspipe.sh" that covers the most common situations.
The input filter for less found in this package is understanding a lot
more file formats and even allows to view textual representation of files
contatined in archives. It is easily extendable for new formats.
The input filter which is also called "lesspipe.sh" is written in a ksh
compatible language (ksh, bash, zsh) as one of these is nearly always installed
on UNIX systems and uses comparably few resources. Otherwise an implementation
in perl for example would have been somewhat simpler to code. The code looks
less clean than it could as it was tried to make the script compatible with
a number of old shells and applications especially found on non Linux systems.
The input filter lesspipe.sh is based on two main ideas. The recognition of
the file format is not based on the file suffix. This method from the Windows
world is error prone and keeping the suffix list up to date is a tedious job.
UNIX comes with the "file" command [2] that recognizes lots of formats. Up to
date file descriptions are included in the tarball, maintaining a list of
file formats is therefore only a matter of obtaining a current version of the
"file" package.
The second idea is to being able to call lesspipe.sh with a hierarchy of file
names and to pull out and interpret finally the file at the bottom of the
hierarchy. This would allow to look at individual files contained in an
archive which itself could be part of a still bigger archive.
2. Usage
========
(see also the man page lesspipe.1)
To activate lesspipe.sh the environment variable LESSOPEN has to be defined
in the following way:
LESSOPEN="|lesspipe.sh %s"; export LESSOPEN (sh like shells)
setenv LESSOPEN "|lesspipe.sh %s" (csh, tcsh)
If lesspipe.sh is not in the UNIX search path or if the wrong lesspipe.sh is
found in the search path, then the full path to lesspipe.sh should be given
in the above commands.
As lesspipe.sh is accepting only a single argument, a hierarchical list of file
names has to be separated by a nonblank character. A colon is rarely found
in file names, therefore it has been chosen as the separator character. If a
file name does however contain at least one isolated colon, the equal sign =
can be used as an alternate separator character. In that case the = character
has to reoccur as the last character of the argument. At each stage in
extracting files from such a hierarchy the file type is determined. This
guarantees a correct processing and display at each stage of the filtering.
To view files in multifile archives the following command can be used:
less archive_file:contained_file
This can be used to extract single files from a multifile archive:
less archive_file:contained_file > extracted_file
For extracting files less is not required, that can be done also using:
lesspipe.sh archive_file:contained_file > extracted_file
Even a file in a multifile archive that itself is contained in yet
another archive can be viewed this way:
less super_archive:archive_file:contained_file
The script is able to extract files up to a depth of 6 where applying a
decompression algorithm counts as a separate level. In a few rare cases the
file command does not recognize the correct format (especially with nroff).
In such cases the filtering can be suppressed by a trailing colon on the file
name.
Display the last file in the file1:..:fileN chain in raw format:
Suppress input filtering: less file1:..:fileN: (append 1 colon)
Suppress decompression: less file1:..:fileN:: (append 2 colons)
Suppress syntax highlighting: less file1:..:fileN: (append 1 colon)
Syntax highlighting (see below) is only tried if less is called with -r or -R
and highlighting support was requested when generating lesspipe.sh !!!
3. Required programs
====================
bash (at least version 2.03) or zsh or ksh (also pdksh, tested with
version 5.2). Configure puts an appropriate first line in the script
file (a version with an up to date magic file) (GNU file 4.xx recommended)
perl (for configure and code2color, lesspipe.sh can work without it)
Standard UNIX programs like ar, cat, cut, dd, egrep, gzip, ln, ls, mkdir,
rm, sed, strings, tar, tput and further programs for special formats.
4. Supported file formats
=========================
Currently lesspipe.sh [3],[4] supports the following compression methods
and file types (i.e. the file contents gets transformed by lesspipe.sh):
4.1 Supported compression methods
---------------------------------
gzip, compress, pack requires gzip
bzip2 requires bzip2
zip requires unzip
rar requires rar or unrar
7-zip requires 7za
lzip requires lzip
lzma requires lzma (limited support only)
4.2 List of preprocessed file types
-----------------------------------
tar requires GNU tar
nroff(mandoc) requires groff
ar library requires ar
jar archive requires fastjar or unzip
rar archive requires unrar or rar
7-zip archive requires 7za
lzip archive requires lzip
shared library requires nm
executable requires strings
directory displayed using ls -lA
RPM requires GNU cpio and rpm2cpio or rpmunpack, optionally rpm
Microsoft Word requires antiword or catdoc
Debian requires ar, gzip and tar, shows more info if dpkg is installed
html requires html2text or elinks or links or lynx or w3m
pdf requires pdftotext or pdftohtml
perl requires pod2text
rtf requires unrtf
dvi requires dvi2tty
ps requires pstotext or ps2ascii (from the gs package)
mp3 requires id3v2 or mp3info
jpg, png, gif requires identify
iso images requires isoinfo
MacOSX archive requires lsbom
MacOS X bom requires lsbom
MacOS X plist requires plutil
cab requires cabextract (version 1.0 or above)
gpg encrypted requires gpg
perl storable requires perl (and the perl modules Storable and Data::Dumper)
perl pod requires perldoc
Openoffice.org 1.x and Opendocument (OASIS) text documents
requires unzip and o3tohtml or sxw2txt (distributed together
with lesspipe)
4.3 Conversion of files with alternate character encodings
----------------------------------------------------------
If the file utility reports a file containing ISO-8859, UTF-8 or UTF-16
characters and the LANG variable indicates that the display should be in
a different encoding (UTF-8 or ISO-8859) then the assumption is made that
the text can be converted (for ISO-8859 ISO-8859-1 is selected).
If the LANG variable gives no hint that UTF-8 is required, then text
with UTF-8 encoding is converted to ISO-8859-1. This is not always correct
but gives at least for some file contents a better display.
The conversion requires the 'iconv' program.
4.4 File formats currently not supported
----------------------------------------
(code contributed but commented out)
jpeg and pbm graphics files to be displayed in ascii art. The ascii art
library works with overprinting that does not work properly within less.
Therefore the resulting quality of the converted picture is not satisfactory.
Display of video streams using mplayer with -aadriver (again ascii art) is
considered abuse of less and also commented out.
looking at contents of DOS formatted disks by accessing the proper device file
5. Syntax highlighting
======================
Experimental support for syntax highlighting was added through a perl script
'code2color' which is derived from code2html [5].
ATTENTION: Syntax highlighting is only activated if the environment variable
LESS is existing and contains the option -R or -r or less is called with one
of these options. This guarantees, that instead of literal escape sequences
colors are displayed. The detection of the -r/-R presence at runtime is
rather dependent on the operating system and may not work in all cases.
Putting the option in the LESS environment variable is guaranteed to work.
By installing the perl module Proc::ProcessTable the OS dependence can be
reduced as well.
As syntax highlighting is rather resource intense it 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 as follows (assuming
this is a file with perl syntax):
less config_file:.pl
That works as well to force the call of code2color for a given language.
5.1 List of supported languages
-------------------------------
Text files for the following languages can be highlighted:
ada, asm, awk, c, c++, groff, html, xml, java, javascript, lisp, m4,
make, pascal, patch, perl, povray, python, ruby, shellscript, sql
The corresponding suffixes recognized by code2color are:
.ada .asm .inc .awk .c .h .cpp .cxx .groff .html .php .xml .java .js .lsp .m4
Makefile .pas .patch .diff .pm .pl .pod .pov .py .rb .sh .sql
5.2 Syntax highlighting alternatives
------------------------------------
The enabling of syntax highlighting contains OS dependent code and is not
guaranteed to work (it was tested on Linux, Solaris, IRIX, HPUX, AIX,
MacOS X, Cygwin and FreeBSD). It is deactivated by default and not
reccommended by me. It can be activated using "configure" or "make MODE=ask".
The function code2color contains code to guarantee that color codes are only
sent if less is called with one of the options -r or -R. If this is not
checked then the display can get garbled by escape sequences that are
displayed by less instead of showing colorful output.
Therefore the replacement of the lines
${dir}code2color $PPID ${in_file:+"$in_file"} $lang "$2" and
${dir}code2color $PPID ${in_file:+"$in_file"} "$2" respectively
by lines containing calls to other syntax colorizers such as pygmentize
or enscript would not in all cases lead to the desired result. In addition
the display of wrapped long lines and moving backward in a file can give
weird output. See also http://www.greenwoodsoftware.com/less/faq.html#dashr
Much better syntax highlighting is obtained using the less emulation of vim:
The editor vim comes with a file less.sh, in my case located in
/usr/share/vim/vim71/macros. Assuming this file location do then define
a function lessc (bash, zsh, ksh users)
lessc () { /usr/share/vim/vim71/macros/less.sh "$@"}
or an alias lessc (csh, tcsh users)
alias lessc /usr/share/vim/vim71/macros/less.sh
and use "lessc filename" to view the colorful file contents.
6. Displaying files with special characters in the file name
============================================================
Shell metacharacters in file names: space (frequently used in windows
file names), the characters | & ; ( ) ` < > " ' # ~ = $ * ? [ ] or \
must be escaped by a \ when used in the shell, e.g. less a\ b.tar.gz:a\"b
will display the file a"b contained in the gzipped tar archive a b.tar.gz.
Files within an archive that do have an isolated colon in the name cannot
be displayed using the
archive_name:contained_file_name
notation. These files can be displayed using a notation with the alternate
separator character = as follows:
archive_name=contained_file_name=
Please note the trailing = which is required.
7. Examples
===========
As a typical usage case it is shown how one could display the man page
"file.man" found in the Fedora10 RPM source archive file-4.26-3.fc10.src.rpm
The less command enhanced with the lesspipe.sh filter
less file-4.26-3.fc10.src.rpm
yields the following output
...
-rw-r--r-- 1 root root 584803 Sep 15 16:29 file-4.26.tar.gz
-rw-r--r-- 1 root root 17124 Oct 16 13:01 file.spec
Then the command
less file-4.26-3.fc10.src.rpm:file-4.26.tar.gz
produces the output
...
-rw-rw-r-- 10080/10080 16027 2008-08-30 12:01:41 file-4.26/doc/Makefile.in
-rw-rw-r-- 10080/10080 16097 2008-03-07 16:00:07 file-4.26/doc/file.man
-rw-rw-r-- 10080/10080 16943 2008-08-30 11:50:20 file-4.26/doc/magic.man
...
The desired man page can finally be viewed with
less file-4.26-3.fc10.src.rpm:file-4.26.tar.gz:file-4.26/doc/file.man
The subcomponents of the argument to less were easily obtained by cut and
paste using information contained in the previous lines of output.
If the nroff sources should have been displayed instead, appending
another colon at the end of the argument would have done the job:
less file-4.26-3.fc10.src.rpm:file-4.26.tar.gz:file-4.26/doc/file.man:
If the man page was even compressed (e.g. as file.man.gz) it would have been
uncompressed anyway. To also disallow uncompressing the source file.man.gz
a second colon would have to be appended to the argument.
Even extracting single files from an archive is possible, like with
less file-4.26-3.fc10.src.rpm:file-4.26.tar.gz:file-4.26/src/file.c > file.c
Files with binary contents can be extracted as well:
less file-4.26-3.fc10.src.rpm:file-4.26.tar.gz:: > file-3.27.tar.gz
Here the two colons at the end of the argument are required to suppress the
unzipping of the resulting file and to extract the tar file instead of
interpreting it.
Another interesting example is to get the dominating colors of a picture,
that contains a diagram with a few colors only. The command
less diagram.png
does produce a lot of information, among others
...
Histogram:
720: ( 0, 0,127) #00007F
3032: (127,127,127) grey50
18935: ( 0, 0,255) blue
21480: ( 0,255, 0) lime
21041: ( 0,255,255) cyan
8719: (255, 0, 0) red
14476: (255, 0,255) magenta
8822: (255,183, 0) #FFB700
13608: (255,255, 0) yellow
49167: (255,255,255) white
...
Other interesting examples are the inspection of Java's .jar files or Debian
package contents without unpacking the files and even without having java
installed or without working neccessarily on a Debian system.
8. Other documentation about lesspipe
=====================================
http://ref.cern.ch/CERN/CNL/2002/001/unix-less/
http://www.linux-magazine.com/issue/21/lesspipe.pdf
in bash cookbook (Ch. 8.15) by Carl Albing, Cameron Newham, J. P. Vossen
http://carloscosta.org/2008/07/05/how-to-get-more-from-less/
Documentation in german:
german.txt (distributed with lesspipe, not updated)
http://www.linux-magazin.de/ausgabe/2001/01/lesspipe/lesspipe.html
http://www.linux-user.de/ausgabe/2002/04/060-ootb/lesspipe-1.html
9. External links
=================
(last checked: Nov 28 2008):
9.1 URLs to some utilities
-------------------------------------
antiword http://www.winfield.demon.nl/
html2text http://www.mbayer.de/html2text/
cabextract http://www.cabextract.org.uk/
7za https://sourceforge.net/projects/p7zip/
lzip http://download.savannah.gnu.org/releases/lzip/
dvi2tty http://www.ctan.org/tex-archive/dviware/dvi2tty/
unrtf http://ftp.gnu.org/gnu/unrtf/
id3v2 http://id3v2.sourceforge.net/
9.2 References
--------------
[1] http://www.greenwoodsoftware.com/less/ (less)
[2] ftp://ftp.gw.com/pub/unix/file/ (file)
[3] http://freshmeat.net/projects/lesspipe/
[4] http://sourceforge.net/projects/lesspipe/
[5] http://www.palfrader.org/code2html/ (code2html)
10. Contributors
===============
The script lesspipe.sh is constantly enhanced thanks to suggestions from
users. Among the additions to lesspipe.sh is the code to browse the ASCII
contents of Word or Openoffice files, to show characteristics of mp3 files
or to decode MacOS X formats.
Thanks to (in alphabetical order):
Sören Andersen: PPD files colorization requested
Andrew Barnert: shell syntax fix
Peter D. Barnes, Jr.: plist files for Mac OS X
Eduard Bloch: proposed support for ISO images
Florian Cramer: MS Word, Openoffice support (o3read), ASCIIart, DjVu support
Philippe Defert: unattended installation
Antonio Diaz Diaz: proposed support for lzip
Bastian Fuchs: Issues using bash vs. sh
Carl Greco: enhanced output for .deb files
Stephan Hegel: suggested better 7za support
Jürgen Kahnert: display debian files without dpkg
Ben Kibbey: works on FreeBSD
Heinrich Kuettler: formatting, html via lynx
Vincent Lefevre: Openoffice support (sxw2txt)
Jay Levitt: suggested to use enscript for highlighting support (see 4.2 above)
Vladimir Linek: inspired me to add ps and dvi support
Istvan Marko: speedup of the procedure
Markus Meyer: improved mp3 handling
Remi Mommsen: Mac OS X support
Derek B. Noonburg: PDF files support
Jim Pryor: many enhancements, bug fixes, restructuring of code
Slaven Rezic: Cygwin support, bug fixes
Daniel Risacher: gpg support
Jens Schleusener: ksh syntax fixes
Ken Teague?: support more versions of file command
Paul Townsend: improved zip support for Solaris, bug fixes in configure
Chelban Vasile: trap command not working under /bin/sh
Götz Waschk: suggested lzma support
Michael Wiedmann: Debian packages support
~
