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        = '&copy 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