web: Don't duplicate the html header.
[osl.git] / gendoc.m4
1 changequote(`«', `»')dnl
2 define(«IFNBLANK», «ifelse(translit(««$1»», «
3 »), «», «», «$2»)»)dnl
4 define(«DECL_ARGLIST», «ifelse(«$#», «2», ««$1»», «dnl
5 «$1», DECL_ARGLIST(shift(shift($@)))»)»)dnl
6 ifelse(OUTPUT_MODE, «C», «dnl --------- C output
7 define(«STRIP_TABS», «translit(««$1»», « »)»)dnl
8 define(«CHOP_FIRST», «translit(patsubst(translit(««««$1»»»», «
9 », « »), «^.... \(.*\)....$», «««\1»»»), « », «
10 »)»)dnl
11 define(«CHOP_LAST»,
12 «format(««%.*s»», regexp(translit(««$1»», «
13 /», «/ »), «/*$»), «$1»)»)dnl
14 define(«NORMALIZE», «CHOP_LAST(CHOP_FIRST(STRIP_TABS(«$1»)))»)dnl
15 define(«COMMENT», «patsubst(patsubst(«««$1»»», «^\(.\)», « \1»), «^», «$2»)»)dnl
16 define(«INDENT», «COMMENT(NORMALIZE(«$1»), « *»)»)dnl
17 define(«INDENT_PARAM», «COMMENT(NORMALIZE(«$1»), « * »)»)dnl
18 define(«INDENT_PARAM_DOC», «COMMENT(NORMALIZE(«$1»), « * »)»)dnl
19 define(«INDENT_RETVAL_DOC», «COMMENT(NORMALIZE(«$1»), « * »)»)dnl
20 define(«INDENT_MEMBER_DOC», «COMMENT(NORMALIZE(«$1»), « *»)»)dnl
21 define(«INDENT_MEMBER», «patsubst(NORMALIZE(««$1»»), «^[ ]*», « »)»)dnl
22 define(«DECL_ARG_TEXT», «ifelse(«$#», «1», «», «
23 INDENT_PARAM(«$1»):
24 INDENT_PARAM_DOC(«$2»)«»dnl
25 DECL_ARG_TEXT(shift(shift($@)))»)»)dnl
26 define(«PRINT_ARGS», «ifelse(«$2», «», «», «dnl
27 *
28 * Parameter(s):DECL_ARG_TEXT($@)»
29 )»)dnl
30 define(«DECLARE_FUNCTION», «dnl
31 /*
32 * «$1»(): «$2»
33 IFNBLANK(«$3», «dnl
34 *
35 INDENT(«$3»)
36 »)dnl
37 PRINT_ARGS($4)dnl
38 IFNBLANK(«$5», «dnl
39 *
40 INDENT(«$5»)
41 »)dnl
42 IFNBLANK(«$7», «dnl
43 *
44 * Return («$6»):
45 INDENT_RETVAL_DOC(«$7»)
46 »)dnl
47 IFNBLANK(«$8», «dnl
48 *
49 INDENT(«$8»)
50 »)dnl
51 */
52 «$6» «$1»(DECL_ARGLIST($4));dnl
53 »)dnl
54 define(«STATEMENT», «dnl
55 /*
56 INDENT(«$2»)
57 IFNBLANK(«$3», «dnl
58 *
59 INDENT(«$3»)
60 »)dnl
61 */
62 «$1»;»)dnl
63 define(«COMPOUND_MEMBERS», «ifelse(«$#», «1», «»,
64 « /*
65 INDENT_MEMBER_DOC(«$2»)
66 */
67 INDENT_MEMBER(«$1»);
68 COMPOUND_MEMBERS(shift(shift($@)))»)»)dnl
69 define(«DECLARE_COMPOUND», «dnl
70 /*
71 * «$2»
72 IFNBLANK(«$3», «dnl
73 *
74 INDENT(«$3»)
75 »)dnl
76 */
77 «$1» {
78 COMPOUND_MEMBERS($4)dnl
79 };dnl
80 »)dnl
81 define(«ENUM_MEMBERS», «ifelse(«$#», «1», «»,
82 « /*
83 INDENT_MEMBER_DOC(«$2»)
84 */
85 INDENT_MEMBER(«$1»),
86 ENUM_MEMBERS(shift(shift($@)))»)»)dnl
87 define(«DECLARE_ENUM», «/* «$2» */
88 IFNBLANK(«$3», «dnl
89 *
90 patsubst(«$3», «^\s*», « * »)
91 »)dnl
92 enum «$1» {
93 ENUM_MEMBERS($4)dnl
94 };dnl
95 »)dnl
96 define(«VERBATIM_C», «NORMALIZE(«$1»)»)dnl
97 », OUTPUT_MODE, «HTML», «dnl --------- HTML output
98 define(«LINK_COUNT», 0)dnl
99 define(«FIXUP_LT», «patsubst(«$1», «<», «&lt;»)»)
100 define(«FIXUP_GT», «patsubst(«$1», «>», «&gt;»)»)
101 define(«FIXUP_AMPERSAND», «patsubst(«$1», «&», «&amp;»)»)
102 define(«HANDLE_EMPTY_LINES», «patsubst(«$1», «^\s*$», «</p><p>»)»)
103 define(«FIXUP_HTML», «FIXUP_AMPERSAND(FIXUP_LT(FIXUP_GT(««««$1»»»»)))»)
104 define(«FORMAT_LIST_HTML», «ifelse(«$#», «1», «», «
105 IFNBLANK(«$2», «<li> <tt>«$1»</tt>: HANDLE_EMPTY_LINES(FIXUP_HTML(««$2»»)) </li>
106 FORMAT_LIST_HTML(shift(shift($@)))»)»
107 )»)
108 define(«ANCHOR», «
109 id="link_«»LINK_COUNT"
110 »)
111 define(«HREF», «
112 define(«LINK_COUNT», incr(LINK_COUNT))
113 <a href = "«#»link_«»LINK_COUNT"> «$1» </a>
114 »)
115 define(«DECLARE_FUNCTION», «
116 divert
117 <tr> <td> <tt> HREF(«$1()») </tt> </td> <td> «$2» </td> </tr>
118 divert(«1»)
119 <h2 ANCHOR()> <tt> «$6» «$1»(DECL_ARGLIST($4)) </tt> </h2>
120 <strong> FIXUP_HTML(«$2») </strong>
121 <p> HANDLE_EMPTY_LINES(FIXUP_HTML(««$3»»)) </p>
122 <ul> FORMAT_LIST_HTML($4) </ul>
123 <p> HANDLE_EMPTY_LINES(FIXUP_HTML(««$5»»)) </p>
124 IFNBLANK(«$7», «Return (<tt>«$6»</tt>):
125 <ul><li> FIXUP_HTML(«$7») </li></ul>»)
126 <p> HANDLE_EMPTY_LINES(FIXUP_HTML(««$8»»)) </p>
127 <hr>
128 »)
129 define(«STATEMENT», «
130 divert
131 <tr> <td> <tt> HREF(«$1») </tt> </td> <td> «$2» </td>
132 divert(«1»)
133 <h2 ANCHOR()> <tt> «$1» </tt> </h2>
134 <strong> FIXUP_HTML(«$2») </strong>
135 <p> HANDLE_EMPTY_LINES(FIXUP_HTML(««$3»»)) </p>
136 <hr>
137 »)
138 define(«DECLARE_COMPOUND», «
139 divert
140 <tr> <td> <tt> HREF(«$1») </tt> </td> <td> «$2» </td>
141 divert(«1»)
142 <h2 ANCHOR()> <tt> «$1» </tt> </h2>
143 <strong> FIXUP_HTML(«$2») </strong>
144 <p> HANDLE_EMPTY_LINES(FIXUP_HTML(««$3»»)) </p>
145 Members:
146 <ul> FORMAT_LIST_HTML($4) </ul>
147 <hr>
148 »)
149 define(«DECLARE_ENUM», «
150 divert
151 <tr> <td> <tt> HREF(«enum $1») </tt> </td> <td> «$2» </td>
152 divert(«1»)
153 <h2 ANCHOR()> <tt> enum «$1» </tt> </h2>
154 <strong> FIXUP_HTML(«$2») </strong>
155 <p> HANDLE_EMPTY_LINES(FIXUP_HTML(««$3»»)) </p>
156 Enumeration Constants:
157 <ul> FORMAT_LIST_HTML($4) </ul>
158 <hr>
159 »)
160 define(«VERBATIM_C»)
161 divert(«1») </table> <hr> </div> divert
162 <center> <h1> API Reference </h1> </center>
163 <div class="toc"> <table>
164 »)dnl
165 ifdef(«EXAMPLES», «
166 dnl $1: name, $2: one-line summary, $3: prolog, $4: parameters,
167 dnl $5: parameter documentation, $6: return type, $7: return text,
168 dnl $8: epilog
169 DECLARE_FUNCTION(
170 «simple_func»,
171 «This is the one-line summary.»,
172 «This is the prolog.»,
173 «
174 «int param1»,
175 «documentation of first parameter»,
176
177 «char *param2»,
178 «documentation of second parameter»
179 »,
180 «This is the parameter documentation section.»,
181
182 «int»,
183 «This is the documentation of the return value»,
184 «This is the epilog.»
185 )
186
187 DECLARE_FUNCTION(
188 «complex_func»,
189 «Example of a function which uses all features of gendoc»,
190 «Prolog: The three free text sections (prolog, arg-doc and epilog) may
191 all consist of several paragraphs, and each may contain multiple lines.
192 Paragraphs are separated by lines containing only whitespace.
193
194 Formatting is kept intact, but lines are wrapped into C comments.»,
195 «
196 «int par1»,
197 «The parameter list consists of any number of parameter/comment
198 pairs. The parameters are plain C code like the "int par1" above.
199
200 The list must be quoted, and both the declaration and its
201 comment must also be quoted. Comments must not be empty.»,
202
203 «int par2»,
204 «For the parameter documentation the same rules as for the free text
205 sections apply: Multiple paragraphs are possible, and each may spawn
206 multiple lines.»
207
208 »,
209 «The par-doc section. It is printed after the parameter list but before
210 the return value (if any).
211
212 It is supposed to describe the function or its parameters in more
213 detail, possibly referring to one or more of the above parameters.
214
215 This function returns non-void, so this paragraph is followed by the
216 return value documentation.»,
217
218 «int»,
219 «Like the parameter/comment pairs, the return value consists of two parts:
220 the return type and the documentation.
221
222 This return documentation consists of two paragraphs.»,
223 «Finally, there is the (optional) epilog.
224
225 It might contain references to related documentation, for example a
226 "see also" section.»
227 )
228
229 DECLARE_FUNCTION(
230 «dwim»,
231 «Example of a function with no parameters and no return value.»,
232 «This is the description. It could consist of several paragraphs.»,
233
234 «
235 «void»,
236 »,
237 «Par-doc: For functions with no parameters, the par-doc section
238 is kind of pointless.»,
239
240 «void»,
241 «»,
242 «Epilog: For functions with no return value, the epilog directly
243 follows the par-doc section.»,
244 )
245
246 DECLARE_FUNCTION(
247 «minimal_documented_function»,
248 «This documentation conists of only the summary line.»,
249 «»,
250
251 «
252 «void»,
253 »,
254 «»,
255 «void»,
256 «»,
257 «»,
258 )
259
260 dnl $1: name, $2: one-line summary, $3: description, $4: members
261 DECLARE_COMPOUND(
262 «struct foo»,
263 «summary: Illustrate the DECLARE_COMPOUND macro»,
264 «description: The macro works for both structs and unions. The
265 structure of the documentation is simpler than for functions because
266 instead of three free-text sections (prolog, par-doc, epilog), it
267 has only one: the description. Of course the description may spawn
268 multiple paragraphs, each of which which may consist of multiple lines.
269
270 The member list is similar to the list of function parameters.»,
271
272 «
273 «float member1»,
274 «The description of the members may also spawn multiple paragraphs,
275 and each of them may spawn multiple lines.
276
277 This description has two paragraphs.»,
278
279 «float member2»,
280 «The documentation might be pretty short, though»
281 »
282 )
283
284 dnl $1: name, $2: one-line summary, $3: description, $4: members
285 DECLARE_ENUM(
286 «example_enum»,
287 «Summary: Illustrate the DECLARE_ENUM macro»,
288 «Enumerations are similar to compounds in that they receive a one-line
289 summary and an optional long description, The member list (paramter
290 #4) is expected to be a list of identifier/comment pairs.»,
291
292 «
293 «ENUM_ID1»,
294 «comment 1»,
295
296 «ENUM_ID2»,
297 «Comments can span multiple lines. Formatting is retained, but
298 leading and trailing newlines are stripped and leading tabs are
299 adjusted to make the C output look nice.»
300 »
301 )
302
303 dnl $1: name, $2: one-line summary, $3 description
304 STATEMENT(
305 «extern int bar»,
306 «Summary: Illustrate the STATMENT macro»,
307 «If the header file contains simple statements, they can be documented
308 with a one-line summary and an optional multi-paragraph description.
309
310 This is the second paragrapgh of the description.»
311 )
312
313 STATEMENT(
314 «struct opaque»,
315 «Summary: A statement without a description»,
316 )
317 »)dnl