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
copyright © 2001 Peter Seiderer for www.ciselant.de