NAME

SYNOPSIS

DESCRIPTION

If a .h file is written as a formal interface description when preparing an interface spec, c2man can generate all the manual pages required for the spec at one fell swoop, and then keep them up to date automatically as the interface changes.

Since c2man will accept either function definitions or prototypes, it can be used on either .c or .h files. If the input is a header file, any files specified by -i options are assumed to be prerequisites, and get parsed before the input file. (Any file whose extension begins with ``h'', matched case-insensitively, is considered a header file.)

This is potentially a huge win for most programmers that just love documenting their functions, and updating the documentation every time it changes. Here's an example, named example.h:

enum Place
{
    HOME,      /* Home, Sweet Home */
    WORK,      /* where I spend lots of time */
    MOVIES,    /* Saturday nights mainly */
    CITY,      /* New York, New York */
    COUNTRY    /* Bob's Country Bunker */
};
/*
 * do some useful work for a change.
 * This function will actually get some productive
 * work done, if you are really lucky.
 * returns the number of milliseconds in a second.
 */
int dowork(int count,        /* how much work to do */
           enum Place where, /* where to do the work */
           long fiveoclock   /* when to knock off */);

When:

% c2man example.h

is run, this produces a file named dowork.3 which can be processed by man(1) or used as:

% nroff -man dowork.3

to produce:

NAME

SYNOPSIS

PARAMETERS

DESCRIPTION

RETURNS

5 For example: /* Sample function */
char *			/* NULL if failed string otherwise */
sample_function()
{
}

13 The following variations of the enum definition in the dowork.h example are all equivalent: /* commas after the comments. */
enum Place
{
    HOME       /* Home, Sweet Home */,
    WORK       /* where I spend lots of time */,
    MOVIES     /* Saturday nights mainly */,
    CITY       /* New York, New York */,
    COUNTRY    /* Bob's Country Bunker */
};

16 /* the comment needn't go on the same line,
 * if the comma goes after the comment.
 */
enum Place
{
    HOME
    	/* Home, Sweet Home */,
    WORK
    	/* where I spend lots of time */,
    MOVIES
    	/* Saturday nights mainly */,
    CITY
    	/* New York, New York */,
    COUNTRY
    	/* Bob's Country Bunker */
};

14 /* the comment can go before it too. */
enum Place
{
    /* Home, Sweet Home */
    HOME,
    /* where I spend lots of time */
    WORK,
    /* Saturday nights mainly */
    MOVIES,
    /* New York, New York */
    CITY,
    /* Bob's Country Bunker */
    COUNTRY
};

16 Don't do this: enum Place
{
    HOME,
    	/* Home, Sweet Home */
    WORK,
    	/* where I spend lots of time */
    MOVIES,
    	/* Saturday nights mainly */
    CITY,
    	/* New York, New York */
    COUNTRY
    	/* Bob's Country Bunker */
};

17 In other words, you can go: /* include logical grouping comments. */
enum Place
{
    /* These take up most of the week */
    HOME,      /* Home, Sweet Home */
    WORK,      /* where I spend lots of time */
    /* More for special occasions */
    MOVIES,     /* Saturday nights mainly */
    CITY,      /* New York, New York */
    /* The real favourite */
    COUNTRY    /* Bob's Country Bunker */
};

/* ctype.h - character classification functions */
/* character is alphanumeric
 * returns 0 if the character doesn't fit the
 * classification; non-zero (but not necessarily 1)
 * if it does.
 */
inline int isalnum(int c	/* the character to classify */);
/* character is a letter */
inline int isalpha(int c);
/* character is a control character */
inline int iscntrl(int c);
/* character is a digit */
inline int isdigit(int c);
/* character is a graphic */
inline int isgraph(int c);
/* character is a lower case letter */
inline int islower(int c);
/* character is printable */
inline int isprint(int c);
/* character is punctuation */
inline int ispunct(int c);
/* character is a a form of whitespace */
inline int isspace(int c);
/* character is an upper case letter */
inline int isupper(int c);
/* character is a hexadecimal digit */
inline int isxdigit(int c);

NAME

SYNOPSIS

PARAMETERS

DESCRIPTION

RETURNS

9 For example: /*
 * Have a quick puff.
 * 
 * Warning: Smoking causes lung cancer
 */
void go_for_a_smoke();

OPTIONS

-odir

Write generated files into directory dir rather than the current directory. If dir is specified as -, generated pages are written to the standard output, separated by form-feeds.

-v

Also output declarations for variables defined in the file.

-s

Output manual pages for all static identifiers.

-g

Group all the info generated together into a single page (ala ctype(3)), reading the single-line terse description for the NAME section from the line of the first comment in the file. If this first line contains a dash (-) surrounded by whitespace, the terse description is taken starting after the dash. If multiple files are specified, the first such suitable comment encountered is used. A link to the output file is made for each identifier documented, according to the -l option.

-Gterse

Like -g, but using the specified terse description rather than reading it from the file.

-k

Don't attempt to fix up capitalization and punctuation.

-b

If a function lacks a preceding comment, look for one immediately following the curly-brace at the top of the function body. The comment must appear before anything else.

-B

Apply -b strictly. Only look for the description of a function at the top of its body.

-l h|s|f|n|r

Select how the output for a grouped manual page is linked to files named after all identifiers documented on the page. Hard link (h) is the default, as it uses the least space. Soft link (s), where supported, allows a find(1) command with ``-type f'' to easily skip the duplicated pages. Separate file (f) containing a file include directive is the traditional UNIX method. No link (n) is useful for generating printed documentation without duplicated pages; only a single file, named according to the -n option, is generated. Remove (r) is like No link, but also removes any previously generated links/files named after the identifiers documented. Useful for cleaning up after accidents with the other link options.

