#
# @(#) $Id: README,v 1.2 2002/06/30 16:09:01 alex Exp $
#
========================================================================
'prcolumn' and 'charcol' are tools for making vertical slices thru text.
'prcolumn' operates upon whitespace-separated columns, while 'charcol'
treats each character position as a column.  They are useful for:
    1) columnar manipulation within an editor by cmd filtering
    2) simple re-formating text (e.g. program output) from the shell
    3) selecting text columns for arglists by cmd substitution
========================================================================
"prcolumn" selects whitespace-separated fields (columns) from text files and
prints them in the specified order.  For example,

'prcolumn 5 7-9 6-3 ' some_text_file'

prints columns 5, 7 thru 9, and 6 thru 3 from 'some_text_file' in the given
order.  Whitepace is normally space and tab, but may be specified to
re-define columns in any useful way.

"charcol" behaves much as "prcolumn" does, except that each character position
is a 'column'; there are no column separators on input.  There are also no
separators on output, unless you specify one, in which case each 'column' or
range of columns specified by argument is preceded by the specified separator.
For example, if the input file 'x' contains "123456789", then

charcol 2-4 6 9 8 x

produces "234698", while

charcol -o "+++" 2-4 6 9 8

produces "234+++6+++9+++8".

You can choose whether output separators are printed for members of a range
(see the manual page).

Prcolumn does not do anything that 'awk' can't do (actually a good deal less)
but does its simpler tasks more conveniently, and usually more quickly, with
less fuss.  The above example could be accomplished by

awk 'BEGIN { OFS = "\t"} {print $5, $7, $8, $9, $6, $5, $4, $3}' \
    some_text_file

The two incarnations of this program correspond roughly to the '-f' and '-c'
options of the ATT "cut" program and will perform all of the operations of
that program, plus a few more (e.g. "cut" won't print reverse ranges).
If you are imaginative, you can simulate some other common Unix programs.
For example 'charcol $-1' is a dead-ringer for 'rev' (if you care).  In
short, these programs don't do anything special, but they aim to be CONVENIENT
to use for common tasks.  For me, they have more than fulfilled this aim
over the years, and I carry them wherever I go--can't do without 'em.

For more information and examples, see the enclosed manual page, and the
test scripts TEST.col and TEST.char.

INSTALLATION
"prcolumn" should compile on almost any Unix system.  The only known portability
issues are the "strchr() vs index()" culture gap, and the need to make (void)
meaningful to older compilers.

    1) download and extract *either* the prcolumn tar file or
       the shar file.

    2) Edit the Makefile to select
       a) BINDIR -- install destination for binaries
       b) MANDIR -- install destination for manual page source
       c) MANEXT -- suffix for manual page
       d) LIBS   -- you probably don't need any...

    3) make

    4) make test -- checks the output of the TEST shell scripts against
       sample output.  You won't need to re-direct or page the output --
       it is 'tee'-ed to an output file.  The makefile ignores error returns,
       primarily because  'tee' always exits non-zero on some systems.
       In any case, if there are program errors, you will see the result of
       a 'diff' against the distributed test output file.

    5) make install -- when you are satisfied


If you find/fix bugs, please send questions or patches (diff -c fmt if
possible) to me.  I'm sometimes a bit slow at answering mail, but I'll
try to at least acknowledge receipt and get back to you more fully later.


Duane H. Hesser dhh@virtual-cafe.com