C2MAN(1) C2MAN(1)
NAME
c2man - generate manual pages from C source code
SYNOPSIS
c2man [ option ... ] [ file ... ]
DESCRIPTION
c2man reads C source code files in which comments have
been strategically placed, and outputs manual page(s) doc
umenting each function defined or declared (via a proto
type), and optionally each variable with global scope.
Function definitions and declarations may be in the old
style or ISO/ANSI style. If no file argument is given,
c2man takes its input from the standard input.
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 inter
face 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 */);
February 25, 2000 1
C2MAN(1) C2MAN(1)
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:
dowork(3) UNIX Programmer's Manual dowork(3)
NAME
dowork - do some useful work for a change.
SYNOPSIS
#include <example.h>
int dowork
(
int count,
enum Place where,
long fiveoclock
);
PARAMETERS
int count
How much work to do.
enum Place where
Where to do the work.
Possible values for an enum Place
are as follows:
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.
long fiveoclock
When to knock off.
DESCRIPTION
This function will actually get some pro
ductive work done, if you are really lucky.
RETURNS
The number of milliseconds in a second.
February 25, 2000 2
C2MAN(1) C2MAN(1)
Output Generation
By default, a separate output file is generated for each
global identifier (i.e. function or variable) documented
by c2man.
Much of c2man's information is extracted from the comment
placed immediately before the declaration/definition of
the identifier being documented; this comment is taken to
describe the identifier and must be present, or the iden
tifier will be ignored entirely. In the case of a vari
able declaration/definition, this comment may instead be
placed after it starting on the same line.
Global variables are not documented, unless the -v option
is used.
Identifiers declared static are ignored by default unless
the file is a header file (which is most useful with
inline functions) or the -s option is used.
Declarations with the extern keyword are ignored unless
they appear in a header file; note that this does not
include function definitions.
Sections Generated Automatically
Each manual page starts with a NAME section, listing the
name(s) of the identifier(s) documented, along with a
terse description. By default, this description is the
first line or sentence of the comment describing the iden
tifier. With the -g option, it is found after the first
dash (-) in the first comment of the file, and the -G
option specifies it explicitly.
The SYNOPSIS section begins with an #include line if the
source file is a header. After this is an external decla
ration for the identifier(s) being documented.
Information in the PARAMETERS section is gleaned from the
comments immediately before or after each parameter decla
ration. A comment after a parameter can follow the comma
that separates that parameter from the next, if the com
ment starts on the same line and is the only remaining
thing on that line. Leading underscores in a parameter
name are stripped when printed in the manual page.
If the manual page is for a group of functions (i.e. -g
or -G options), identical parameters (in both name and
type) common to more than one function are described only
once if only one has a comment (as in the ctype example
below).
If a parameter is an enumerated type, all the possible
values it can take are output, along with their descrip
tions. These descriptions are gleaned from the comments
February 25, 2000 3
C2MAN(1) C2MAN(1)
surrounding the enum identifiers where the type was
defined. Comments describing enum identifiers are placed
in a similar manner to those that describe function param
eters. enum identifiers that begin with an underscore are
ignored, which is useful for padding or _NUMBER_OF_...
values which aren't normally used by someone calling the
function. If none of the identifiers in an enumerated
type has a comment, c2man will bunch them together to save
space.
The DESCRIPTION section contains everything after the
first line or sentence of the comment describing the iden
tifier, up until the word ``returns'' at the start of a
line, matched case-insensitively and optionally followed
by a colon (:). In the case of a variable of enumerated
type, it will also list all the values it can hold.
The RETURNS section contains anything after that. Any of
these lines that begin with a single word followed by a
colon or a tab generate tagged paragraphs so that lists of
possible return values and error codes look neat. If the
function is void, don't put anything like "Returns: noth
ing" in the comment, since it's a waste of space. If the
identifier is a function returning an enumerated type, its
possible values will be listed here.
The RETURNS section is also added if there is a comment
after the function return type.
For example:
/* Sample function */
char * /* NULL if failed string otherwise */
sample_function()
{
}
The RETURNS section will contain the full contents of the
comment (stripping the optional leading asterisk). It is
not possible to use both methods to specify a description
for the return value. In that case the comment after the
return type supersedes whatever was specified for the
return value in the comment above the function.
Finally, a SEE ALSO section is generated, referencing all
the other manual pages generated, if any.
The RETURNS, PARAMETERS and SEE ALSO sections are omitted
entirely if they aren't needed.
Comment Style and Placement
Both C and C++ style comments are recognized, with sepa
rate consecutive single-line comments coalesced into a
February 25, 2000 4
C2MAN(1) C2MAN(1)
single block. When looking at comments, c2man ignores
everything before the first alpha-numeric character. After
that, it ignores leading white-space, leading asterisks
and leading slashes on all subsequent lines, and ignores
all trailing lines thus rendered blank. If that leaves
nothing, the comment is ignored entirely. This makes it
very flexible in supporting popular comment boxing.
Comments can be placed with considerable flexibility so
that most commenting styles are supported.
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 */
};
/* 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 */
};
February 25, 2000 5
C2MAN(1) C2MAN(1)
/* 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
};
But the following example is NOT equivalent because the
commas are between the identifier and the its associated
comment, and the comment is on a different line. Each
comment actually applies to the wrong identifier, so this
will result in very misleading output.
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 */
};
Since enum identifiers sometimes fall into logical groups,
a comment before such an identifier will be taken to apply
to the next few in the list, provided that the comments
describing each individual identifier are placed after
them. Also, there must be a blank line separating the com
ment describing the next logical group and the comment at
the end of the previous line, or the two will be coalesced
and incorrectly treated as a single comment for the previ
ous enumerator.
February 25, 2000 6
C2MAN(1) C2MAN(1)
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 */
};
That may all sound a bit complex, but the upshot is that
c2man will usually know which identifier a comment is
associated with, unless you do something truly bizarre.
Processing of Comment Contents
Basic punctuation and capitalisation corrections are made
in each section for neatness, and the typesetting program
used to process the output will generally reformat line
breaks according to the width of the output device. Blank
lines in a comment will be preserved, and lines starting
with a dash (-), an asterisk (*), or a numbered point
((n), n) or n.), will cause a line break, allowing simple
bulleted or numbered lists.
Lines beginning with a tab after the comment leader will
be output verbatim without reformatting, to allow source
code to be embedded in the comments.
Typesetter specific commands may be included for more com
plex processing, although this isn't recommended since it
ties you to a particular typesetter.
Grouped Manual Pages
Simple, closely related objects can be grouped together
onto a single page with the -g or -G options. By default,
this results in a single output file with multiple links
so that it can be accessed by the name of the input file,
or of any identifier documented. For example, if ctype.h
contains:
February 25, 2000 7
C2MAN(1) C2MAN(1)
/* 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);
then using:
% c2man -g ctype.h
yields:
February 25, 2000 8
C2MAN(1) C2MAN(1)
ctype(3) UNIX Programmer's Manual ctype(3)
NAME
isalnum, isalpha, iscntrl, isdigit,
isgraph, islower, isprint, ispunct, iss
pace, isupper, isxdigit - character classi
fication functions
SYNOPSIS
#include <ctype.h>
inline int isalnum(int c);
inline int isalpha(int c);
inline int iscntrl(int c);
inline int isdigit(int c);
inline int isgraph(int c);
inline int islower(int c);
inline int isprint(int c);
inline int ispunct(int c);
inline int isspace(int c);
inline int isupper(int c);
inline int isxdigit(int c);
PARAMETERS
int c The character to classify.
DESCRIPTION
isalnum
Character is alphanumeric.
isalpha
Character is a letter.
iscntrl
Character is a control character.
isdigit
Character is a digit.
isgraph
Character is a graphic.
islower
Character is a lower case letter.
February 25, 2000 9
C2MAN(1) C2MAN(1)
isprint
Character is printable.
ispunct
Character is punctuation.
isspace
Character is a a form of whitespace.
isupper
Character is an upper case letter.
isxdigit
Character is a hexadecimal digit.
RETURNS
isalnum
0 if the character doesn't fit the classi
fication; non-zero (but not necessarily 1)
if it does.
Extra Sections
Additional sections not otherwise recognized by c2man can
be included in the manual page by including them in the
comment describing the identifier. A section heading is
preceded in the comment by an empty line (after removal of
leading asterisks), and is the only word on it's line, or
is a word followed by a colon (:), or is a line ending
with a colon, so section names with spaces are allowed,
like "Return value:".
Section heading names are capitalized, and the names
DESCRIPTION, RETURNS and NAME are recognized specially so
you can name them explicitly if you like. FUNCTION, PRO
CEDURE and ROUTINE are also recognised, and treated iden
tically to NAME.
/*
* Have a quick puff.
*
* Warning: Smoking causes lung cancer
*/
void go_for_a_smoke();
Generates a manual page with a WARNING section.
OPTIONS
-odir Write generated files into directory dir rather
than the current directory. If dir is specified as
February 25, 2000 10
C2MAN(1) C2MAN(1)
-, generated pages are written to the standard out
put, 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.
For example:
-k Don't attempt to fix up capitalization and punctua
tion.
-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 docu
mented 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.
February 25, 2000 11
C2MAN(1) C2MAN(1)
-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 lan
guage specific options. options is a comma delim
ited 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 pre
vents 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 sec
tion, 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
February 25, 2000 12
C2MAN(1) C2MAN(1)
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 speci
fied (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 exten
sion 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 exten
sion to be specified for these different classes of
objects: functions (f), variables (v), static func
tions (F) and static variables (V).
If subdir is specified, the selected class of out
put will be written in that subdirectory under the
directory given by the -o option if specified, oth
erwise under the current directory.
If .ext is specified, it will be used as the exten
sion on the output files of the selected class,
instead of the default based on the -S option (if
specified), or the typesetting output format speci
fied 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 sec
tion 3v (/usr/local/man/man3/*.3v), static func
tions 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
February 25, 2000 13
C2MAN(1) C2MAN(1)
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)"
will produce:
int main(
int argc,
char *argv[]
)
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
February 25, 2000 14
C2MAN(1) C2MAN(1)
conditionals such as #ifdef.
-Uname This option is passed through to the preprocessor
and is used to remove any definitions of this sym
bol.
-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 com
menting styles.
SEE ALSO
man(1), apropos(1), catman(8), cproto(1), cc(1), cpp(1)
DIAGNOSTICS
c2man's error messages are not very helpful, so make sure
your code compiles before trying c2man. If the code com
piles OK but c2man rejects it, it may be because a comment
is in a position c2man does not accept, or you are using a
compiler extension not strictly conforming to standard C.
c2man defines the preprocessor symbol __C2MAN__ with its
major version number to allow you to work around such
problems by surrounding them with #ifndef __C2MAN__.
An error at the very end of a function may indicate that
the comments at the beginning are badly placed.
HISTORY
c2man was originally written by:
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 contribu
tors since then, and to Chin Huang, the author of cproto
from which it was originally derived.
BUGS
The -F option only interprets the following character
escape sequences:
\n newline
\t tab
February 25, 2000 15
C2MAN(1) C2MAN(1)
A comment before a preprocessor directive will be consid
ered to apply to the identifier that immediately follows,
if it has no comment of its own. This is because the pre
processor 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 dif
ferent tastes.
February 25, 2000 16
|