*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Linux man pages -> c2man (1)              
Title
Content
Arch
Section
 

C2MAN(1)

Contents


NAME    [Toc]    [Back]

       c2man - generate manual pages from C source code

SYNOPSIS    [Toc]    [Back]

       c2man [ option ...  ] [ file ...  ]

DESCRIPTION    [Toc]    [Back]

       c2man  reads  C source code files in which comments have been strategically
 placed, and outputs  manual  page(s)  documenting	each  function
       defined	or  declared  (via  a prototype), 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 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:

	  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 productive work
		 done, if you are really lucky.

	  RETURNS
		 The number of milliseconds in a second.


   Output Generation    [Toc]    [Back]
       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.

   Sections Generated Automatically    [Toc]    [Back]
       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 enu-
       merated 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.


       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    [Toc]    [Back]
       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.


       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 */
	    };


	    /* 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
       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.


       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    [Toc]    [Back]
       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.

   Grouped Manual Pages    [Toc]    [Back]
       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:

	    % c2man -g ctype.h

       yields:

	  ctype(3)     UNIX Programmer's Manual     ctype(3)

	  NAME
		 isalnum,  isalpha,  iscntrl,  isdigit, isgraph, islower,
		 isprint, ispunct, isspace, isupper, isxdigit - character
		 classification 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.

	     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 classification; nonzero
 (but not necessarily 1) if it does.


   Extra Sections    [Toc]    [Back]
       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.


       For example:

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

       Generates a manual page with a WARNING section.

OPTIONS    [Toc]    [Back]

       -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 manpages.  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) , or
	      AutoDoc (a).  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 manpage 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	manpage,  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)"



	      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 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    [Toc]    [Back]

       /usr/share/doc/c2man/eg/*.[ch]
	      A few example input files, showing different commenting  styles.

SEE ALSO    [Toc]    [Back]

      
      
       man(1), apropos(1), catman(8), cproto(1), cc(1), cpp(1)

DIAGNOSTICS    [Toc]    [Back]

       c2man's	error  messages  are  not very helpful, so make sure your code
       compiles before trying c2man.   If  the	code  compiles	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    [Toc]    [Back]

       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 contributors since then,
       and  to	Chin  Huang, the author of cproto from which it was originally
       derived.

BUGS    [Toc]    [Back]

       The -F option only interprets the following character escape sequences:

	    \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.



				 March 2, 1995			      C2MAN(1)
[ Back ]
 Similar pages
Name OS Title
manctl FreeBSD manipulating manual pages
getNAME FreeBSD get name sections from manual pages
fixman HP-UX fix manual pages for faster viewing with man(1)
man OpenBSD display the on-line manual pages
catman Linux create or update the pre-formatted manual pages
man FreeBSD format and display the on-line manual pages
manpath Linux determine search path for manual pages
whereis IRIX locate source, binary, and or manual for program
whereis HP-UX locate source, binary, and/or manual for program
sdoc FreeBSD guide to adding security considerations sections to manual pages
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service