diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 112 |
1 files changed, 112 insertions, 0 deletions
@@ -0,0 +1,112 @@ + + c2man, Version 2 + by Graham Stoney + + Copyright (c) 1992-1996 + Canon Information Systems Research Australia + All rights reserved. + +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: + +1. The names of all contributing authors remain on the documentation, +2. All derivative works are clearly documented as such, +3. 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 <listserv@research.canon.com.au> 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: +<c2man@research.canon.com.au>. + + +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 greyham@research.canon.com.au +Mailing List for general c2man Questions & Answers c2man@research.canon.com.au |