1<< 2# Scandoc template file. 3# 4# This is an example set of templates that is designed to create several 5# different kinds of index files. It generates a "master index" which intended 6# for use with a frames browser; A "package index" which is the root page of 7# the index, and then "package files" containing documentation for all of the 8# classes within a single package. 9 10###################################################################### 11 12## For quick and superficial customization, 13## simply change these variables 14 15$project_name = '[Apache]'; 16$company_logo = '<img src="../images/ScanDocBig.jpg">'; # change this to an image tag. 17$copyright = '© 2000 [Apache Software Foundation]'; 18$image_directory = "../images/"; 19$bullet1_image = $image_directory . "ball1.gif"; 20$bullet2_image = $image_directory . "ball2.gif"; 21$bgcolor1 = "#FFFFFF"; 22$bgcolor2 = "#FFFFFF"; 23 24###################################################################### 25 26## Begin generating frame index file. 27 28file "index.html"; 29>><html> 30 <head> 31 <meta http-equiv="Content-Type" content="text/html; iso-8859-1"> 32 <title>$project_name</title> 33 </head> 34 <frameset cols="190,*"> 35 <frame src="master.html" name="Master Index" noresize> 36 <frame src="packages.html" name="Documentation"> 37 <noframes> 38 <body bgcolor="$bgcolor2" stylesrc="index.html"> 39 <p>Some Documentation</p> 40 </body> 41 </noframes> 42 </frameset> 43</html> 44<< 45 46###################################################################### 47 48## Begin generating master index file (left-hand frame). 49 50file "master.html"; 51>><html> 52 <head> 53 <title>Master Index</title> 54 </head> 55 <body bgcolor="$bgcolor1" text=#0000ff link=#0020ff vlink=#0020ff> 56 <center><img src="${image_directory}ScanDocSmall.jpg" border="0" /></center> 57 <p> 58 <a href="packages.html" target="Documentation">Master Index</a> 59 </p> 60 <p> 61 <font size="2"> 62 <nobr> 63<< 64 65## For each package, generate an index entry. 66 67foreach $p (packages()) { 68 $_ = $p->url; 69 s/\s/%20/g; 70 >><a href="$_" target="Documentation"><b>$(p.name)</b></a><br> 71 <dir> 72 << 73 foreach $e ($p->classes()) { 74 $_ = $e->url; 75 s/\s/%20/g; 76 >><li><a href="$_" target="Documentation">$(e.fullname)</a> 77 << 78 } 79 foreach $e ($p->globals()) { 80 $_ = $e->url; 81 s/\s/%20/g; 82 >><li><a href="$_" target="Documentation">$(e.fullname)</a> 83 << 84 } 85 >></dir><< 86} 87 88>> 89 <a href="to-do.html" target="Documentation"><b>To-Do List</b></a><br> 90 </nobr> 91 </font> 92 </p> 93 </body> 94</html> 95<< 96 97###################################################################### 98 99## Begin generating package index file 100 101file "packages.html"; 102>><html> 103 <head> 104 <title>$project_name -- Packages</title> 105 </head> 106 <body bgcolor="$bgcolor2"> 107 108 <center>$company_logo 109 <h1>Documentation for $project_name</h1> 110 </center> 111 <h2>Package List</h2> 112<< 113 114## For each package, generate an index entry. 115 116foreach $p (packages()) { 117 $_ = $p->url; 118 s/\s/%20/g; 119 >><a href = "$_">$(p.name)</a><br> 120 << 121} 122 123>> 124 <p> 125 <hr size=4> 126 $copyright<br> 127 Generated by <a href="$scandocURL"><b>ScanDoc $majorVersion.$minorVersion</b></a><br> 128 Last Updated: $date<br> 129 </body> 130</html> 131 132<< 133 134###################################################################### 135 136## Generate "To-do list" 137 138file "to-do.html"; 139>><html> 140 <head> 141 <title>$project_name -- To-Do list</title> 142 </head> 143 <body bgcolor="$bgcolor2"> 144 145 $company_logo 146 147 <h1>To-do list for $project_name</h1> 148<< 149 150if (&todolistFiles()) { 151 >><hr size=4><p> 152 << 153 foreach $f (&todolistFiles()) { 154 my @m = &todolistEntries( $f ); 155 if ($f =~ /([^\/]+)$/) { $f = $1; } 156 >><b>$f:</b><ul> 157 << 158 foreach $text (@m) { 159 if ($text) { 160 print "<li>", &processDescription( $text ), "\n"; 161 } 162 } 163 >></ul> 164 << 165 } 166} 167 168>> 169 <hr size=4> 170 $copyright<br> 171 Generated by <a href="$scandocURL"><b>ScanDoc $majorVersion.$minorVersion</b></a><br> 172 Last Updated: $date<br> 173 </body> 174</html> 175<< 176 177###################################################################### 178 179## Generate individual files for each package. 180 181my $p; 182foreach $p (packages()) { 183 file $p->name() . ".html"; 184 >><html> 185 <head> 186 <title>$project_name -- $(p.name)</title> 187 </head> 188 <body bgcolor="$bgcolor2"> 189 <center> 190 <font size=6><b>$project_name</b></font> 191 <hr size=4><p> 192 </center> 193 194 <h2>Package Name: $(p.name)</h2> 195 <b> 196<< 197 198## Generate class and member index at the top of the file. 199 200foreach $c ($p->classes()) { 201 >><h3><img src="$bullet1_image" width=18 height=17 align=texttop> 202 <a href="$(c.url)">$(c.fullname)</h3></a> 203 <ul> 204 << 205 foreach $m ($c->members()) { 206 >><li><a href="$(m.url)">$(m.longname)</a> 207 << 208 } 209 >></ul> 210 << 211} 212 213>> 214</b> 215<< 216 217## Generate detailed class documentation 218foreach $c ($p->classes()) { 219 ## Output searchable keyword list 220 if ($c->keywords()) { 221 print "<!-- ", $c->keywords(), " -->\n"; 222 } 223 224 >><hr size="4"> 225 <a name="$(c.anchor)"></a> 226 <h1>$(c.fullname)</h1> 227 <table bgcolor="ffffff" border="0" cellspacing="4"> 228 <tr> 229 <th align=center colspan=2> 230 </th> 231 </tr> 232 << 233 234 # Output author tag 235 if ($c->author()) { 236 >><tr><th width=20% align=right>Author:</th><< 237 >><td>$(c.author)</td></tr><< 238 } 239 240 # Output package version 241 if ($c->version()) { 242 >><tr><th width=20% align=right>Version:</th><< 243 >><td>$(c.version)</td></tr><< 244 } 245 246 # Output Source file 247 if ($c->sourcefile()) { 248 >><tr><th width=20% align=right>Source:</th><< 249 >><td>$(c.sourcefile)</td></tr><< 250 } 251 252 # Output base class list 253 if ($c->baseclasses()) { 254 >><tr><th width=20% align=right>Base classes:</th> 255 <td><< 256 my @t = (); 257 foreach $b ($c->baseclasses()) { 258 my $name = $b->name(); 259 if ($url = $b->url()) { 260 push @t, "<a href=\"$url\">$name</a>"; 261 } 262 else { push @t, $name; } 263 } 264 print join( ', ', @t ); 265 >></td></tr> 266 << 267 } 268 269 # Output subclasses list 270 if ($c->subclasses()) { 271 >><tr><th width=20% align=right>Subclasses:</th> 272 <td><< 273 my @t = (); 274 foreach $s ($c->subclasses()) { 275 my $name = $s->name(); 276 if ($url = $s->url()) { 277 push @t, "<a href=\"$url\">$name</a>"; 278 } 279 else { push @t, $name; } 280 } 281 print join( ', ', @t ); 282 >></td></tr><< 283 } 284 285 # Output main class description 286 >></tr> 287 </table> 288 <p> 289 << 290 print &processDescription( $c->description() ); 291 292 # Output "see also" information 293 if ($c->seealso()) { 294 >><p><dt><b>See Also</b><dd> 295 << 296 my @r = (); 297 foreach $a ($c->seealso()) { 298 my $name = $a->name(); 299 if ($url = $a->url()) { 300 push @r, "<a href=\"$url\">$name</a>"; 301 } 302 else { push @r, $name; } 303 } 304 print join( ',', @r ); 305 >><p> 306 << 307 } 308 309 # Output class member index 310 if ($c->members()) { 311 print "<h2>Member Index</h2>\n"; 312 print "<ul>"; 313 foreach $m ($c->members()) { 314 >><li><a href="$(m.url)">$(m.fullname)</a> 315 << 316 } 317 >></ul><< 318 } 319 320 # Output class member variable documentation 321 if ($c->membervars()) { 322 print "<h2>Class Variables</h2>\n"; 323 print "<blockquote>\n"; 324 foreach $m ($c->membervars()) { &variable( $m ); } 325 print "</blockquote>\n"; 326 } 327 328 # Output class member function documentation 329 if ($c->memberfuncs()) { 330 print "<h2>Class Methods</h2>\n"; 331 print "<blockquote>\n"; 332 foreach $m ($c->memberfuncs()) { &function( $m ); } 333 print "</blockquote>\n"; 334 } 335} 336 337# Output global variables 338if ($p->globalvars()) { 339 >><h2>Global Variables</h2> 340 <blockquote> 341 << 342 foreach $m ($p->globalvars()) { &variable( $m ); } 343 print "</blockquote>\n"; 344} 345 346# Output global functions 347if ($p->globalfuncs()) { 348 >><h2>Global Functions</h2> 349 <blockquote> 350 << 351 foreach $m ($p->globalfuncs()) { &function( $m ); } 352 print "</blockquote>\n"; 353} 354 355>> 356 <hr size=4> 357 $copyright<br> 358 Generated by <a href="$scandocURL"><b>ScanDoc $majorVersion.$minorVersion</b></a><br> 359 Last Updated: $date<br> 360 </body> 361</html> 362<< 363} # end of foreach (packages) loop 364 365###################################################################### 366 367## Subroutine to generate documentation for a member function or global function 368 369sub function { 370 local ($f) = @_; 371 372 if ($f->keywords()) { 373 >><!-- $(f.keywords) --> 374 << 375 } 376 >> 377 <a name="$(f.anchor)"></a> 378 <dl> 379 <dt> 380 <b><img src="$bullet2_image" width=19 height=17 align=texttop>$(f.fullname);</b> 381 <dd> 382 << 383 print &processDescription( $f->description() ); 384 >> 385 <p><dl> 386 << 387 if ($f->params()) { 388 >> 389 <dt><b>Parameters</b><dd> 390 <table width="85%"> 391 << 392 foreach $a ($f->params()) { 393 >><tr valign=top><th align=right> 394 $(a.name)</th><td><< 395 print &processDescription( $a->description() ); 396 >></td></tr> 397 << 398 } 399 >></table> 400 << 401 } 402 403 if ($f->returnValue()) { 404 >><dt><b>Return Value</b> 405 <dd><< 406 print &processDescription( $f->returnValue() ); 407 >><p><< 408 } 409 410 if ($f->exceptions()) { 411 >><dt><b>Exceptions</b><dd> 412 <table width=85%><tr><td colspan=2><hr size=3></td></tr> 413 << 414 foreach $a ($f->exceptions()) { 415 >><tr valign=top><th align=right> 416 $(a.name)</th><td><< 417 print &processDescription( $a->description() ); 418 >></td></tr> 419 << 420 } 421 >><tr><td colspan=2><hr size=3></td></tr></table> 422 << 423 } 424 425 if ($f->seealso()) { 426 >><dt><b>See Also</b><dd> 427 << 428 my @r = (); 429 foreach $a ($f->seealso()) { 430 my $name = $a->name(); 431 if ($url = $a->url()) { 432 push @r, "<a href=\"$url\">$name</a>"; 433 } 434 else { push @r, $name; } 435 } 436 print join( ',', @r ); 437 >><p><< 438 } 439 >></dl></dl> 440 << 441} 442 443###################################################################### 444 445## Subroutine to generate documentation for a member variable or global variable. 446 447sub variable { 448 local ($v) = @_; 449 450 if ($v->keywords()) { 451 print "<!-- $(v.keywords) -->"; 452 } 453 454 >> 455 <a name="$(v.name)"></a> 456 <dl><dt> 457 <b><img src="$bullet2_image" width=19 height=17 align=texttop>$(v.fullname);</b> 458 <dd> 459 <<print &processDescription( $v->description() );>> 460 <p><dl> 461 << 462 if ($v->seealso()) { 463 >><dt><b>See Also</b><dd> 464 << 465 $comma = 0; 466 foreach $a ($v->seealso()) { 467 if ($comma) { print ","; } 468 $comma = 1; 469 >><a href="$(a.url)">$(a.name)</a> 470 << 471 } 472 >><p> 473 << 474 } 475 >></dl></dl> 476 << 477} 478 479###################################################################### 480 481sub processDescription { 482 local ($_) = @_; 483 484 s/^\s+//; # Remove whitespace from beginning 485 s/\s+$/\n/; # Remove whitespace from end 486 s/\n\n/<p>\n/g; # Replace multiple CR's with paragraph markers 487 s:\@heading(.*)\n:<p><h2>$1</h2>:; # Handle heading text 488 489 # Handle embedded image tags 490 s:\@caution:<p><img src=\"${image_directory}/caution.gif\" align=left>:; 491 s:\@warning:<p><img src=\"${image_directory}/warning.gif\" align=left>:; 492 s:\@bug:<p><img src=\"${image_directory}/bug.gif\">:; 493 s:\@tip:<p><img src=\"${image_directory}/tip.gif\">:; 494 495 return $_; 496} 497