diff options
Diffstat (limited to 'doc/invoke-columns.texi')
| -rw-r--r-- | doc/invoke-columns.texi | 418 |
1 files changed, 418 insertions, 0 deletions
diff --git a/doc/invoke-columns.texi b/doc/invoke-columns.texi new file mode 100644 index 0000000..1166465 --- /dev/null +++ b/doc/invoke-columns.texi @@ -0,0 +1,418 @@ +@node columns Invocation +@section Invoking columns +@pindex columns +@cindex Columnize Input Text +@ignore +# -*- buffer-read-only: t -*- vi: set ro: +# +# DO NOT EDIT THIS FILE (invoke-columns.texi) +# +# It has been AutoGen-ed August 11, 2012 at 09:45:26 AM by AutoGen 5.16.2 +# From the definitions ./opts.def +# and the template file agtexi-cmd.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/agen5/fsm.tpl} and the generated output +@file{pseudo-fsm.h}. + +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 @code{autogen} to +columnize input, a la the @code{ls} command. + +This section was generated by @strong{AutoGen}, +using the @code{agtexi-cmd} template and the option descriptions for the @code{columns} program. +This software is released under the GNU General Public License, version 3 or later. + +@menu +* columns usage:: columns help/usage (@option{--help}) +* columns dimensions:: dimensions options +* columns treatment:: treatment options +* columns ordering:: ordering options +* columns input-text:: input-text options +* columns config:: presetting/configuring columns +* columns exit status:: exit status +* columns See Also:: See Also +@end menu + +@node columns usage +@subsection columns help/usage (@option{--help}) +@cindex columns help + +This is the automatically generated usage text for columns. + +The text printed is the same whether selected with the @code{help} option +(@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print +the usage text by passing it through a pager program. +@code{more-help} is disabled on platforms without a working +@code{fork(2)} function. The @code{PAGER} environment variable is +used to select the program, defaulting to @file{more}. Both will exit +with a status code of 0. + +@exampleindent 0 +@example +columns (GNU AutoGen) - Columnize Input Text - Ver. 1.2 +USAGE: columns [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... + +Specify the output dimensions: + + Flg Arg Option-Name Description + -W Num width Maximum Line Width + - It must be in the range: + 16 to 4095 + -c Num columns Desired number of columns + - It must be in the range: + 1 to 2048 + -w Num col-width Set width of each column + - It must be in the range: + 1 to 2048 + Num tab-width tab width + +Specify how to lay out the text: + + Flg Arg Option-Name Description + Num spread maximum spread added to column width + - It must be in the range: + 1 to 1024 + no fill Fill lines with input + - prohibits these options: + spread + col-width + by-columns + -I Str indent Line prefix or indentation + Str first-indent First line prefix + - requires these options: + indent + -f Str format Formatting string for each input + -S Str separation Separation string - follows all but last + Str line-separation string at end of all lines but last + Str ending string at end of last line + +Specify the ordering of the entries: + + Flg Arg Option-Name Description + no by-columns Print entries in column order + -s opt sort Sort input text + +Redirecting stdin to an alternate file: + + Flg Arg Option-Name Description + -i Str input Input file (if not stdin) + +version, usage and configuration options: + + Flg Arg Option-Name Description + -v opt version Output version information and exit + -? no help Display extended usage information and exit + -! no more-help Extended usage information passed thru pager + -> opt save-opts Save the option state to a config file + -< Str load-opts Load options from a config file + - disabled as --no-load-opts + - may appear multiple times + +Options are specified by doubled hyphens and their name or by a single +hyphen and the flag character. + +The following option preset mechanisms are supported: + - reading file ./.columnsrc + - reading file $HOME/.columnsrc + - examining environment variables named COLUMNS_* +Packaged by Bruce (2012-08-11) +Report columns bugs to bkorb@@gnu.org +@end example +@exampleindent 4 + +@node columns dimensions +@subsection dimensions options +Specify the output dimensions. +@subsubheading width option (-W). +@anchor{columns width} +@cindex columns-width + +This is the ``maximum line width'' option. +This option takes an argument number @file{num}. +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. +@subsubheading columns option (-c). +@anchor{columns columns} +@cindex columns-columns + +This is the ``desired number of columns'' option. +This option takes an argument number @file{count}. +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. +@subsubheading col-width option (-w). +@anchor{columns col-width} +@cindex columns-col-width + +This is the ``set width of each column'' option. +This option takes an argument number @file{num}. +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. +@subsubheading tab-width option. +@anchor{columns tab-width} +@cindex columns-tab-width + +This is the ``tab width'' option. +This option takes an argument number @file{num}. +If an indentation string contains tabs, then this value is used to +compute the ending column of the prefix string. +@node columns treatment +@subsection treatment options +Specify how to lay out the text. +@subsubheading spread option. +@anchor{columns spread} +@cindex columns-spread + +This is the ``maximum spread added to column width'' option. +This option takes an argument number @file{num}. +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. Without this option, @file{columns} +will attempt to widen columns to fill the full width. +@subsubheading fill option. +@anchor{columns fill} +@cindex columns-fill + +This is the ``fill lines with input'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +spread, col_width, by_columns. +@end itemize + +Instead of columnizing the input text, fill the output lines +with the input lines. Blank lines on input will cause a +blank line in the output, unless the output is sorted. +With sorted output, blank lines are ignored. +@subsubheading indent option (-I). +@anchor{columns indent} +@cindex columns-indent + +This is the ``line prefix or indentation'' option. +This option takes an argument string @file{l-pfx}. +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. +@subsubheading first-indent option. +@anchor{columns first-indent} +@cindex columns-first-indent + +This is the ``first line prefix'' option. +This option takes an argument string @file{l-pfx}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must appear in combination with the following options: +indent. +@end itemize + +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. If its length exceeds "indent", then it +will be emitted on a line by itself, suffixed by any line separation +string. For example: + +@example +$ columns --first='#define TABLE' -c 2 -I4 --line=' \' <<_EOF_ +one +two +three +four +_EOF_ +#define TABLE \ + one two \ + three four +@end example +@subsubheading format option (-f). +@anchor{columns format} +@cindex columns-format + +This is the ``formatting string for each input'' option. +This option takes an argument string @file{fmt-str}. +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. +@subsubheading separation option (-S). +@anchor{columns separation} +@cindex columns-separation + +This is the ``separation string - follows all but last'' option. +This option takes an argument string @file{sep-str}. +Use this option if, for example, you wish a comma to appear after +each entry except the last. +@subsubheading line-separation option. +@anchor{columns line-separation} +@cindex columns-line-separation + +This is the ``string at end of all lines but last'' option. +This option takes an argument string @file{sep-str}. +Use this option if, for example, you wish a backslash to appear at +the end of every line, except the last. +@subsubheading ending option. +@anchor{columns ending} +@cindex columns-ending + +This is the ``string at end of last line'' option. +This option takes an argument string @file{end-str}. +This option puts the specified string at the end of the output. +@node columns ordering +@subsection ordering options +Specify the ordering of the entries. +@subsubheading by-columns option. +@anchor{columns by-columns} +@cindex columns-by-columns + +This is the ``print entries in column order'' option. +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. +@subsubheading sort option (-s). +@anchor{columns sort} +@cindex columns-sort + +This is the ``sort input text'' option. +This option takes an optional argument string @file{key-pat}. +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 input-text +@subsection input-text options +Redirecting stdin to an alternate file. +@subsubheading input option (-i). +@anchor{columns input} +@cindex columns-input + +This is the ``input file (if not stdin)'' option. +This option takes an argument string @file{file}. +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. + + +@node columns config +@subsection presetting/configuring columns + +Any option that is not marked as @i{not presettable} may be preset by +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 +the options listed above in upper case and segmented with underscores. +The @code{COLUMNS} variable will be tokenized and parsed like +the command line. The remaining variables are tested for existence and their +values are treated like option arguments. + + +@noindent +@code{libopts} will search in 2 places for configuration files: +@itemize @bullet +@item +$PWD +@item +$HOME +@end itemize +The environment variables @code{PWD}, and @code{HOME} +are expanded and replaced when @file{columns} runs. +For any of these that are plain files, they are simply processed. +For any that are directories, then a file named @file{.columnsrc} is searched for +within that directory and processed. + + +Configuration files may be in a wide variety of formats. +The basic format is an option name followed by a value (argument) on the +same line. Values may be separated from the option name with a colon, +equal sign or simply white space. Values may be continued across multiple +lines by escaping the newline with a backslash. + +Multiple programs may also share the same initialization file. +Common options are collected at the top, followed by program specific +segments. The segments are separated by lines like: +@example +[COLUMNS] +@end example +@noindent +or by +@example +<?program columns> +@end example +@noindent +Do not mix these styles within one configuration file. + +Compound values and carefully constructed string values may also be +specified using XML syntax: +@example +<option-name> + <sub-opt>...<...>...</sub-opt> +</option-name> +@end example +@noindent +yielding an @code{option-name.sub-opt} string value of +@example +"...<...>..." +@end example +@code{AutoOpts} does not track suboptions. You simply note that it is a +hierarchicly valued option. @code{AutoOpts} does provide a means for searching +the associated name/value pair list (see: optionFindValue). + +The command line options relating to configuration and/or usage help are: + +@subsubheading version (-v) + +Print the program version to standard out, optionally with licensing +information, then exit 0. The optional argument specifies how much licensing +detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. Only the +first letter of the argument is examined: + +@table @samp +@item version +Only print the version. This is the default. +@item copyright +Name the copyright usage licensing terms. +@item verbose +Print the full copyright usage licensing terms. +@end table + +@node columns exit status +@subsection columns exit status + +One of the following exit values will be returned: +@table @samp +@item 0 (EXIT_SUCCESS) +Successful program execution. +@item 1 (EXIT_FAILURE) +The operation failed or the command syntax was not valid. +@item 66 (EX_NOINPUT) +A specified configuration file could not be loaded. +@item 70 (EX_SOFTWARE) +libopts had an internal operational error. Please report +it to autogen-users@@lists.sourceforge.net. Thank you. +@end table +@node columns See Also +@subsection columns See Also +This program is documented more fully in the Columns section +of the Add-On chapter in the @code{AutoGen} Info system documentation. + |