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 »)