.TH cli-generate 1
.SH NAME
cli-generate \- Generate source and documentation from CLI descriptions
.SH SYNOPSIS
.B cli-generate
[
.B -c
|
.B -h
|
.B -m
|
.B -w
]
.I FILENAME.cli
.SH DESCRIPTION
.SS Operation
.B 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 \fBPROGRAM\fI.cli\fR) 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.
.SS File Format
.nf
file = header "\\n" *section

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

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

whitespace = *(SPACE / TAB)

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

lines = *( line "\\n" )
.fi
.SS Headers
.TP
.B Description:
A one-line description of what the program does.
.TP
.B Include:
Add C statements to #include the given source file.  Must be formatted
as either
.I <file>
or
.I "file"
.TP
.B Min:
The minimum number of allowed non-option arguments.  Defaults to 0.
.TP
.B Max:
The maximum number of allowed non-option arguments.  Negative values
mean unlimited.  Defaults to -1.
.TP
.B Show-Pid:
Set to non-zero if the resulting program is to show its PID with every
output message.  Defaults to 0.
.TP
.B Usage:
A one-line description of the intended usage.  Defaults to empty.
.SS Section Names
.TP
.B [prefix]
The text in this section is shown in the command usage before the
options description.
.TP
.B [options]
The list of options this program accepts.  See below for their format.
.TP
.B [suffix]
The text in this section is shown in the command usage after the
options description.
.TP
.B [description]
.TP
.B [return value]
.TP
.B [errors]
.TP
.B [examples]
.TP
.B [environment]
.TP
.B [files]
.TP
.B [see also]
.TP
.B [notes]
.TP
.B [caveats]
.TP
.B [diagnostics]
.TP
.B [bugs]
.TP
.B [restrictions]
.TP
.B [author]
.TP
.B [history]
These sections are formatted and copied into the man page in the
standard order.
.SS Options Format
.nf
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"
.fi

If not specified,
.I flag-value
and
.I init
are
.IR 0 ,
and
.I default
is empty.
.SS Formatting
Except for
.BR [prefix] ,
.BR [options] ,
and
.BR [suffix] ,
all of the sections support formatting instructions similar to that of
TeXinfo (but greatly simplified).
.TP
.I @strong{text}
Use "strong" (bold) text.
.TP
.I @command{text}
Indicate the name of a command.
.TP
.I @option{text}
Indicate a command-line option.
.TP
.I @emph{text}
Use "emphatic" (italicized) text.
.TP
.I @var{text}
Indicate a metasyntactic variable.
.TP
.I @env{text}
Indicate an environment variable.
.TP
.I @file{text}
Indicate the name of a file.
.TP
.I @code{text}
Indicate text that is a literal example of a piece of a program.
.TP
.I @samp{text}
Indicate text that is a literal example of a sequence of characters.
.TP
.I @example
.TP
.I @end example
The text between these two tags is indented.
.TP
.I @verbatim
.TP
.I @end verbatim
Everything between these two tags is passed as-is (verbatim) to the
output.
.TP
.I @table @format
.TP
.I @end table
Mark up a two-column table, or "definition list".
.TP
.I @item paragraph
Add an item to a table.  The 
.I @item
starts a paragraph that will be the actual list entry.  Any subsequent
paragraphs will be typeset separately.
.SH OPTIONS
.TP
.B \-c
Output C source code.
.TP
.B \-h
Output C header file.
.TP
.B \-m
Output a UNIX man page.
.TP
.B \-w
Output HTML (web) markup.
.SH EXAMPLES
Here is a sample CLI file, containing many of the described elements.

.nf
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}.
.fi
.SH AUTHOR
Bruce Guenter <bruce@untroubled.org>