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
|
<!-- $Id$ -->
<HTML>
<HEAD>
<TITLE>ACE Documentation Tools</TITLE>
<BODY text = "#000000"
link="#000fff"
vlink="#ff0f0f"
bgcolor="#ffffff">
<HR>
<H3>ACE Documentation Tools</H3>
This <A HREF="http://www.cs.wustl.edu/~schmidt/ACE-bin/">directory</A>
contains versions of the freely available <A
HREF="http://www.dscpl.com.au/">OSE</A> tools used to generate the ACE
<A
HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/man/man3/">man</A>
and <A
HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/man/acewindex.html">HTML</A>
documentation. These tools were originally written by <A
HREF="mailto:grahamd@nms.otc.com.au"> Graham Dumpleton</A> and later
modified by <A HREF="mailto:kdorn@erlh.siemens.de">Karlheinz Dorn</A>.
<A HREF="http://www.cs.wustl.edu/~schmidt/ACE-members.html">We</A> are
very grateful to Graham and Karlheinz for these tools. You can obtain
the ACE documentation-generation tools in the <A
HREF="http://www.cs.wustl.edu/~schmidt/ACE-obtain.html">ACE</A>
release. <P>
<H3>Modified Version of the OSE Documentation Tools</H3>
The primary goal of Karlheinz's modifications was to create a
<EM>class</EM>.hxx and <EM>class</EM>.cxx file (for each class,
struct, union included within the original ACE header file) from the
ACE *.h header files by collecting the comments from that file and
feeding them into the newly created files, but keeping the ACE *.h
file untouched. <P>
This helps when making product documentation using commercial
documentation tools (e.g., <A HREF="http://www.k2.co.uk">George</A>,
<A
HREF="http://www.zib.de/Visual/software/doc++/index.html">doc++</a>,
etc.) by feeding in these newly created files with a customizable
layout. The modifications are an upgrade to the original OSE-tools,
but many bug-fixes are also done for the OSE-tool files (some are
listed below). <P>
Incidentally, the classinfo tools in OSE have evolved independently
since the copies in ACE were made and they support new features not
supported in the ACE version of the tools. Certain subtle changes
were also made in the ACE copies for indicating sections,
<em>etc.</em>, which makes them different from the OSE documentation.
For more information please contact <A
HREF="mailto:grahamd@nms.otc.com.au">Graham Dumpleton</A>, who heads
the <A HREF="http://www.dscpl.com.au/">OSE</A> project. <P>
Karlheinz's extensions make it easy to include new ACE versions into
commercial documentations without doing any painful modifications of
the deltas within a frozen ACE-version or directly within ACE source
files when a new release arises. <P>
The following changes were made to the original OSE tools:
<UL>
<LI> The vendor headers can be suppressed within the hiding.fmt file,
so it is possible to generate <EM>class</EM>.cxx and
<EM>class</EM>.hxx files consisting only of pure class description
(hxx) and pure prototypes (cxx). Look at the vendor.fmt file and
change the field <EM>vendor</EM> in replacing it with your company
identifying line. <P>
<LI> Added a new script class2hxxcxx for making a <EM>class</EM>.hxx file for each
class, struct, union included in an ACE *.h file as well as a *.cxx
file that includes the correct prototypes for all classes within that
*.h file. <P>
<LI> Added new script info2headsrc for creating a <EM>class</EM>.hxx file for each
class, struct, union included in an ACE *.h file as well as a <EM>class</EM>.cxx
file that includes the correct prototypes for that class. <P>
<LI> added a new script class2hxxcxxsingle for the feature listed above. <P>
<LI> added a new format file named "hiding.fmt" to control more fine grained output
of a class in separating/suppressing PUBLIC, PROTECTED, PRIVATE parts of a
class, struct, union for output explicitly. <P>
<LI> added a new format file named "vendor.fmt" to control vendor specific
compilation-unit headers as well as class and method headers for the newly
created <EM>class</EM>.hxx and <EM>class</EM>.cxx files. The information for these headers
is collected from the headers and comments of the according ACE *.h files. <P>
<LI> changed info2doc and info2src for the features listed above. <P>
<LI> added the ability for handling multiline ENUMs properly (class2info,info2doc). <P>
<LI> added the ability for handling operator functions properly (info2src). <P>
<LI> added the ability for handling template functions properly (info2src). <P>
<LI> added the ability for handling nested classes, structs, unions properly
by introducing gawk-function recursion within info2doc (class2info,
info2doc, info2src). <P>
<LI> added the ability for handling default values properly (info2src). <P>
</UL>
<HR><P>
<H3>Known Bugs</H3>
Some bugs inherited from the original OSE-tools are remaining. So the
developer of the *.h files should the following keep in mind:
- do not write multiline inheritance! <P>
INCORRECT: <P>
<pre><code>
class x :
public y
{
}
</pre></code>
CORRECT: <P>
<pre><code>
class x : public y
{
}
</pre></code>
- do not write multiline templates!<P>
INCORRECT: <P>
<pre><code>
template <class t,
class>
class x
{
}
</pre></code>
CORRECT: <P>
<pre><code>
template <class t, class u>
class x
{
}
</pre></code>
<P>
<HR><P>
Other documentation tools are available at the following URLs: <P>
<UL>
<A HREF="http://www.dscpl.com.au/">OSE documentation tools</A>
<LI> <A HREF="http://www.zib.de/Vishal/software/doc++/index.html">doc++</a>
<LI> <A HREF="http://www.k2.co.uk">George</A>
</UL>
<P><HR><P>
Back to the <A HREF="http://www.cs.wustl.edu/~schmidt/ACE.html">ACE</A> home page.
</BODY>
</HTML>
|
