apr-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From r..@locus.apache.org
Subject cvs commit: apr-util/build default.pl
Date Wed, 06 Dec 2000 05:02:14 GMT
rbb         00/12/05 21:02:14

  Modified:    .        Makefile.in
  Added:       build    default.pl
  Log:
  Add a make target to build the apr-util API documentation.  This uses
  the scandoc script from APR, so that we don't duplicate that section of
  code.
  
  Revision  Changes    Path
  1.5       +5 -0      apr-util/Makefile.in
  
  Index: Makefile.in
  ===================================================================
  RCS file: /home/cvs/apr-util/Makefile.in,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- Makefile.in	2000/12/06 02:19:45	1.4
  +++ Makefile.in	2000/12/06 05:02:13	1.5
  @@ -36,4 +36,9 @@
   aprutil.exports:
   	perl @APR_SOURCE_DIR@/helpers/make_export.pl -o $@ include/*.h
   
  +docs:
  +	mkdir ./docs
  +	perl @APR_SOURCE_DIR@/helpers/scandoc -i./build/default.pl -p./docs/ ./include/*.h
  +
  +
   .PHONY: delete-lib
  
  
  
  1.1                  apr-util/build/default.pl
  
  Index: default.pl
  ===================================================================
  <<
  # 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
  
  $project_name     = '[Apache Portable RunTime Utility Library]';
  #$company_logo     = '<img src="../images/ScanDocBig.jpg">'; # change this to an image
tag.
  $copyright        = '&copy 2000 [Apache Software Foundation]';
  $image_directory  = "../images/";
  $bullet1_image    = $image_directory . "ball1.gif";
  $bullet2_image    = $image_directory . "ball2.gif";
  $bgcolor1         = "#FFFFFF";
  $bgcolor2         = "#FFFFFF";
  
  ######################################################################
  
  ## Begin generating frame index file.
  
  file "index.html";
  >><html>
    <head>
      <meta http-equiv="Content-Type" content="text/html; iso-8859-1">
      <title>$project_name</title>
    </head>
    <frameset cols="190,*">
      <frame src="master.html"  name="Master Index" noresize>
      <frame src="packages.html" name="Documentation">
      <noframes>
        <body bgcolor="$bgcolor2" stylesrc="index.html">
          <p>Some Documentation</p>
        </body>
      </noframes>
    </frameset>
  </html>
  <<
  
  ######################################################################
  
  ## Begin generating master index file (left-hand frame).
  
  file "master.html";
  >><html>
    <head>
      <title>Master Index</title>
    </head>
    <body bgcolor="$bgcolor1" text=#0000ff link=#0020ff vlink=#0020ff>
      <center><img src="${image_directory}ScanDocSmall.jpg" border="0" /></center>
      <p>
      <a href="packages.html" target="Documentation">Master Index</a>
      </p>
      <p>
        <font size="2">
          <nobr>
  <<
  
  ## For each package, generate an index entry.
  
  foreach $p (packages()) {
    $_ = $p->url;
    s/\s/_/g;
    >><a href="$_" target="Documentation"><b>$(p.name)</b></a><br>
      <dir>
    <<
    foreach $e ($p->classes()) {
      $_ = $e->url;
      s/\s/_/g;
      >><li><a href="$_" target="Documentation">$(e.fullname)</a>
      <<
    }
    foreach $e ($p->globals()) {
      $_ = $e->url;
      s/\s/_/g;
      >><li><a href="$_" target="Documentation">$(e.fullname)</a>
      <<
    }
    >></dir><<
  }
  
  >>
            <a href="to-do.html" target="Documentation"><b>To-Do List</b></a><br>
          </nobr>
        </font>
      </p>
    </body>
  </html>
  <<
  
  ######################################################################
  
  ## Begin generating package index file
  
  file "packages.html";
  >><html>
    <head>
      <title>$project_name -- Packages</title>
    </head>
    <body bgcolor="$bgcolor2">
  
      <center>$company_logo
      <h1>Documentation for $project_name</h1>
      </center>
      <h2>Package List</h2>
  <<
  
  ## For each package, generate an index entry.
  
  foreach $p (packages()) {
    $_ = $p->url;
    s/\s/_/g;
    >><a href = "$_">$(p.name)</a><br>
    <<
  }
  
  >>
      <p>
      <hr size=4>
      $copyright<br>
      Generated by <a href="$scandocURL"><b>ScanDoc $majorVersion.$minorVersion</b></a><br>
      Last Updated: $date<br>
    </body>
  </html>
  
  <<
  
  ######################################################################
  
  ## Generate "To-do list"
  
  file "to-do.html";
  >><html>
    <head>
      <title>$project_name -- To-Do list</title>
    </head>
    <body bgcolor="$bgcolor2">
  
      $company_logo
  
      <h1>To-do list for $project_name</h1>
  <<
  
  if (&todolistFiles()) {
    >><hr size=4><p>
    <<
    foreach $f (&todolistFiles()) {
      my @m = &todolistEntries( $f );
      if ($f =~ /([^\/]+)$/) { $f = $1; }
      >><b>$f:</b><ul>
      <<
      foreach $text (@m) {
        if ($text) {
          print "<li>", &processDescription( $text ), "\n";
        }
      }
      >></ul>
      <<
    }
  }
  
  >>
      <hr size=4>
      $copyright<br>
      Generated by <a href="$scandocURL"><b>ScanDoc $majorVersion.$minorVersion</b></a><br>
      Last Updated: $date<br>
    </body>
  </html>
  <<
  
  ######################################################################
  
  ## Generate individual files for each package.
  
  my $p;
  foreach $p (packages()) {
    $_ = $p->name;
    s/\s/_/g;
    file $_ . ".html";
    >><html>
    <head>
      <title>$project_name -- $(p.name)</title>
    </head>
    <body bgcolor="$bgcolor2">
      <center>
        <font size=6><b>$project_name</b></font>
        <hr size=4><p>
      </center>
  
      <h2>Package Name: $(p.name)</h2>
      <b>
  <<
  
  ## Generate class and member index at the top of the file.
  
  foreach $c ($p->classes()) {
    $_ = $c->url;
    s/\s/_/g;
    >><h3><img src="$bullet1_image" width=18 height=17 align=texttop>
      <a href="$_">$(c.fullname)</h3></a>
      <ul>
    <<
    foreach $m ($c->members()) {
      $_ = $m->url;
      s/\s/_/g;
      >><li><a href="$_">$(m.longname)</a>
      <<
    }
    >></ul>
    <<
  }
  
  >>
  </b>
  <<
  
  ## Generate detailed class documentation
  foreach $c ($p->classes()) {
   ## Output searchable keyword list
   if ($c->keywords()) {
     print "<!-- ", $c->keywords(), " -->\n";
   }
  
   >><hr size="4">
     <a name="$(c.anchor)"></a>
     <h1>$(c.fullname)</h1>
     <table bgcolor="ffffff" border="0" cellspacing="4">
       <tr>
         <th align=center colspan=2>
         </th>
       </tr>
    <<
    
    # Output author tag
    if ($c->author()) {
      >><tr><th width=20% align=right>Author:</th><<
      >><td>$(c.author)</td></tr><<
    }
  
    # Output package version
    if ($c->version()) {
      >><tr><th width=20% align=right>Version:</th><<
      >><td>$(c.version)</td></tr><<
    }
  
    # Output Source file
    if ($c->sourcefile()) {
      >><tr><th width=20% align=right>Source:</th><<
      >><td>$(c.sourcefile)</td></tr><<
    }
  
    # Output base class list
    if ($c->baseclasses()) {
      >><tr><th width=20% align=right>Base classes:</th>
      <td><<
      my @t = ();
      foreach $b ($c->baseclasses()) {
        my $name = $b->name();
        if ($url = $b->url()) {
          $_ = $url;
          s/\s/_/g;
          push @t, "<a href=\"$_\">$name</a>";
        }
        else { push @t, $name; }
      }
      print join( ', ', @t );
      >></td></tr>
      <<
    }	
  
    # Output subclasses list
    if ($c->subclasses()) {
      >><tr><th width=20% align=right>Subclasses:</th>
        <td><<
      my @t = ();
      foreach $s ($c->subclasses()) {
        my $name = $s->name();
        if ($url = $s->url()) {
          $_ = $url;
          s/\s/_/g;
          push @t, "<a href=\"$_\">$name</a>";
        }
        else { push @t, $name; }
      }
      print join( ', ', @t );
      >></td></tr><<
    }
  
    # Output main class description
    >></tr>
    </table>
    <p>
    <<
    print &processDescription( $c->description() );
  	
    # Output "see also" information
    if ($c->seealso()) {
      >><p><dt><b>See Also</b><dd>
      <<
      my @r = ();
      foreach $a ($c->seealso()) {
        my $name = $a->name();
        if ($url = $a->url()) {
          $_ = $url;
          s/\s/_/g;
          push @r, "<a href=\"$_\">$name</a>";
        }
        else { push @r, $name; }
      }
      print join( ',', @r );
      >><p>
      <<
    }
  
    # Output class member index
    if ($c->members()) {
      print "<h2>Member Index</h2>\n";
      print "<ul>";
      foreach $m ($c->members()) {
        $_ = $m->url;
        s/\s/_/g;
        >><li><a href="$_">$(m.fullname)</a>
  	<<
      }
      >></ul><<
    }
   
    # Output class member variable documentation
    if ($c->membervars()) {
      print "<h2>Class Variables</h2>\n";
      print "<blockquote>\n";
      foreach $m ($c->membervars()) { &variable( $m ); }
      print "</blockquote>\n";
    }
  
    # Output class member function documentation
    if ($c->memberfuncs()) {
      print "<h2>Class Methods</h2>\n";
      print "<blockquote>\n";
      foreach $m ($c->memberfuncs()) { &function( $m ); }
      print "</blockquote>\n";
    }
  }
  
  # Output global variables
  if ($p->globalvars()) {
    >><h2>Global Variables</h2>
      <blockquote>
    <<
    foreach $m ($p->globalvars()) { &variable( $m ); }
    print "</blockquote>\n";
  }
  
  # Output global functions
  if ($p->globalfuncs()) {
    >><h2>Global Functions</h2>
      <blockquote>
    <<
    foreach $m ($p->globalfuncs()) { &function( $m ); }
    print "</blockquote>\n";
  }
  
  >>
      <hr size=4>
      $copyright<br>
      Generated by <a href="$scandocURL"><b>ScanDoc $majorVersion.$minorVersion</b></a><br>
      Last Updated: $date<br>
    </body>
  </html>
  <<
  } # end of foreach (packages) loop
  
  ######################################################################
  
  ## Subroutine to generate documentation for a member function or global function
  
  sub function {
    local ($f) = @_;
    
    if ($f->keywords()) {
      >><!-- $(f.keywords) -->
        <<
    }
    >>
    <a name="$(f.anchor)"></a>
    <dl>
      <dt>
       <b><img src="$bullet2_image" width=19 height=17 align=texttop>$(f.fullname);</b>
      <dd>
    <<
    print &processDescription( $f->description() );
    >>
    <p><dl>
    <<
    if ($f->params()) {
      >>
        <dt><b>Parameters</b><dd>
  	<table width="85%">
      <<
      foreach $a ($f->params()) {
        >><tr valign=top><th align=right>
  	$(a.name)</th><td><<
        print &processDescription( $a->description() );
        >></td></tr>
        <<
      }
      >></table>
        <<
    }
  	
    if ($f->returnValue()) {
      >><dt><b>Return Value</b>
        <dd><<
      print &processDescription( $f->returnValue() );
      >><p><<
    }
    
    if ($f->exceptions()) {
      >><dt><b>Exceptions</b><dd>
        <table width=85%><tr><td colspan=2><hr size=3></td></tr>
      <<
      foreach $a ($f->exceptions()) {
        >><tr valign=top><th align=right>
  	$(a.name)</th><td><<
  	  print &processDescription( $a->description() );
        >></td></tr>
        <<
      }
      >><tr><td colspan=2><hr size=3></td></tr></table>
      <<
    }
  	
    if ($f->seealso()) {
      >><dt><b>See Also</b><dd>
        <<
      my @r = ();
      foreach $a ($f->seealso()) {
        my $name = $a->name();
        if ($url = $a->url()) {
          $_ = $url;
          s/\s/_/g;
  	push @r, "<a href=\"$_\">$name</a>";
        }
        else { push @r, $name; }
      }
      print join( ',', @r );
      >><p><<
    }
    >></dl></dl>
    <<
  }
  
  ######################################################################
  
  ## Subroutine to generate documentation for a member variable or global variable.
  
  sub variable {
    local ($v) = @_;
    
    if ($v->keywords()) {
      print "<!-- $(v.keywords) -->";
    }
  
    >>
      <a name="$(v.name)"></a>
        <dl><dt>
  	<b><img src="$bullet2_image" width=19 height=17 align=texttop>$(v.fullname);</b>
    <dd>
    <<print &processDescription( $v->description() );>>
    <p><dl>
    <<
    if ($v->seealso()) {
      >><dt><b>See Also</b><dd>
        <<
  	$comma = 0;
      foreach $a ($v->seealso()) {
        $_ = $a->url;
        s/\s/_/g;
        if ($comma) { print ","; }
        $comma = 1;
        >><a href="$_">$(a.name)</a>
  	<<
      }
      >><p>
      <<
    }
    >></dl></dl>
    <<
  }
  
  ######################################################################
  
  sub processDescription {
    local ($_) = @_;
    
    s/^\s+//;				# Remove whitespace from beginning
    s/\s+$/\n/;				# Remove whitespace from end
    s/\n\n/<p>\n/g;			# Replace multiple CR's with paragraph markers
    s:\@heading(.*)\n:<p><h2>$1</h2>:;	# Handle heading text
    
    # Handle embedded image tags
    s:\@caution:<p><img src=\"${image_directory}/caution.gif\" align=left>:;
    s:\@warning:<p><img src=\"${image_directory}/warning.gif\" align=left>:;
    s:\@bug:<p><img src=\"${image_directory}/bug.gif\">:;
    s:\@tip:<p><img src=\"${image_directory}/tip.gif\">:;
  
    return $_;
  }
  
  
  

Mime
View raw message