<< # Scandoc template file. # This is an example set of templates that is designed to create several different # kinds of index files. It generates a "master index" which intended for use with # a frames browser; A "package index" which is the root page of the index, and then # "package files" containing documentation for all of the classes within a single # package. # ======================================================================= # For quick and superficial customization, simply change these variables # ======================================================================= $doc_dir = "ArpDoc"; $root_dir = "../"; # relative to $doc_dir. $image_directory = "images/"; # relative to $doc_dir. $company_name = "Angry Red Planet"; $short_company_name = "ARP"; $project_name = 'ArpCommon'; $company_logo = $image_directory . "arp_pic.jpeg"; # change this to an image tag. $copyright = '© 1999 Angry Red Planet'; $index_background = $image_directory . "slate.jpg"; $page_background = $image_directory . "greytile.jpg"; $bullet1_image = $image_directory . "ball1.gif"; $bullet2_image = $image_directory . "ball2.gif"; # ======================================================================= # For each package, generate all documentation. # ======================================================================= if( ! -e "$doc_dir" ) { mkdir($doc_dir, 0777); } if( ! -d $doc_dir ) { die "Location $doc_dir is not a directory." } foreach $p (packages()) { my $package_dir = $doc_dir . "/" . $p->name(); if( ! -e $package_dir ) { mkdir($package_dir, 0777); } if( ! -d $package_dir ) { die "Location $package_dir is not a directory." } write_index($p, "$package_dir/", "../"); write_todo($p, "$package_dir/", "../"); write_globals($p, "$package_dir/", "../"); # Generate explanatory chapters. foreach $c ($p->chapters()) { write_chapter($p, $c, "$package_dir/", "../"); } # Generate detailed class documentation foreach $c ($p->classes()) { write_class($p, $c, "$package_dir/", "../"); } } # ========================================= # Generate index for package. sub write_index { my $p = $_[0]; my $dir = $_[1]; my $doc = $_[2]; file $dir . "index.html"; &writeHeader("$project_name: " . $p->name() . " Package", $p->name(), $doc . $company_logo); if ($p->chapters() || $p->globals()) { >>

Chapters

<< # Write out summary of chapters in package. foreach $e ($p->chapters()) { >>

$(e.sequence). $(e.name)

<< #print &processDescription( $e->shortdescription(), $doc ); } if ($p->globals()) { >>

Global Functions and Variables

<< } } if ($p->classes()) { >>

Classes

<< # Write out summary of classes in package. foreach $e ($p->classes()) { >>

$(e.name)  (header file)

<< print &processDescription( $e->shortdescription(), $doc ); } } # Write out pointer to to-do and footer of package. if (&todolist_files()) { >>

To-Do List

<< } &writeFooter(); } # ========================================= # Generate "To-do list" for package. sub write_todo { my $p = $_[0]; my $dir = $_[1]; my $doc = $_[2]; if (&todolist_files()) { file $dir . "to-do.html"; &writeHeader("$project_name: " . $p->name() . " To-Do", $p->name(), $doc . $company_logo); >>

To-do list for $(p->name())

<< foreach $f (&todolist_files()) { my @m = &todolist_entries( $f ); if ($f =~ /([^\/]+)$/) { $f = $1; } >>

$f:

<< } >>
<< &writeFooter(); } } # ========================================= # Generate chapter of package. sub write_chapter { my $p = $_[0]; my $c = $_[1]; my $dir = $_[2]; my $doc = $_[3]; file $dir . $c->sequence() . "." . $c->name() . ".html"; &writeHeader("$project_name: " . $p->name() . $c->name(), $p->name(), $doc . $company_logo); >>

$(c.name)

<< print $c->text(); &writeFooter(); } # ========================================= # Generate file of global methods and variables for package. sub write_globals { my $p = $_[0]; my $dir = $_[1]; my $doc = $_[2]; if ( ! $p->globals() ) { return; } file $dir . "XX-Globals.html"; &writeHeader("$project_name: " . $p->name() . " Globals", $p->name(), $doc . $company_logo); >>

Globals in $(p.name)

