tools/docpercentages.pl

   1 #!/usr/bin/perl -w
   2
   3 #############################################################################
   4 # Function    : CreateValidSGMLID
   5 # Description : Creates a valid SGML 'id' from the given string.
   6 #               NOTE: SGML ids are case-insensitive, so we have a few special
   7 #                     cases to avoid clashes of ids.
   8 # Arguments   : $id - the string to be converted into a valid SGML id.
   9 #############################################################################
  10
  11 sub CreateValidSGMLID {
  12     my ($id) = $_[0];
  13
  14     # Append -CAPS to all all-caps identifiers
  15
  16     # Special case, '_' would end up as '' so we use 'gettext-macro' instead.
  17     if ($id eq "_") { return "gettext-macro"; }
  18
  19     if ($id !~ /[a-z]/) { $id .= "-CAPS" };
  20
  21     $id =~ s/[_ ]/-/g;
  22     $id =~ s/[,\.]//g;
  23     $id =~ s/^-*//;
  24     $id =~ s/::/-/g;
  25
  26     return $id;
  27 }
  28
  29 $BASEDIR=shift @ARGV;
  30
  31 print <<EOT;
  32 <table cellspacing="0" cellpadding="2">
  33   <tr><th align="left">Module</th><th style="padding-left: 0.5em; padding-right: 0.5em" colspan="4">Documented</th></tr>
  34 EOT
  35
  36 my $row = 0;
  37 while (@ARGV) {
  38     my $percentage;
  39     my $documented;
  40     my $undocumented;
  41     my @undocumented_symbols;
  42
  43     my $module_name = shift @ARGV;
  44     my $file = shift @ARGV;
  45     my $indexfile = shift @ARGV;
  46
  47     open DOCUMENTED, "<$file" or die "Cannot open $file: $!\n";
  48
  49     while (<DOCUMENTED>) {
  50         if      (/(\d+)% (function|symbol) docs coverage/) {
  51             $percentage = $1;
  52         } elsif (/(\d+) (function|symbol)s documented/) {
  53             $documented = $1;
  54         } elsif (/(\d+) not documented/) {
  55             $undocumented = $1;
  56         } elsif (/^\s*(\w+)\s*$/) {
  57             push @undocumented_symbols, $1;
  58         }
  59     }
  60
  61     close DOCUMENTED;
  62
  63     my $complete = defined $percentage && defined $documented && defined $undocumented;
  64     if (!$complete) {
  65         die "Cannot parse documentation status file $file\n";
  66     }
  67
  68     my $total = $documented + $undocumented;
  69
  70     my $directory;
  71     ($directory = $indexfile) =~ s@/[^/]*$@@;
  72
  73     $bgcolor = ($row % 2 == 0) ? "#f7ebd3" : "#fffcf4";
  74
  75     print <<EOT;
  76   <tr bgcolor="$bgcolor">
  77     <td><a href="$indexfile">$module_name</a></td>
  78     <td align="right" style="padding-left: 0.5em">$documented</td>
  79         <td>/</td><td>$total</td>
  80     <td style="padding-right: 0.5em">($percentage%)</td>
  81 EOT
  82     if ($undocumented != 0) {
  83         print <<EOT;
  84     <td><a href="$directory/undocumented.html"><small>[missing]<small></a></td>
  85 EOT
  86     }
  87     print <<EOT;
  88   </tr>
  89 EOT
  90
  91     #
  92     # Print an index of undocumented symbols for this module
  93     #
  94
  95     @undocumented_symbols = sort { uc($a) cmp uc($b) } @undocumented_symbols;
  96
  97     my $base = "$BASEDIR/$directory";
  98
  99     open INDEX_SGML, "<$base/index.sgml" or die "Cannot open $base/index.sgml: $!\n";
 100
 101     my %index_symbols;
 102
 103     while (<INDEX_SGML>) {
 104         if (/<ANCHOR\s+id="([^"]+)"\s+href="([^"]+)">/) {
 105             $index_symbols{$1} = $2;
 106         }
 107     }
 108
 109     close INDEX_SGML;
 110
 111     open UNDOC_OUT, ">$base/undocumented.html" or die "Cannot open $base/undocumented.html: $!\n";
 112     print UNDOC_OUT <<EOT;
 113 <html>
 114 <head>
 115 <title>Undocumented functions in $module_name</title>
 116 </head>
 117 <body bgcolor="#ffffff">
 118 <table>
 119   <tr>
 120 EOT
 121     my $i = 0;
 122     for $symbol (@undocumented_symbols) {
 123         my $id = CreateValidSGMLID($symbol);
 124
 125         my $output;
 126         if (exists $index_symbols{$id}) {
 127             my $href;
 128
 129             ($href = $index_symbols{$id}) =~ s@.*/(.*)$@$1@;
 130
 131             $output = qq(<a href="$href">$symbol</a>);
 132         } else {
 133             $output = qq($symbol);
 134         }
 135         print UNDOC_OUT "    <td>$output</td>\n";
 136         if ($i % 3 == 2) {
 137             print UNDOC_OUT "  </tr><tr>\n";
 138         }
 139
 140         $i++;
 141     }
 142
 143     print UNDOC_OUT <<EOT;
 144   </tr>
 145 </table>
 146 </body>
 147 </html>
 148 EOT
 149     close UNDOC_OUT;
 150     $row++;
 151 }
 152
 153 print <<EOT;
 154 </table>
 155 EOT