# *********************************************************************
#  Written by and copyright Carlo Strozzi <carlos@linux.it>.
#
#  tabletoform.txt: help text
#  Copyright (C) 2001 Carlo Strozzi <carlos@linux.it>
# 
#  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; either version 2 of the License, or
#  (at your option) any later version.
# 
#  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.
#
# *********************************************************************

                      NoSQL operator: tabletoform

Takes a NoSQL table and uses the values from the last record
to replace special tags on a template file.

Usage: tabletoform [options] template

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.

    --prefix (-p) 'string'
      Prefix each input column name with 'string'.

    --eval (-e) tag1[,tag2, ...]
      The specified comma-separated tags are to be eval'ed, i.e.
      their actual values will be looked-up in environment. This
      is useful when there are tags that act simply as place-
      holders for values that cannot be known in advance: a
      temporary file name, for example.

    --strip-comments (-C)
      Print the statements necessary to remove comment-lines,
      (lines that start with a '#' character), from the
      specified template file.

    --trim (-t)
      Strip leading and trailing blanks from each input field
      name and field value.

    --content-type (-T) type/subtype
      Prepend a MIME header for the specified type/subtype to
      the target template before printing the latter to STDOUT.

    --advertise (-a) 'string'
      Print the additional MIME header 'X-Powered-By: string' just
      before the usual 'Content-Type' header. This applies only
      if '-t' is also specified.

    --file-root (-R) 'path'
      In the normal case, if a replacement tag contains one or
      more '/' characters, it is interpreted as an external file
      name to include, relative to the current working directory.
      If this option is set, then a *relative* file tag is considered
      to be relative to 'path'. Absolute file tags will still be
      taken literally. Note: the program will make use of the 'path'
      string as is, including any '../' patterns that it may contain,
      so watch out. This has been done deliberately to provide more
      flexibility.

Notes:

Takes a single-record table and a template file, and uses the former
to make substitutions and file-inclusions in the latter, based on
special tags. The replacement points are marked by the string $[Tag],
where "Tag" can be a column name of the input table, or a file
reference. If the input table has more than one record, then only the
last one will be used. Tags that contain '/' characters are
considered to be file names, and the corresponding file, if found, is read
into the template file at the point where that tag occurs. File tags
that contain '..' patterns are not honoured, for security reasons.
File tags can be followed by a semicolon and a letter. The letter
specifies the type of encoding that is to be performed on the file
being included. Valid letters are:

  m = Base64 encoding (MIME)
  q = quoted printable
  u = uuencode

For example, a tag in the form $[/my/file:m] will cause /my/file
to be Base64-encoded before it is inserted.

Although the functionality provided by this operator could also be
done with sed(1), the latter is more than ten-times slower on a
large number of replacements (>= 500), and it also takes one extra
process (sed).

$Id$
