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 identifier will be ignored entirely. In the case of a variable 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.

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 identifier. 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 declaration for the identifier(s) being documented.

Information in the PARAMETERS section is gleaned from the comments immediately before or after each parameter declaration. A comment after a parameter can follow the comma that separates that parameter from the next, if the comment 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 (ie: -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 Xexample below).

If a parameter is an enumerated type, all the possible values it can take are output, along with their descriptions. These descriptions are gleaned from the comments surrounding the enum identifiers where the type was defined. Comments describing enum identifiers are placed in a similar manner to those that describe function parameters. 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 identifier, 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: nothing" 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. /* 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.

Both C and C++ style comments are recognized, with seperate consecutive single-line comments coalesced into a 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. 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 */ }; /* 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. 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 comment 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 previous enumerator. /* 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.

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.

Typesetter specific commands may be included for more complex processing, although this isn't recommended since it ties you to a particular typesetter.

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: /* 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: yields:

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: /* 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: yields:

Character is alphanumeric.

Character is a letter.

Character is a control character.

Character is a digit.

Character is a graphic.

Character is a lower case letter.

Character is printable.

Character is punctuation.

Character is a a form of whitespace.

Character is an upper case letter.

Character is a hexadecimal digit.

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 identifier will be ignored entirely. In the case of a variable 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.

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 identifier. 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 declaration for the identifier(s) being documented.

Information in the PARAMETERS section is gleaned from the comments immediately before or after each parameter declaration. A comment after a parameter can follow the comma that separates that parameter from the next, if the comment 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 (ie: -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 Xexample below).

If a parameter is an enumerated type, all the possible values it can take are output, along with their descriptions. These descriptions are gleaned from the comments surrounding the enum identifiers where the type was defined. Comments describing enum identifiers are placed in a similar manner to those that describe function parameters. 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 identifier, 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: nothing" 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. /* 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.

Both C and C++ style comments are recognized, with seperate consecutive single-line comments coalesced into a 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. 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 */ }; /* 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. 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 comment 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 previous enumerator. /* 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.

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.

Typesetter specific commands may be included for more complex processing, although this isn't recommended since it ties you to a particular typesetter.

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: /* 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: yields:

Character is alphanumeric.

Character is a letter.

Character is a control character.

Character is a digit.

Character is a graphic.

Character is a lower case letter.

Character is printable.

Character is punctuation.

Character is a a form of whitespace.

Character is an upper case letter.

Character is a hexadecimal digit.

0 if the character doesn't fit the classification; non-zero (but not necessarily 1) if it does.

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, PROCEDURE and ROUTINE are also recognised, and treated identically to NAME. /* * Have a quick puff. * * Warning: Smoking causes lung cancer */ void go_for_a_smoke(); Generates a manual page with a WARNING section.