NAME¶
src2man - extract man pages from source files.
SYNOPSIS¶
src2man [-n][-d date][-v volume][-r release] [srcfile ...]
DESCRIPTION¶
src2man scans source file
srcfile. Only C source files are
supported for now. Comments blocks starting by "/** num", where num
is a section number, are converted into a man file, using
txt2man(1).
The first line of the comment block must contain the name of the manpage,
usually the function name, followed by a "-" and a short
description. The following lines are the "DESCRIPTION" section
content, except if they are in upper case, in which case they define a new
section.
If the next line after a comment block is empty, Then no "SYNOPSIS"
section will be generated. Otherwise,
src2man will look in the
following source lines for a function prototype or a type definion (struct,
union, typedef, ...) matching the manpage name, and include it in a
"SYNOPSIS" section. This avoids to duplicate the type or function
prototype in the comment block.
The best place for code documentation is in the source file, where the body is
implemented, not the header file which only contains the prototype.
src2man automatically searches for the presence of a prototype in the
corresponding header file, and if found, will print a "#include"
statement in the synopsis.
OPTIONS¶
- -d date
- Set the date of the man pages. Defaults to current date.
- -n
- No man page is created. The name of the manpages that would be created are
printed.
- -v volume
- Specify the name of the volume to be printed in center header of generated
manpages.
- -r release
- Specify the project name and release number for the generated
manpage.
ENVIRONMENT¶
- SOURCE_DATE_EPOCH
- Unix timestamp that is used for date in header instead of current
date.
EXAMPLE¶
The following example displays C code and comments to generate a manpage
foobar.3:
/** 3
* foobar - a sample dummy function
* This line is now the first of the description section.
* Note that function parameters parm1 and parm2 are highlighted
* in the generated man page.
*/
int foobar(char *parm1, int parm2)
{
...
return 0;
}
SEE ALSO¶
txt2man(1),
bookman(1).
AUTHOR¶
Marc Vertes <mvertes@free.fr>