# *********************************************************************
# maketable.txt: help text
# Copyright (c) 2001,2006 Carlo Strozzi
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; version 2 dated June, 1991.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
#
# *********************************************************************
# $Id: maketable.txt,v 1.6 2006/03/10 11:26:13 carlo Exp $

                      NoSQL operator: maketable

Builds a valid table header from a table cross-reference file.

Usage: maketable [options]

Options:
    --input (-i) 'file'
      Read input from 'file' instead of STDIN.

    --output (-o) 'file'
      Write output to 'file' instead of STDOUT.

    --help (-h)
      Display this help text.

    --count (-c)
      Add a data record with field positions to the output table.
      The leftmost field actual content will depend also on '-K'.

    --add-row (-a)
      Add an empty  data record to the output table. If '-c' is
      also specified the added record will be formatted accordingly,
      accountig also for '-K'.

    --match (-m) 'pattern'   
      Consider only those fields which *names* match the
      given regular expression. 'pattern' must be a valid
      mawk(1) pattern without surrounding slashes.

    --set-key (-k) 'field'   
      If the input template contains 'field', the latter is
      printed as the leftmost column in the output table.

    --key (-K) 'string'
      Set the leftmost field to 'string' in the new row.
      Any NoSQL special characters in 'string' are automatically
      escaped. This switch implies '-a'.

    --names-only (-n)
      Strip '\001' characters from output. This is useful when the
      column names are to to be passed to another program as
      command-line arguments, a common case. If this option is
      specified, then options '-c', '-a' and '-K' are ignored.

Notes:

Takes a cross-reference file on stdin and prints the corresponding table
header to stdout. A cross-reference file is very similar to a 'list'
file, except that it only contains column names without the associated
values. Each column name may optionally be preceeded by its positional
number in the table header. For example:

##################################################
# Optional table comments
##################################################
1  Name1     Any comments ...
2  Name2     Any comments ...
3  Name3     Any comments ...
...

Field numbers are optional, and if they are present they must be
separated from the column names by blanks or tabs. Column documentation
comments are optional, and must be separated from the column name by
blanks and/or tabs. Warning: if the input list contains duplicated
entries, i.e. multiple rows with the same label (column name), the
resulting table may be broken.

Comments associated with specific columns may span over multiple rows,
provided that each continuation line begins with one or more blanks
and/or tabs.

