The long option parser for subcommands (lopsub).
[lopsub.git] / gendoc / gendoc.m4
1 changequote(`«', `»')dnl
2 define(«IFNBLANK», «ifelse(translit(««$1»», «
3 »), «», «», «$2»)»)dnl
4 define(«DECL_ARGLIST», «ifelse(«$#», «2», «$1»,
5 «$1, DECL_ARGLIST(shift(shift($@)))»)»)dnl
6 define(«LINK_COUNT», 0)
7 define(«STRIP_LEFT», «patsubst(«$1», «^\s+», «»)»)dnl
8 define(«STRIP_RIGHT», «patsubst(«$1», «\s+$», «»)»)dnl
9 define(«STRIP», «STRIP_LEFT(«STRIP_RIGHT(«$1»)»)»)dnl
10 ifelse(OUTPUT_MODE, «C», «dnl --------- C output
11 define(«COMPOUND_MEMBERS», «ifelse(«$#», «1», «»,
12 « $1; /* STRIP_RIGHT(«$2») */
13 COMPOUND_MEMBERS(shift(shift($@)))»)»)dnl
14 define(«DECL_ARG_TEXT», «ifelse(«$#», «1», «», «IFNBLANK(«$2», «
15 $1: $2«»DECL_ARG_TEXT(shift(shift($@)))»)»)»)dnl
16 define(«DECLARE_FUNCTION», «/* $2 */
17 $6 $1(DECL_ARGLIST($4));
18 /*dnl
19 $3«»dnl
20 DECL_ARG_TEXT($4)dnl
21 IFNBLANK(«$5», «$5»)dnl
22 IFNBLANK(«$7», «
23 Return ($6): STRIP_RIGHT(«$7»)»
24 )dnl
25 IFNBLANK(«$8», «$8»)dnl
26 */»)dnl
27 define(«STATEMENT», «/* $2 */
28 $1;
29 IFNBLANK(«$3», «/*STRIP_RIGHT(«$3»)
30 */dnl
31 »)dnl
32 »)dnl
33 define(«DECLARE_COMPOUND», «/* $2 */
34 $1 {
35 IFNBLANK(«$3», «/*STRIP_RIGHT(«$3»)
36 */
37 »)dnl
38 COMPOUND_MEMBERS($4)dnl
39 };
40 IFNBLANK(«$5», «/*STRIP_RIGHT(«$5»)
41 */
42 »)dnl
43 »)dnl
44 define(«VERBATIM_C», «$1»)dnl
45 », OUTPUT_MODE, «HTML», «dnl --------- HTML output
46 define(«FIXUP_LT», «patsubst(«$1», «<», «&lt;»)»)
47 define(«FIXUP_GT», «patsubst(«$1», «>», «&gt;»)»)
48 define(«FIXUP_AMPERSAND», «patsubst(«$1», «&», «&amp;»)»)
49 define(«HANDLE_EMPTY_LINES», «patsubst(«$1», «^\s*$», «</p><p>»)»)
50 define(«FIXUP_HTML», «<p> FIXUP_AMPERSAND(«FIXUP_LT(«FIXUP_GT(
51 «HANDLE_EMPTY_LINES(«$1»)»)»)») </p>»)
52 define(«FORMAT_LIST_HTML», «ifelse(«$#», «1», «», «
53 IFNBLANK(«$2», «<li> <tt>$1</tt>: $2 </li>
54 FORMAT_LIST_HTML(shift(shift($@)))»)»
55 )»)
56 define(«ANCHOR», «
57 <a name = "link_«»LINK_COUNT" </a>
58 »)
59 define(«HREF», «
60 define(«LINK_COUNT», incr(LINK_COUNT))
61 <a href = "«#»link_«»LINK_COUNT"> $1 </a>
62 »)
63 define(«DECLARE_FUNCTION», «
64 divert
65 <tr> <td> <tt> HREF(«$1») </tt> </td> <td> $2 </td> </tr>
66 divert(«1»)
67 ANCHOR
68 <h1> <tt> $6 $1(DECL_ARGLIST($4)) </tt> </h1>
69 <strong> FIXUP_HTML(«$2») </strong>
70 FIXUP_HTML(«$3»)
71 <ul> FORMAT_LIST_HTML($4) </ul>
72 FIXUP_HTML(«$5»)
73 IFNBLANK(«$7», «Return (<tt>$6</tt>):
74 <ul><li> FIXUP_HTML(«$7») </lu></ul>»)
75 FIXUP_HTML(«$8»)
76 <hr>
77 »)
78 define(«STATEMENT», «
79 divert
80 <tr> <td> <tt> HREF(«$1») </tt> </td> <td> $2 </td>
81 divert(«1»)
82 ANCHOR
83 <h1> <tt> $1 </tt> </h1>
84 <strong> FIXUP_HTML(«$2») </strong>
85 <p> FIXUP_HTML(«$3») </p>
86 <hr>
87 »)
88 define(«DECLARE_COMPOUND», «
89 divert
90 <tr> <td> <tt> HREF(«$1») </tt> </td> <td> $2 </td>
91 divert(«1»)
92 ANCHOR
93 <h1> <tt> $1 </tt> </h1>
94 <strong> FIXUP_HTML(«$2») </strong>
95 FIXUP_HTML(«$3»)
96 Members:
97 <ul> FORMAT_LIST_HTML($4) </ul>
98 FIXUP_HTML(«$5»)
99 <hr>
100 »)
101 define(«VERBATIM_C»)
102 divert(«1») </table> <hr> divert
103 <center> <h1> API Reference </h1> </center>
104 <table>
105 », OUTPUT_MODE, «ROFF»,«dnl ---------- ROFF output
106 .TH
107 .SH SYNOPSIS
108 define(«VERBATIM_C»)
109 define(«FORMAT_LIST_ROFF», «ifelse(«$#», «1», «», «
110 IFNBLANK(«$2», «
111 .B "STRIP(«$1»)"
112 \- STRIP(«$2»)
113 .br dnl
114 FORMAT_LIST_ROFF(shift(shift($@)))»dnl
115 »))»)
116 define(«STATEMENT», «dnl
117 divert
118 .B "$1"
119 \- «$2»
120 .br dnl
121 divert(«1»)
122 .SS "«$1»"
123 STRIP_LEFT(«$2»)
124 STRIP_LEFT(«$3»)dnl
125 »)
126 define(«DECLARE_FUNCTION», «
127 divert
128 .BR "«$1»" ()
129 \- «$2»
130 .br dnl
131 divert(«1»)
132 .SS "STRIP_RIGHT(«$6») $1(DECL_ARGLIST($4))"
133 STRIP(«$2»)
134 STRIP(«$3»)
135 .IP
136 FORMAT_LIST_ROFF($4)
137 .P
138 STRIP(«$5»)dnl
139 IFNBLANK(«$7», «
140 .IP
141 Return
142 .RB ( "$6" ):
143 STRIP(«$7»)»
144 .P
145 )
146 STRIP_LEFT(«$8»)
147 .P
148 »)
149 divert(«1»)
150 .P
151 .SH DESCRIPTION
152 divert
153 »)dnl
154 ifdef(«EXAMPLES», «
155 dnl
156 dnl
157 dnl Args
158 dnl ~~~~
159 dnl (1) name, (2) one-line summary, (3) prolog, (4) args,
160 dnl (5) arg doc, (6) return type, (7) one-line return text, (8) epilog
161 DECLARE_FUNCTION(
162 «main»,
163 «The function that is executed on startup.»,
164 «
165 1. This function must not be static, it's always linked in.
166
167 Each executable needs to define exactly one main function.
168 », «
169 «int argc», «usual argument count»,
170 «char **argv», «usual argument vector»
171 », «
172 2. The arg list may optionally contain an env pointer. In any case
173 argc > 0 and argc < INT_MAX.
174 »,
175 «int», «EXIT_SUCCESS or EXIT_FAILURE»,
176 «
177 3. On most systems EXIT_FAILURE is 1 and EXIT_SUCCESS is 0.
178 »)
179
180 DECLARE_FUNCTION(
181 «sync»,
182 «Commit buffer cache to disk.»,
183 «
184 Causes all buffered modifications to file metadata and data
185 to be written to the underlying filesystems.
186 », «
187 «void»,
188 », «
189 »,
190 «void»,
191 )
192
193 DECLARE_FUNCTION(
194 «getchar»,
195 «Input of characters and strings.»,
196 «
197 Reads the next character from stdin.
198 », «
199 «void»,
200 », «
201 »,
202 «int», «the character read»,
203 «
204 On success the return value is an unsigned char cast to
205 an int. On end of file or error, EOF is returned.
206 »
207 )
208
209 DECLARE_FUNCTION(
210 «free»,
211 «Free dynamic memory.»,
212 «
213 The memory space must have been returned by a previous call to
214 malloc(), calloc(), or realloc().
215 », «
216 «void *ptr», «free the memory space pointed to by ptr»
217 », «
218 If ptr is NULL, no operation is performed.
219 »,
220 «void»,
221 )
222
223 dnl Args
224 dnl ~~~~
225 dnl (1) name, (2) one-line summary, (3) prolog, (4) member list, (5) epilog
226 DECLARE_COMPOUND(
227 «struct complex»,
228 «Describes a complex number»,
229 «
230 », «
231 «float re», «real part»,
232 «float im», «imaginary part»,
233 »
234 )
235 DECLARE_COMPOUND(
236 «struct iovec»,
237 «According to POSIX, the <sys/uio.h> header shall define the iovec structure.»,
238 «
239 This structure is employed for the readv() and writev() system calls.
240
241 For example, the readv() system call reads into buffers which is
242 described by an array of iovec structures.
243 », «
244 «void *iov_base», «start address»,
245 «size_t iov_len», «number of bytes to transfer»
246 », «
247 Buffers are processed in array order.
248 »
249 )
250 dnl Args
251 dnl ~~~~
252 dnl (1) name, (2) one-line summary, (3) description
253 STATEMENT(
254 «struct foo_handle»,
255 «Opaque structure that describes one connection to the foo subsystem»,
256 «
257 The compiler considers this structure an incomplete type.
258
259 Applications can still declare pointer variables or arrays of pointers
260 to this structure, and compare pointers for equality. However, they
261 will not be able to de-reference a pointer, and can only change the
262 pointer's content by calling some procedure of the library.
263 »
264 )
265 »)