packages icon



 C2MAN(1)                                                           C2MAN(1)
                                March 2, 1995



 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) 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:




                                    - 1 -          Formatted:  June 25, 2018






 C2MAN(1)                                                           C2MAN(1)
                                March 2, 1995



           % 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
      By default, a separate output file is generated for each global



                                    - 2 -          Formatted:  June 25, 2018






 C2MAN(1)                                                           C2MAN(1)
                                March 2, 1995



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



                                    - 3 -          Formatted:  June 25, 2018






 C2MAN(1)                                                           C2MAN(1)
                                March 2, 1995



      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.


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





                                    - 4 -          Formatted:  June 25, 2018






 C2MAN(1)                                                           C2MAN(1)
                                March 2, 1995



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




                                    - 5 -          Formatted:  June 25, 2018






 C2MAN(1)                                                           C2MAN(1)
                                March 2, 1995



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





                                    - 6 -          Formatted:  June 25, 2018






 C2MAN(1)                                                           C2MAN(1)
                                March 2, 1995



      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.

      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
      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);




                                    - 7 -          Formatted:  June 25, 2018






 C2MAN(1)                                                           C2MAN(1)
                                March 2, 1995



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




                                    - 8 -           Formatted:  June 25, 2018






 C2MAN(1)                                                            C2MAN(1)
                                March 2, 1995



           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;
                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



                                    - 9 -          Formatted:  June 25, 2018






 C2MAN(1)                                                           C2MAN(1)
                                March 2, 1995



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



                                   - 10 -          Formatted:  June 25, 2018






 C2MAN(1)                                                           C2MAN(1)
                                March 2, 1995



      -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



                                   - 11 -          Formatted:  June 25, 2018






 C2MAN(1)                                                           C2MAN(1)
                                March 2, 1995



           (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



                                   - 12 -          Formatted:  June 25, 2018






 C2MAN(1)                                                           C2MAN(1)
                                March 2, 1995



           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:




                                   - 13 -          Formatted:  June 25, 2018






 C2MAN(1)                                                           C2MAN(1)
                                March 2, 1995



                % 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
      /usr/local/lib/c2man/eg/*.[ch]
           A few example input files, showing different commenting 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 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
      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
      The -F option only interprets the following character escape



                                   - 14 -          Formatted:  June 25, 2018






 C2MAN(1)                                                           C2MAN(1)
                                March 2, 1995



      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.



































                                   - 15 -          Formatted:  June 25, 2018