1
2 c2man, Version 2
3 by Graham Stoney
4
5 Copyright (c) 1992-2000
6 Canon Information Systems Research Australia
7 All rights reserved.
8
9C2man is an automatic documentation tool that extracts comments from C source
10code to generate functional interface documentation in the same format as
11sections 2 & 3 of the Unix Programmer's Manual. It requires minimal effort from
12the programmer by looking for comments in the usual places near the objects
13they document, rather than imposing a rigid function-comment syntax or
14requiring that the programmer learn and use a typesetting language. Acceptable
15documentation can often be generated from existing code with no modifications.
16
17The program can generate nroff/troff -man, TeXinfo, LaTeX or HTML output
18directly, and should run on virtually any Unix-like system, OS/2, VMS, MSDOS or
19Amiga systems.
20
21You will need lex or flex, plus yacc or bison, and a C compiler (traditional
22K&R 1 or ISO/ANSI will do) to build the program. You'll also need a text
23formatter to format its output.
24
25This version of c2man is copyright, but may be freely redistributed and modified
26so long as:
27
281. The names of all contributing authors remain on the documentation,
292. All derivative works are clearly documented as such,
303. All derivative works remain freely redistributable under the same conditions.
31
32As such, there is no warranty.
33
34The manual page includes some automatically generated examples, which will be
35missing if you try to read it before doing a make. Running make will generate
36the complete manual page, which you can then copy around freely.
37
38c2man does not currently support C++, but if you think this would be worth
39while, look in the file "C++autodoc" for information on how I envisage C++
40support could be added, and get ready to volunteer. Note that this isn't
41related to the Commodore Amiga AutoDoc backend; the name's just a coincidence.
42
43The file "FAQ" in the c2man distribution contains answers to a number of
44Frequently Asked Questions about c2man.
45
46By popular demand, there are a few trivial examples of different comment
47styles in the "eg" directory. I'm open to submissions from users too.
48
49
50There is a mailing list for c2man users; it is very low volume and has a very
51low noise content. This is the preferred place to ask questions about the
52program and discuss modifications and additions with the author and other
53users, but please check in the file "FAQ" first before asking questions on the
54list, in case I've already answered it. You are encouraged to join by sending
55mail with no Subject: line to <majordomo@research.canon.com.au> containing:
56
57 SUBSCRIBE c2man
58
59Messages for distribution to everyone on the list should be sent to:
60<c2man@research.canon.com.au>.
61
62
63The time I have available for c2man support is rather limited, but if it lacks
64any features you require, feel free to Email me (preferably to the mailing list
65address above) asking about it. Unless you request otherwise, I will probably
66cc: to the list replies to any questions that I get mailed, to save me
67answering them again for other people. I encourage you to go ahead and make
68any changes you like and send me the diffs for inclusion in the next patch, but
69it's a good idea to ask first in case someone already has the feature you want
70in the works. In order for me to integrate your changes, they need to be
71reasonably "clean", and you'll need to update manual page as appropriate.
72
73Please try to remember to include the c2man version number in any bug reports.
74You can find it by running: c2man -V /dev/null
75
76If you'd like to be notified automatically about new releases and patches,
77answer yes to the Configure question about sending mail to the author.
78
79
80Special thanks for their direct and indirect contributions to c2man go to:
81 Larry Wall, Raphael Manfredi, Harlan Stenn and the "dist" team, for writing
82 various bits of metaconfig, which generated the Configure script.
83
84 Darrel Hankerson for the OS/2 and MSDOS ports.
85 Rick Flower for the VMS port.
86 Stefan Ruppert for the Amiga port, and AutoDoc backend.
87 Bill Mitchell and Manoj Srivastava for maintaining the Debian version.
88 Bernd Luevelsmeyer for the Windows port, and the Raw ASCII text backend.
89
90 Richard Kooijman for the LaTeX backend, for fixing the TeXinfo backend and
91 for keeping the original c2man ftp site up to date.
92
93 Diab Jerius too, for more work on the TeXinfo backend.
94 Frank P.J. Ooms for the HTML backend.
95
96 Vern Paxson for his suggestions on how to handle comment lexing better.
97
98
99Thanks to the following people for suggestions & bug fixes is long overdue:
100 Peter (P.) Barszczewski, Carlo Tarantola, Dennis Allison,
101 Philip Yzarn de Louraille, Jerry Lieberthal, Mats Ohrman, Stefan Zimmermann,
102 Dolf Grunbauer, Lele Gaifax, Carl R. Crawford, Jhon Honce, Chris Borchert,
103 Jerry E. Dunmire, Marty Leisner, Dan Forrest, Ken Weinert, Ken Poppleton,
104 Michael Hamilton, Thomas E. Dickey, Marco Nijdam, Peter Seiderer.
105
106Finally, c2man owes a huge debt to the public domain program cproto, by
107Chin Huang, from which the original code was derived.
108
109(Hmmm. This is beginning to sound like an Academy Awards night...)
110
111
112See the file "INSTALL" for Unix installation instructions.
113OS/2 and MSDOS users should see the file "README.pc" in the "pc" directory.
114Windows users should see the file "README.win32" in the "win32" directory.
115VMS users should see the file "README.1st" in the "vms" directory.
116Amiga users should see the file "README" in the "amiga" directory.
117
118
119Graham Stoney greyham@research.canon.com.au
120Mailing List for general c2man Questions & Answers c2man@research.canon.com.au
121