doc/invoke-columns.texi

   1 @node columns Invocation
   2 @section Invoking columns
   3 @pindex columns
   4 @cindex Columnize Input Text
   5 @ignore
   6 #  -*- buffer-read-only: t -*- vi: set ro:
   7 #
   8 # DO NOT EDIT THIS FILE   (invoke-columns.texi)
   9 #
  10 # It has been AutoGen-ed
  11 # From the definitions    ./opts.def
  12 # and the template file   agtexi-cmd.tpl
  13 @end ignore
  14 This program was designed for the purpose of generating compact,
  15 columnized tables.  It will read a list of text items from standard
  16 in or a specified input file and produce a columnized listing of
  17 all the non-blank lines.  Leading white space on each line is
  18 preserved, but trailing white space is stripped.  Methods of
  19 applying per-entry and per-line embellishments are provided.
  20 See the formatting and separation arguments below.
  21
  22 This program is used by AutoGen to help clean up and organize
  23 its output.
  24
  25 See @file{autogen/agen5/fsm.tpl} and the generated output
  26 @file{pseudo-fsm.h}.
  27
  28 This function was not implemented as an expression function because
  29 either it would have to be many expression functions, or a provision
  30 would have to be added to provide options to expression functions.
  31 Maybe not a bad idea, but it is not being implemented at the moment.
  32
  33 A side benefit is that you can use it outside of @code{autogen} to
  34 columnize input, a la the @code{ls} command.
  35
  36 This section was generated by @strong{AutoGen},
  37 using the @code{agtexi-cmd} template and the option descriptions for the @code{columns} program.
  38 This software is released under the GNU General Public License, version 3 or later.
  39
  40 @menu
  41 * columns usage::                  columns help/usage (@option{--help})
  42 * columns dimensions::             dimensions options
  43 * columns treatment::              treatment options
  44 * columns ordering::               ordering options
  45 * columns input-text::             input-text options
  46 * columns config::                 presetting/configuring columns
  47 * columns exit status::            exit status
  48 * columns See Also::               See Also
  49 @end menu
  50
  51 @node columns usage
  52 @subsection columns help/usage (@option{--help})
  53 @cindex columns help
  54
  55 This is the automatically generated usage text for columns.
  56
  57 The text printed is the same whether selected with the @code{help} option
  58 (@option{--help}) or the @code{more-help} option (@option{--more-help}).  @code{more-help} will print
  59 the usage text by passing it through a pager program.
  60 @code{more-help} is disabled on platforms without a working
  61 @code{fork(2)} function.  The @code{PAGER} environment variable is
  62 used to select the program, defaulting to @file{more}.  Both will exit
  63 with a status code of 0.
  64
  65 @exampleindent 0
  66 @example
  67 columns (GNU AutoGen) - Columnize Input Text - Ver. 1.2
  68 Usage:  columns [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]...
  69
  70 Specify the output dimensions:
  71
  72   Flg Arg Option-Name    Description
  73    -W Num width          Maximum Line Width
  74                                 - it must be in the range:
  75                                   16 to 4095
  76    -c Num columns        Desired number of columns
  77                                 - it must be in the range:
  78                                   1 to 2048
  79    -w Num col-width      Set width of each column
  80                                 - it must be in the range:
  81                                   1 to 2048
  82       Num tab-width      tab width
  83
  84 Specify how to lay out the text:
  85
  86   Flg Arg Option-Name    Description
  87       Num spread         maximum spread added to column width
  88                                 - it must be in the range:
  89                                   1 to 1024
  90       no  fill           Fill lines with input
  91                                 - prohibits these options:
  92                                 spread
  93                                 col-width
  94                                 by-columns
  95    -I Str indent         Line prefix or indentation
  96       Str first-indent   First line prefix
  97                                 - requires the option 'indent'
  98    -f Str format         Formatting string for each input
  99    -S Str separation     Separation string - follows all but last
 100       Str line-separation string at end of all lines but last
 101       Str ending         string at end of last line
 102
 103 Specify the ordering of the entries:
 104
 105   Flg Arg Option-Name    Description
 106       no  by-columns     Print entries in column order
 107    -s opt sort           Sort input text
 108
 109 Redirecting stdin to an alternate file:
 110
 111   Flg Arg Option-Name    Description
 112    -i Str input          Input file (if not stdin)
 113
 114 Version, usage and configuration options:
 115
 116   Flg Arg Option-Name    Description
 117    -v opt version        output version information and exit
 118    -? no  help           display extended usage information and exit
 119    -! no  more-help      extended usage information passed thru pager
 120    -> opt save-opts      save the option state to a config file
 121    -< Str load-opts      load options from a config file
 122                                 - disabled as '--no-load-opts'
 123                                 - may appear multiple times
 124
 125 Options are specified by doubled hyphens and their name or by a single
 126 hyphen and the flag character.
 127
 128 The following option preset mechanisms are supported:
 129  - reading file ./.columnsrc
 130  - reading file $HOME/.columnsrc
 131  - examining environment variables named COLUMNS_*
 132
 133 Please send bug reports to:  <autogen-users@@lists.sourceforge.net>
 134 @end example
 135 @exampleindent 4
 136
 137 @node columns dimensions
 138 @subsection dimensions options
 139 Specify the output dimensions.
 140 @subsubheading width option (-W).
 141 @anchor{columns width}
 142 @cindex columns-width
 143
 144 This is the ``maximum line width'' option.
 145 This option takes a number argument @file{num}.
 146 This option specifies the full width of the output line,
 147 including any start-of-line indentation.  The output will fill
 148 each line as completely as possible, unless the column width has
 149 been explicitly specified.  If the maximum width is less than
 150 the length of the widest input, you will get a single column
 151 of output.
 152 @subsubheading columns option (-c).
 153 @anchor{columns columns}
 154 @cindex columns-columns
 155
 156 This is the ``desired number of columns'' option.
 157 This option takes a number argument @file{count}.
 158 Use this option to specify exactly how many columns to produce.
 159 If that many columns will not fit within @var{line_width}, then
 160 the count will be reduced to the number that fit.
 161 @subsubheading col-width option (-w).
 162 @anchor{columns col-width}
 163 @cindex columns-col-width
 164
 165 This is the ``set width of each column'' option.
 166 This option takes a number argument @file{num}.
 167 Use this option to specify exactly how many characters are to be
 168 allocated for each column.  If it is narrower than the widest entry,
 169 it will be over-ridden with the required width.
 170 @subsubheading tab-width option.
 171 @anchor{columns tab-width}
 172 @cindex columns-tab-width
 173
 174 This is the ``tab width'' option.
 175 This option takes a number argument @file{num}.
 176 If an indentation string contains tabs, then this value is used to
 177 compute the ending column of the prefix string.
 178 @node columns treatment
 179 @subsection treatment options
 180 Specify how to lay out the text.
 181 @subsubheading spread option.
 182 @anchor{columns spread}
 183 @cindex columns-spread
 184
 185 This is the ``maximum spread added to column width'' option.
 186 This option takes a number argument @file{num}.
 187 Use this option to specify exactly how many characters may be
 188 added to each column.  It allows you to prevent columns from
 189 becoming too far apart.  Without this option, @file{columns}
 190 will attempt to widen columns to fill the full width.
 191 @subsubheading fill option.
 192 @anchor{columns fill}
 193 @cindex columns-fill
 194
 195 This is the ``fill lines with input'' option.
 196
 197 @noindent
 198 This option has some usage constraints.  It:
 199 @itemize @bullet
 200 @item
 201 must not appear in combination with any of the following options:
 202 spread, col_width, by_columns.
 203 @end itemize
 204
 205 Instead of columnizing the input text, fill the output lines
 206 with the input lines.  Blank lines on input will cause a
 207 blank line in the output, unless the output is sorted.
 208 With sorted output, blank lines are ignored.
 209 @subsubheading indent option (-I).
 210 @anchor{columns indent}
 211 @cindex columns-indent
 212
 213 This is the ``line prefix or indentation'' option.
 214 This option takes a string argument @file{l-pfx}.
 215 If a number, then this many spaces will be inserted at the start of
 216 every line.  Otherwise, it is a line prefix that will be inserted
 217 at the start of every line.
 218 @subsubheading first-indent option.
 219 @anchor{columns first-indent}
 220 @cindex columns-first-indent
 221
 222 This is the ``first line prefix'' option.
 223 This option takes a string argument @file{l-pfx}.
 224
 225 @noindent
 226 This option has some usage constraints.  It:
 227 @itemize @bullet
 228 @item
 229 must appear in combination with the following options:
 230 indent.
 231 @end itemize
 232
 233 If a number, then this many spaces will be inserted at the start of
 234 the first line.  Otherwise, it is a line prefix that will be inserted
 235 at the start of that line.  If its length exceeds "indent", then it
 236 will be emitted on a line by itself, suffixed by any line separation
 237 string.  For example:
 238
 239 @example
 240 $ columns --first='#define TABLE' -c 2 -I4 --line=' \' <<_EOF_
 241 one
 242 two
 243 three
 244 four
 245 _EOF_
 246 #define TABLE \
 247     one   two \
 248     three four
 249 @end example
 250 @subsubheading format option (-f).
 251 @anchor{columns format}
 252 @cindex columns-format
 253
 254 This is the ``formatting string for each input'' option.
 255 This option takes a string argument @file{fmt-str}.
 256 If you need to reformat each input text, the argument to this
 257 option is interpreted as an @code{sprintf(3)} format that is used
 258 to produce each output entry.
 259 @subsubheading separation option (-S).
 260 @anchor{columns separation}
 261 @cindex columns-separation
 262
 263 This is the ``separation string - follows all but last'' option.
 264 This option takes a string argument @file{sep-str}.
 265 Use this option if, for example, you wish a comma to appear after
 266 each entry except the last.
 267 @subsubheading line-separation option.
 268 @anchor{columns line-separation}
 269 @cindex columns-line-separation
 270
 271 This is the ``string at end of all lines but last'' option.
 272 This option takes a string argument @file{sep-str}.
 273 Use this option if, for example, you wish a backslash to appear at
 274 the end of every line, except the last.
 275 @subsubheading ending option.
 276 @anchor{columns ending}
 277 @cindex columns-ending
 278
 279 This is the ``string at end of last line'' option.
 280 This option takes a string argument @file{end-str}.
 281 This option puts the specified string at the end of the output.
 282 @node columns ordering
 283 @subsection ordering options
 284 Specify the ordering of the entries.
 285 @subsubheading by-columns option.
 286 @anchor{columns by-columns}
 287 @cindex columns-by-columns
 288
 289 This is the ``print entries in column order'' option.
 290 Normally, the entries are printed out in order by rows and then columns.
 291 This option will cause the entries to be ordered within columns.
 292 The final column, instead of the final row, may be shorter than the
 293 others.
 294 @subsubheading sort option (-s).
 295 @anchor{columns sort}
 296 @cindex columns-sort
 297
 298 This is the ``sort input text'' option.
 299 This option takes an optional string argument @file{key-pat}.
 300 Causes the input text to be sorted.  If an argument is supplied,
 301 it is presumed to be a pattern and the sort is based upon the
 302 matched text.  If the pattern starts with or consists of
 303 an asterisk (@code{*}), then the sort is case insensitive.
 304 @node columns input-text
 305 @subsection input-text options
 306 Redirecting stdin to an alternate file.
 307 @subsubheading input option (-i).
 308 @anchor{columns input}
 309 @cindex columns-input
 310
 311 This is the ``input file (if not stdin)'' option.
 312 This option takes a string argument @file{file}.
 313 This program normally runs as a @code{filter}, reading from standard
 314 input, columnizing and writing to standard out.  This option redirects
 315 input to a file.
 316
 317
 318 @node columns config
 319 @subsection presetting/configuring columns
 320
 321 Any option that is not marked as @i{not presettable} may be preset by
 322 loading values from configuration ("rc" or "ini") files, and values from environment variables named @code{COLUMNS} and @code{COLUMNS_<OPTION_NAME>}.  @code{<OPTION_NAME>} must be one of
 323 the options listed above in upper case and segmented with underscores.
 324 The @code{COLUMNS} variable will be tokenized and parsed like
 325 the command line.  The remaining variables are tested for existence and their
 326 values are treated like option arguments.
 327
 328
 329 @noindent
 330 @code{libopts} will search in 2 places for configuration files:
 331 @itemize @bullet
 332 @item
 333 $PWD
 334 @item
 335 $HOME
 336 @end itemize
 337 The environment variables @code{PWD}, and @code{HOME}
 338 are expanded and replaced when @file{columns} runs.
 339 For any of these that are plain files, they are simply processed.
 340 For any that are directories, then a file named @file{.columnsrc} is searched for
 341 within that directory and processed.
 342
 343 Configuration files may be in a wide variety of formats.
 344 The basic format is an option name followed by a value (argument) on the
 345 same line.  Values may be separated from the option name with a colon,
 346 equal sign or simply white space.  Values may be continued across multiple
 347 lines by escaping the newline with a backslash.
 348
 349 Multiple programs may also share the same initialization file.
 350 Common options are collected at the top, followed by program specific
 351 segments.  The segments are separated by lines like:
 352 @example
 353 [COLUMNS]
 354 @end example
 355 @noindent
 356 or by
 357 @example
 358 <?program columns>
 359 @end example
 360 @noindent
 361 Do not mix these styles within one configuration file.
 362
 363 Compound values and carefully constructed string values may also be
 364 specified using XML syntax:
 365 @example
 366 <option-name>
 367    <sub-opt>...&lt;...&gt;...</sub-opt>
 368 </option-name>
 369 @end example
 370 @noindent
 371 yielding an @code{option-name.sub-opt} string value of
 372 @example
 373 "...<...>..."
 374 @end example
 375 @code{AutoOpts} does not track suboptions.  You simply note that it is a
 376 hierarchicly valued option.  @code{AutoOpts} does provide a means for searching
 377 the associated name/value pair list (see: optionFindValue).
 378
 379 The command line options relating to configuration and/or usage help are:
 380
 381 @subsubheading version (-v)
 382
 383 Print the program version to standard out, optionally with licensing
 384 information, then exit 0.  The optional argument specifies how much licensing
 385 detail to provide.  The default is to print just the version.  The licensing information may be selected with an option argument.
 386 Only the first letter of the argument is examined:
 387
 388 @table @samp
 389 @item version
 390 Only print the version.  This is the default.
 391 @item copyright
 392 Name the copyright usage licensing terms.
 393 @item verbose
 394 Print the full copyright usage licensing terms.
 395 @end table
 396
 397 @node columns exit status
 398 @subsection columns exit status
 399
 400 One of the following exit values will be returned:
 401 @table @samp
 402 @item 0 (EXIT_SUCCESS)
 403 Successful program execution.
 404 @item 1 (EXIT_FAILURE)
 405 The operation failed or the command syntax was not valid.
 406 @item 66 (EX_NOINPUT)
 407 A specified configuration file could not be loaded.
 408 @item 70 (EX_SOFTWARE)
 409 libopts had an internal operational error.  Please report
 410 it to autogen-users@@lists.sourceforge.net.  Thank you.
 411 @end table
 412 @node columns See Also
 413 @subsection columns See Also
 414 This program is documented more fully in the Columns section
 415 of the Add-On chapter in the @code{AutoGen} Info system documentation.