home | help 
src2man(1)							      src2man(1)

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 cor-
     responding 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 cre-
	    ated 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 man-
	    page.

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>

txt2man-1.7.1			   2020-06-28			      src2man(1)
home | help