cli-generate(1)

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>