c2man Version 2
by Graham Stoney
Copyright (c) 1992-1996
Canon Information Systems Research Australia
All rights reserved.
c2man Version 3
by Mark O'Neill
Tumbling Dice, Newcastle upon Tyne UK, 2024
Version 3 is an update of Graham Stoney's original code (in K&R) format to make it more readable (and therefore maintainable). K&R function prototypes have been replaced by modern ANSI-C prototypes and the code has been re-structured to make it easier to debug (using symbolic debuggers such as gdb). In addition, support for 'prehistoric systems' (Sun, Apollo, HPUX, AIX and MSDOS) has been removed. Yes, they were great in their time, but they are functionally extinct now. Support in this release is primarily for Linux, but the code should build on BSD flavours, and probably CYGWIN and other POSIX compliant systems. The configuration script has been also been updated in order to make it easier to maintain (and support for legacy UNIX and other systems has been removed).
C2man is an automatic documentation tool that extracts comments from C source code to generate functional interface documentation in the same format as sections 2 & 3 of the Unix Programmer's Manual. It requires minimal effort from the programmer by looking for comments in the usual places near the objects they document, rather than imposing a rigid function-comment syntax or requiring that the programmer learn and use a typesetting language. Acceptable documentation can often be generated from existing code with no modifications.
The program can generate nroff/troff -man, TeXinfo, LaTeX or HTML output directly, and should run on virtually any Unix-like system, OS/2, VMS, MSDOS or Amiga systems.
You will need lex or flex, plus yacc or bison, and a C compiler (traditional K&R 1 or ISO/ANSI will do) to build the program. You'll also need a text formatter to format its output.
This version of c2man is copyright, but may be freely redistributed and modified so long as:
- The names of all contributing authors remain on the documentation,
- All derivative works are clearly documented as such,
- All derivative works remain freely redistributable under the same conditions.
As such, there is no warranty.
The manual page includes some automatically generated examples, which will be missing if you try to read it before doing a make. Running make will generate the complete manual page, which you can then copy around freely.
c2man does not currently support C++, but if you think this would be worth while, look in the file "C++autodoc" for information on how I envisage C++ support could be added, and get ready to volunteer. Note that this isn't related to the Commodore Amiga AutoDoc backend; the name's just a coincidence.
The file "FAQ" in the c2man distribution contains answers to a number of Frequently Asked Questions about c2man.
By popular demand, there are a few trivial examples of different comment styles in the "eg" directory. I'm open to submissions from users too.
There is a mailing list for c2man users; it is very low volume and has a very low noise content. This is the preferred place to ask questions about the program and discuss modifications and additions with the author and other users, but please check in the file "FAQ" first before asking questions on the list, in case I've already answered it. You are encouraged to join by sending mail with no Subject: line to [email protected] containing:
SUBSCRIBE c2man Your name
Where `Your name' should be replaced with your real name. Messages for distribution to everyone on the list should be sent to: [email protected].
The time I have available for c2man support is rather limited, but if it lacks any features you require, feel free to Email me (preferably to the mailing list address above) asking about it. Unless you request otherwise, I will probably cc: to the list replies to any questions that I get mailed, to save me answering them again for other people. I encourage you to go ahead and make any changes you like and send me the diffs for inclusion in the next patch, but it's a good idea to ask first in case someone already has the feature you want in the works. In order for me to integrate your changes, they need to be reasonably "clean", and you'll need to update manual page as appropriate.
Please try to remember to include the c2man version number in any bug reports. You can find it by running: c2man -V /dev/null
If you'd like to be notified automatically about new releases and patches, answer yes to the Configure question about sending mail to the author.
Special thanks for their direct and indirect contributions to c2man go to: Larry Wall, Raphael Manfredi, Harlan Stenn and the "dist" team, for writing various bits of metaconfig, which generated the Configure script.
Darrel Hankerson for the OS/2 and MSDOS ports.
Rick Flower for the VMS port.
Stefan Ruppert for the Amiga port, and AutoDoc backend.
Richard Kooijman for the LaTeX backend, and for fixing the TeXinfo backend.
Diab Jerius too, for more work on the TeXinfo backend.
Frank P.J. Ooms for the HTML backend.
Vern Paxson for his suggestions on how to handle comment lexing better.
Thanks to the following people for suggestions & bug fixes is long overdue: Peter (P.) Barszczewski, Carlo Tarantola, Dennis Allison, Philip Yzarn de Louraille, Jerry Lieberthal, Mats Ohrman, Stefan Zimmermann, Dolf Grunbauer, Lele Gaifax, Carl R. Crawford, Jhon Honce, Chris Borchert, Jerry E. Dunmire, Marty Leisner, Dan Forrest, Ken Weinert, Ken Poppleton, Michael Hamilton, Thomas E. Dickey, Marco Nijdam.
Finally, c2man owes a huge debt to the public domain program cproto, by Chin Huang, from which the original code was derived.
(Hmmm. This is beginning to sound like an Academy Awards night...)
See the file "INSTALL" for Unix installation instructions.
Graham Stoney [email protected] Mailing List for general c2man Questions & Answers [email protected]