<< my $m; # Collect member functions together, grouping by "seealso" # references. my %funcMap; foreach $m ($p->globals()) { my @list = (); my $name = $m->name(); my $seealso = ""; my $desc = $m->description(); $desc =~ s/\s*//; if( $desc eq "" && $m->seealso() ) { my @s = $m->seealso; $seealso = member_ref(@s[0]->name()); if( $seealso ne "" ) { $name = $seealso; } } #print "

Adding member: $name, ref=$seealso

\n"; if( exists $funcMap{$name} ) { @list = @{ $funcMap{$name} }; } push @list, $m; #print "

Current member is: $m

\n"; #print "

New list is: @list

\n"; @{ $funcMap{$name} } = @list; #my @funcs = sort keys %funcMap; #print "

funcs: @funcs

\n"; } my @funcs = sort keys %funcMap; my $name = ""; foreach $m ($p->globals()) { $name = $m->name(); my $typename = $name; if ($m->type() eq 'func') { $typename .= '()'; } if (exists $funcMap{$name}) { >>

$typename

<< &funclist( @{ $funcMap{$name} } ); } elsif( $m->seealso() ) { my @s = $m->seealso; $seealso = member_ref(@s[0]->name()); if( $seealso ne "" ) { >>

$typename see $seealso()

<< } } } &writeFooter(); } # ========================================= # Generate description for class. sub write_class { my $p = $_[0]; my $c = $_[1]; my $dir = $_[2]; my $doc = $_[3]; file $dir . $c->name() . ".html"; &writeHeader("$project_name: " . $c->name() . " Class", "", ""); >>
Table Of Contents Master Index

$(c.name)

<< # Output base class list print "

Derived from: "; if ($c->baseclasses()) { my @t = (); foreach $b ($c->baseclasses()) { my $name = $b->name(); push @t, $name; } print join( ', ', @t ); } else { print "none."; } print "\n

\n"; # Output subclasses list print "

Inherited by: "; if ($c->baseclasses()) { my @t = (); foreach $s ($c->subclasses()) { my $name = $s->name(); push @t, $name; } print join( ', ', @t ); } else { print "none."; } print "\n

\n"; >>

Declared in: $(c.sourcefile)

Package: $(p.name)

Summary
<< print &processDescription( $c->description(), $doc ); my $m; # Collect member functions together, grouping by "seealso" # references. my %funcMap; foreach $m ($c->memberfuncs()) { my @list = (); my $name = $m->name(); my $seealso = ""; my $desc = $m->description(); $desc =~ s/\s*//; if( $desc eq "" && $m->seealso() ) { my @s = $m->seealso; $seealso = member_ref(@s[0]->name()); if( $seealso ne "" ) { $name = $seealso; } } #print "

Adding member: $name, ref=$seealso

\n"; if( exists $funcMap{$name} ) { @list = @{ $funcMap{$name} }; } push @list, $m; #print "

Current member is: $m

\n"; #print "

New list is: @list

\n"; @{ $funcMap{$name} } = @list; my @funcs = sort keys %funcMap; #print "

funcs: @funcs

\n"; } my @funcs = sort keys %funcMap; my $first = 1; my $name = ""; #print "

funcs: @funcs

\n"; # Output class constructor method(s) foreach $name (@funcs) { #print "

Doing function: $name

\n"; if( $name eq $c->name() ) { if( $first != 0 ) { print "

Constructor

"; $first = 0; } >>

$name()

<< &funclist( @{ $funcMap{$name} } ); } } $first = 1; foreach $m ($c->memberfuncs()) { $name = $m->name(); if ($name ne $c->name()) { if( $first != 0 ) { print "

Member Functions

"; $first = 0; } if (exists $funcMap{$name}) { >>

$name()

<< &funclist( @{ $funcMap{$name} } ); } elsif( $m->seealso() ) { my @s = $m->seealso; $seealso = member_ref(@s[0]->name()); if( $seealso ne "" ) { >>

$name() see $seealso()

<< } } } } $first = 1; # Output class member variables foreach $m ($c->membervars()) { if( $first != 0 ) { print "

Data Members

"; $first = 0; } else { print "
\n"; } &variable( $m, $doc ); } } # ========================================= # Generate summary for class. sub write_summary { my $p = $_[0]; my $c = $_[1]; my $dir = $_[2]; my $doc = $_[3]; file $dir . $p->name() . ".summary.html"; >> $project_name: $(c.name) Class << foreach $c ($p->classes()) { >>

