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 seperately.
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)