@node columns Invocation
@section Invoking columns
@cindex columns invocation
@ignore

DO NOT EDIT THIS FILE   (columns.texi)

It has been autogen-ed  Wednesday May 17, 2000 at 11:15:57 AM BST
From the definitions    ../columns/opts.def
and the template file   ../autoopts/aginfo.tpl

@end ignore

This program was designed for the purpose of generating compact,
columnized tables.  It will read a list of text items from standard
in or a specified input file and produce a columnized listing of
all the non-blank lines.  Leading white space on each line is
preserved, but trailing white space is stripped.  Methods of
applying per-entry and per-line embellishments are provided.
See the formatting and separation arguments below.

This program is used by AutoGen to help clean up and organize
its output.

See @file{autogen/src/agfunc.tpl}.

This function was not implemented as an expression function because
either it would have to be many expression functions, or a provision
would have to be added to provide options to expression functions.
Maybe not a bad idea, but it is not being implemented at the moment.

A side benefit is that you can use it outside of AutoGen to columnize
input, a la the @code{ls} command.

@menu
* columns usage::                  columns Usage
* columns by-columns::             by-columns Option
* columns col-width::              col-width Option
* columns columns::                columns Option
* columns first-indent::           first-indent Option
* columns format::                 format Option
* columns indent::                 indent Option
* columns input::                  input Option
* columns line-separation::        line-separation Option
* columns separation::             separation Option
* columns sort::                   sort Option
* columns spread::                 spread Option
* columns tab-width::              tab-width Option
* columns width::                  width Option
@end menu

@node columns usage
@subsection columns Usage
@cindex columns usage

This is the automatically generated usage text for columns:

@example

columns - Columnize Input Text - Ver. 1.1
USAGE:  lt-columns [-<flag> [<val>]]... [--<name>[@{=| @}<val>]]... 
  Flg Arg Option-Name    Description
   -W Num width          Maximum Line Width
   -c Num columns        Desired number of columns
   -w Num col-width      Set width of each column
      Num spread         maximum spread added to column width
   -I YES indent         Line prefix or indentation
      YES first-indent   First line prefix
                                - requires these options:
                                indent
      Num tab-width      tab width
   -s opt sort           Sort input text
   -f YES format         Formatting string for each input
   -S YES separation     Separation string - follows all but last
      YES line-separation string at end of all lines but last
      no  by-columns     Print entries in column order
   -i YES input          Input file (if not stdin)
   -v opt version        Output version information and exit
   -? no  help           Display usage information and exit
   -! no  more-help      Extended usage information passed thru pager

Options may be specified by doubled hyphens and their name
or by a single hyphen and the flag character/option value.

This program was designed for the purpose of generating compact,
columnized tables.  It will read a list of text items from standard
in or a specified input file and produce a columnized listing of
all the non-blank lines.  Leading white space on each line is
preserved, but trailing white space is stripped.  Methods of
applying per-entry and per-line embellishments are provided.
See the formatting and separation arguments below.

This program is used by AutoGen to help clean up and organize
its output.
@end example


@node columns width
@subsection width Option
@cindex columns-width

This option specifies the full width of the output line,
including any start-of-line indentation.  The output will fill
each line as completely as possible, unless the column width has
been explicitly specified.  If the maximum width is less than
the length of the widest input, you will get a single column
of output.

@node columns columns
@subsection columns Option
@cindex columns-columns

Use this option to specify exactly how many columns to produce.
If that many columns will not fit within @var{line_width}, then
the count will be reduced to the number that fit.

@node columns col-width
@subsection col-width Option
@cindex columns-col-width

Use this option to specify exactly how many characters are to be
allocated for each column.  If it is narrower than the widest entry,
it will be over-ridden with the required width.

@node columns spread
@subsection spread Option
@cindex columns-spread

Use this option to specify exactly how many characters may be
added to each column.  It allows you to prevent columns from
becoming too far apart.

@node columns indent
@subsection indent Option
@cindex columns-indent

If a number, then this many spaces will be inserted at the start of
every line.  Otherwise, it is a line prefix that will be inserted
at the start of every line.

@node columns first-indent
@subsection first-indent Option
@cindex columns-first-indent

If a number, then this many spaces will be inserted at the start of
the first line.  Otherwise, it is a line prefix that will be inserted
at the start of that line.

@node columns tab-width
@subsection tab-width Option
@cindex columns-tab-width

If an indentation string contains tabs, then this value is used to
compute the ending column of the prefix string.

@node columns sort
@subsection sort Option
@cindex columns-sort

Causes the input text to be sorted.  If an argument is supplied,
it is presumed to be a pattern and the sort is based upon the
matched text.  If the pattern starts with or consists of
an asterisk (@code{*}), then the sort is case insensitive.

@node columns format
@subsection format Option
@cindex columns-format

If you need to reformat each input text, the argument to this
option is interpreted as an @code{sprintf(3)} format that is used
to produce each output entry.

@node columns separation
@subsection separation Option
@cindex columns-separation

Use this option if, for example, you wish a comma to appear after
each entry except the last.

@node columns line-separation
@subsection line-separation Option
@cindex columns-line-separation

Use this option if, for example, you wish a backslash to appear at
the end of every line, except the last.

@node columns by-columns
@subsection by-columns Option
@cindex columns-by-columns

Normally, the entries are printed out in order by rows and then columns.
This option will cause the entries to be ordered within columns.  The final
column, instead of the final row, may be shorter than the others.

@node columns input
@subsection input Option
@cindex columns-input

This program normally runs as a @code{filter}, reading from standard
input, columnizing and writing to standard out.  This option redirects
input to a file.