$(c.fullname)

<< } } sub member_ref { my $ref = $_[0]; #print "

Getting member_ref for: $ref

\n"; if( $ref =~ /^[a-zA-Z_].*\(\)/ ) { $ref =~ tr/()//d; return $ref; } return ""; } # Subroutine to generate documentation for a member function or global function sub funclist { my @flist = @_; my $f; my %funcnames = { }; >>
<< foreach $f (@flist) { print " << $funcnames{$f->name()} = 1; } >>
\n"; if ($f->keywords()) { >> << } >>$(f.fullname)
<< my $first = 1; foreach $f (@flist) { if ($f->params() || $f->returnval() || $f->exceptions()) { if( $first ) { print "
\n"; $first = 0; } } if ($f->params()) { >>
Parameters
<< foreach $a ($f->params()) { >> << } >>

$(a.name)<< print &processDescription( $a->description(), $doc ); >>

<< } if ($f->returnval()) { >>
Return Value
<< print &processDescription( $f->returnval(), $doc );>>
<< } if ($f->exceptions()) { >>
Exceptions
<< foreach $a ($f->exceptions()) { >> << } >>

$(a.name)<< print &processDescription( $a->description(), $doc ); >>

<< } } if (! $first) { print "
\n"; } foreach $f (@flist) { print &processDescription( $f->description(), $doc ); } my @r = (); foreach $f (@flist) { my $a; foreach $a ($f->seealso()) { my $name = $a->name(); my $ref = member_ref($name); if( $ref ne "" ) { if (! exists $funcnames{$ref}) { push @r, "$ref()"; @funcnames{$ref} = 1; } } else { push @r, "$name"; } } } if( @r ) { print "

See also:\n"; print join( ',', @r ); print "

\n"; } } # Subroutine to generate documentation for a member variable or global variable. sub variable { my $v = $_[0]; my $doc = $_[1]; if ($v->keywords()) { print ""; } >> $(v.fullname)
<description(), $doc );>> << if ($v->seealso()) { >>

See also: << $comma = 0; foreach $a ($v->seealso()) { if ($comma) { print ","; } $comma = 1; >>$(a.name) << } >>

<< } } sub writeHeader { my $title = $_[0]; my $project = $_[1]; my $logo = $_[2]; >> $title << if( $project ne "" ) { >>

$company_name

$project








<< } } sub writeFooter { >>

Copyright

All files and code contained in this package are Copyright ©1998 Angry Red Planet, except where otherwise noted. The files contained here-in are distributed under a modifed form of the Artistic License. See the file \@License.html or \@License.txt for a copy of this license.

Generated by ScanDoc

Last Updated: $date

<< } sub processDescription { my $docdir = $_[1]; local ($_) = $_[0] . " "; #print "

Raw Description:

\n

$_

\n"; s:^\s+::; # Remove whitespace from beginning s:\n\s*\n:\n

\n:g; # Replace multiple CR's with paragraph markers s:\@heading\s(.*)\n:

$1

:g; # Handle heading text s:\@begindl\s:\n

\n:g; # Handle definition lists s:\@term\s(.*)\n:\n
$1
\n:g; s:\@definition\s:
:g; s:\@enddl:\n

\n:g; # Handle definition lists s:\@formatted\s:\n

\n:g;		# Handle pre-formatted text.
	s:\@unformatted\s:\n

\n:g; # Handle pre-formatted text. s:

[ \t]*\n:
:g;				# Strip empty newline off 
.
	s:\s*
:\n
:g; # Strip space before
. # Put multiple CRs back into formatted text. while( s:(
[^\t]*)

([^\t]*

):$1$2:g ) { } # Handle embedded image tags s:\@caution\s:\n

\n:g; s:\@warning\s:\n

\n:g; s:\@bug\s:\n

\n:g; s:\@tip\s:\n

\n:g; s:\s+$:\n:; # Remove whitespace from end if ($_ ne "") { $_ = "

\n" . $_ . "\n

\n"; } #print STDERR "Before

strip:\n$_\n"; s:

\s*

::g; # Remove any empty paragraphs. #print STDERR "After

strip:\n$_\n"; return $_; }