In all cases, any existing links will be removed before being rewritten.

-n

Name the documentation output file after the input file. When generating grouped manual pages, this will be the file to which others are linked. For non-grouped manual pages, if documentation for more than one identifier is generated, information about the last identifier will overwrite information about all the previous ones.

-ifile

-i"file"

-i<file>

Insert a #include line referencing the specified file in the SYNOPSIS section, using the ``<file>'' form by default. Any number of -i options may be specified to build up a list of prerequisites. If using the second form, you may need to quote the quotation marks, lest they get removed by the shell.

-xsectionname

Exclude sectionname from the generated man pages. This option may be repeated to exclude a number of sections.

-Hheader-path

Prepend header-path to the name of the header file when an #include line is automatically generated in the SYNOPSIS section.

-L

Lazy option: Only list parameters in the PARAMETERS section if they are documented by a comment in the source. By default, parameters with no comment are described as ``Not Documented.'', to encourage the programmer to comment them.

-Tn|l|t|h|a[,options]

Set the output typesetting language as well as language specific options. options is a comma delimited list of options. Nroff (n) is the default, LaTeX (l) , Texinfo (t) , HTML (h) , AutoDoc (a). , or Raw text (r). Texinfo specific options are s, t, n, and C.

In Texinfo mode, each section is normally coded as a ``heading'' rather than a ``section''. This prevents the section name from appearing in the table of contents. If the option t is given, the name of the man page is used for the title of the NAME section, and is encoded as a ``section'', placing it in the table of contents. Subsequent sections are encoded as ``headings''. Texinfo supports multiple levels of headings; the desired level may be specified via the sn option, where n starts at 0 for the ``chapter level'' and works down. A top level node is created for the man page, except when in embedded mode (the c2man -e option). If the n option is specified, a node is created in embedded mode, but without Up, Previous, or Next pointers; these must be filled in (Texinfo mode in emacs does a good job of it). The C option capitalizes the section titles. Usually they are printed as specified (which is usually upper case).

-e

Prepares the output so it can be embedded in texts of the output typesetting language.

-Mname

Set the name of the manual in which the page will go.

-Ssection

Set the default manual section, used as the extension on the output files. section defaults to ``3'' for nroff, ``texi'' for Texinfo , ``html'' for HTML and ``tex'' for LaTeX output, as specified via the -T option. This setting can be overridden by the -O?.ext options for finer control.

-Of|v|F|V[subdir][.ext]

Provides for finer control of the output files, allowing a different output subdirectory and extension to be specified for these different classes of objects: functions (f), variables (v), static functions (F) and static variables (V).

If subdir is specified, the selected class of output will be written in that subdirectory under the directory given by the -o option if specified, otherwise under the current directory.

If .ext is specified, it will be used as the extension on the output files of the selected class, instead of the default based on the -S option (if specified), or the typesetting output format specified by the -T option.

For example, the following command will generate nroff(1) style output under the /usr/local/man hierarchy, documenting functions in section 3 (/usr/local/man/man3/*.3), global variables in section 3v (/usr/local/man/man3/*.3v), static functions in section 9 (/usr/local/man/man9/*.9) and static variables in section 9v (/usr/local/man/man9/*.9v):

% c2man -o/usr/local/man -v -s -Ofman3.3 -Ovman3.3v -OFman9.9 -OVman9.9v input.c

The -O options will have no effect if -o- is used to write to standard output, and -Ov, -OF and -OV will have no effect unless their classes of output are enabled via the appropriate -v and -s options.

-Ftemplate

Set the format used to output the prototype for functions with more than 1 parameter in each manual page; functions with zero or 1 parameters are always output as one line. The format is specified by a template in the form

" int f ( a, b )"

    

but you may replace each space in this string with any number of whitespace characters. For example, the option

-F"int f(\n\ta,\n\tb\n\t)"

    

5 will produce: int main(
        int argc,
        char *argv[]
        )

    

5 The default output format is: int main
(
        int argc,
        char *argv[]
);
    

-Ppreprocessor

Run a different C preprocessor than normal (use -V to determine the configured default). You must include any options required to prevent it from stripping comments, which is normally the default preprocessor behaviour. For example, to use gcc's cpp instead:

% c2man -P "gcc -E -C"

-Dname[=value]

This option is passed through to the preprocessor and is used to define symbols for use with conditionals such as #ifdef.

-Uname

This option is passed through to the preprocessor and is used to remove any definitions of this symbol.

-Idirectory

This option is passed through to the preprocessor and is used to specify a directory to search for files that are referenced with #include.

-V

Print version information and cpp parameters.

FILES

/usr/local/lib/c2man/eg/*.[ch]

A few example input files, showing different commenting styles.

SEE ALSO

DIAGNOSTICS

An error at the very end of a function may indicate that the comments at the beginning are badly placed.

HISTORY

Graham Stoney
Canon Information Systems Research Australia
greyham@research.canon.com.au
(please send bug reports here)

Many thanks are due to the many other Internet contributors since then, and to Chin Huang, the author of cproto from which it was originally derived.

BUGS

2 \n	newline
\t	tab

A comment before a preprocessor directive will be considered to apply to the identifier that immediately follows, if it has no comment of its own. This is because the preprocessor directive gets removed by cpp before c2man looks at it.

Comments aren't legal in some of the more obscure places that they are in C.

Heavy use of #define in a program may yield somewhat obscure manual pages.

c2man's output backends may not be entirely consistent, but then users of different formatters tend to have different tastes.