1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
|
Frequently Asked Questions about c2man
--------------------------------------
By Graham Stoney (greyham@research.canon.com.au)
Last-modified: $Date: 2004-05-03 05:17:49 $
Q. Where can I get an up-to-date already patched copy of c2man?
A. You can usually get the latest version via ftp:
ftp /pub/Unix/Util/c2man-2.0.*.tar.gz from dnpap.et.tudelft.nl
Many thanks to Richard Kooijman <R.Kooijman@et.tudelft.nl> for providing
the ftp site, and keeping it up to date. The very latest version probably
won't be available until a short time after each patch is issued, since
we're relying on Richard's kindness to apply the patches and keep the tar
file up to date manually.
You can also retrieve the latest version via the author's mail server, by
mailing to greyham@research.canon.com.au with a message like:
Subject: Command
@PACK shar
@SH maildist - c2man 2.0
In reply, you can expect on the order of 9 or so mail messages, each around
55 K long. You'll also have the extra hassle of unpacking it. Detailed
instructions on using the mail server can be obtained by mailing to the
same with address a message like:
Subject: Command
@SH mailhelp -
It should also be available in your local comp.sources.misc archive. The
versions in the alt.sources and comp.sources.reviewed archives are
obsolete. One day soon I'll be able to put it up for ftp here directly.
Q. How do I remove myself from the c2man discussion list?
A. You should have received instructions on how to do this when you joined the
list. It's always wise to save a copy of the instructions you receive when
you join a mailing list, so that you can refer to them in future when you
wish to leave.
To remove yourself from the c2man discussion list, send E-mail to:
listserv@research.canon.com.au
With the message:
Subject:
unsubscribe c2man
You should also be able to unsubscribe be running Configure again, and
asking it to unsubscribe you when it asks if you wish to subscribe to, or
unsubscribe from the mailing list.
Note that the discussion list and the automatic patch notification/update
list are completely independant.
Q. How do I remove myself from the c2man automatic patch notification/update
list?
A. If you don't wish to receive future notification or mailing of new patches,
you need to send a message to the author's personal mail server. In other
words, you send E-mail to:
greyham@research.canon.com.au
With the message:
Subject: Command
@SH package - c2man
You can also achieve the same effect by running Configure and asking that
future patches not be sent to you. You may also alter your notification
vs update preference via Configure.
Q. Can c2man handle C++? Is anyone working on a version that can?
A. No, it can't handle C++, although there are other tools that do a similar
job for C++. A few people have expressed interest, but I don't know of
anyone who is actively working on it. If you look in the file C++autodoc in
the distribution, you'll get all the gory details. This file is always kept
up-to-date with the current state of play.
Q. How do I apply the official patches to c2man?
A. You need the patch program, by Larry Wall. Chances are that it's already
installed on your system; if not, you could ask your system administrator
about getting it, or search for it using archie if you know how. Once
you've got it, follow the instructions in each of the patch headers. For
example, patch 10 says:
Fix: From rn, say "| patch -p -N -d DIR", where DIR is your c2man source
directory. Outside of rn, say "cd DIR; patch -p -N <thisarticle".
If you don't have the patch program, apply the following by hand,
or get patch (version 2.0, latest patchlevel).
In other words, 'cd' to your c2man directory and type:
patch -p -N < patch10
That should feed the patch into the patch program, which will apply it. You
also need to take care to follow the "After Patching" instructions in each
patch, and repeat this procedure for each patch. In general, you can apply
all the patches without having to re-run Configure after every patch set,
although you must run Configure after patch30, because it renames a few
files. You can apply patches 10 through 30 without having to run Configure
though. The "After patching" instructions assume that you apply patches as
they are issued; you don't generally have to do them multiple times if
you're applying a whole group of patch sets.
Q. Can c2man document structure fields automatically, like it does for enums?
A. In short, No.
This is a very logical extension; so much so in fact that I'd say it's
absence in the current version is a real deficiency. I'm not sure if you
always want the structure contents listed in the manual page for the
functions that use the type though, since some interfaces use "opaque"
types, where the structure contents is deliberately hidden from the user;
eg: the stdio FILE type. My thoughts were to generate a separate manual
page for each struct or type definition, with perhaps an option to include
the info in all the functional manual pages using that type, as now happens
with enum types now.
Adding struct support to the current grammar should be fairly easy; mainly
by copying what it does with enum's; and it would certainly be very
worthwhile. I'd encourage anyone who'd like to see greater functionality in
c2man to feel free to add it in, and send me the diffs.
Sorry, this doesn't work at present. It's probably the most serious
omission from the program; lots of people have asked about this. At
present, I don't know when it's likely to be fixed. I might suddenly get
really keen one day and do it -- otherwise, someone else will have to
implement it and send me the diffs. It shouldn't be too hard, but it's a
matter of making it a priority and getting around to actually doing it...
Q. Why do my functions using ``FILE *'' get documented with this weird
``struct _iobuf'' type?
A. Unfortunately, many systems use a #define for ``FILE'' in stdio.h to rename
it to ``struct _iobuf'', rather than using a typedef. Since c2man sees the
output of the pre-processor, ``FILE'' is long gone before it reads the
code, and so the documentation that it generates is misleading.
Some stdio.h's perform this #define conditionally, so it may be possible to
pass certain -D flags to c2man which will cause stdio.h to use a typedef
instead, although this will be very system-dependant.
I don't know of a really good solution to this problem, but I'd be
interested to hear if anyone has one.
Q. How can I get c2man recognise and document #defines?
A. c2man doesn't recognise #defines at all, but you can rewrite it as an enum.
You do need to be able to change the type passed to an enum though, to get
c2man to recognise that it's what's being passed. C is very loose with its
enums, so it's still just as flexible as the #define case, and the types
look more self-documenting in the code too:
enum Bits
{
BIT0 = 1, /* The first bit */
BIT1 = 2, /* The next bit */
BIT2 = 4 /* The last bit */
};
/* set the bits! */
void set_bits( enum Bits bits );
Gives you:
set_bits(3) UNIX Programmer's Manual set_bits(3)
NAME
set_bits - set the bits!
SYNOPSIS
#include <set_bits.h>
void set_bits(enum Bits bits);
PARAMETERS
enum Bits bits
Possible values for an enum Bits are as follows:
BIT0 The first bit.
BIT1 The next bit.
BIT2 The last bit.
DESCRIPTION
Set the bits!.
Q. But what if my function returns an errno-like code which can take many
values, but I'd like the documentation to list only those that the function
in question can actually generate?
A. c2man makes a crude attempt at identifying token/value lists in the RETURNS
section from the comment describing the function. If the first thing on a
line in the RETURNS section is a single token followed a ':' or TAB
character, c2man interprets it as a token list and attempts to format it
accordingly. Have a look at the file "eg/reterrno.h" for an exmple.
|
