NAME

       cli-generate - Generate source and documentation from CLI descriptions

SYNOPSIS

       cli-generate [ -c | -h | -m | -w ] FILENAME.cli

DESCRIPTION

   Operation
       cli-generate  reads in a CLI (command line interface) description file, parses it into its
       various sections, and prints out one of a set of output files.   In  typical  usage,  that
       output would be directed to a file and later compiled or included in other sources.

       The  CLI file (named PROGRAM.cli) is divided into two parts, a header (formatted much like
       a standard mail header) and a series of sections.  Headers and sections other  than  those
       specified below are ignored.  All headers and sections are optional.

   File Format
       file = header "\n" *section

       header = *(header-line "\n")

       header-line = header-field ":" whitespace value

       whitespace = *(SPACE / TAB)

       section = "[" name "]" "\n" lines

       lines = *( line "\n" )

   Headers
       Description:
              A one-line description of what the program does.

       Include:
              Add  C  statements  to #include the given source file.  Must be formatted as either
              <file> or file

       Min:   The minimum number of allowed non-option arguments.  Defaults to 0.

       Max:   The  maximum  number  of  allowed  non-option  arguments.   Negative  values   mean
              unlimited.  Defaults to -1.

       Show-Pid:
              Set  to  non-zero  if  the  resulting  program is to show its PID with every output
              message.  Defaults to 0.

       Usage: A one-line description of the intended usage.  Defaults to empty.

   Section Names
       [prefix]
              The text in this  section  is  shown  in  the  command  usage  before  the  options
              description.

       [options]
              The list of options this program accepts.  See below for their format.

       [suffix]
              The  text  in  this  section  is  shown  in  the  command  usage  after the options
              description.

       [description]

       [return value]

       [errors]

       [examples]

       [environment]

       [files]

       [see also]

       [notes]

       [caveats]

       [diagnostics]

       [bugs]

       [restrictions]

       [author]

       [history]
              These sections are formatted and copied into the man page in the standard order.

   Options Format
       options = *(option / separator)

       option = option1 "\n" option2 "\n" *(line "\n")

       option1 = [shortopt] [longopt] type ["=" flag-value] variable ["=" init]

       option2 = helpstr ["=" default]

       separator = "-- " text "\n"

       shortopt = "-" character

       longopt = "--" word

       type = "FLAG" / "COUNTER" / "INTEGER" / "UINTEGER" / "STRING" / "STRINGLIST" / "FUNCTION"

       If not specified, flag-value and init are 0, and default is empty.

   Formatting
       Except for [prefix], [options], and [suffix],  all  of  the  sections  support  formatting
       instructions similar to that of TeXinfo (but greatly simplified).

       @strong{text}
              Use "strong" (bold) text.

       @command{text}
              Indicate the name of a command.

       @option{text}
              Indicate a command-line option.

       @emph{text}
              Use "emphatic" (italicized) text.

       @var{text}
              Indicate a metasyntactic variable.

       @env{text}
              Indicate an environment variable.

       @file{text}
              Indicate the name of a file.

       @code{text}
              Indicate text that is a literal example of a piece of a program.

       @samp{text}
              Indicate text that is a literal example of a sequence of characters.

       @example

       @end example
              The text between these two tags is indented.

       @verbatim

       @end verbatim
              Everything between these two tags is passed as-is (verbatim) to the output.

       @table @format

       @end table
              Mark up a two-column table, or "definition list".

       @item paragraph
              Add  an item to a table.  The @item starts a paragraph that will be the actual list
              entry.  Any subsequent paragraphs will be typeset separately.

OPTIONS

       -c     Output C source code.

       -h     Output C header file.

       -m     Output a UNIX man page.

       -w     Output HTML (web) markup.

EXAMPLES

       Here is a sample CLI file, containing many of the described elements.

       Min: 1
       Max: 1
       Usage: PATH
       Description: Create a file.
       Show-Pid: 0
       Include: <stdio.h>

       [prefix]
       If the given PATH is a directory, it is suffixed with another name.

       [description]
       @program generates a new random file from a variety of sources including
       @command{ls} and @command{ps} output.

       If the given @option{PATH} is a directory, it is suffixed with another
       name of my choosing.

       [options]
       -v --verbose FLAG=1 opt_verbose

       -t --type STRING opt_type = "type1"
       The type of the file to generate. = type1
       Possible types for this include @option{type1} and @option{base64}.

AUTHOR

       Bruce Guenter <bruce@untroubled.org>

                                                                                  cli-generate(1)