Re: Header documentation script

Frode wrote:

> Hi!

Aloha!

> I have a question about the appealing documentation reference in  
> libwww. Is it the header comments that generates the HTML  
> documentation? And is there any script that can redo this available?

Actually the header files are generated from the HTML documentation, as 
described in the step,

  http://www.w3.org/Library/cvs.html#Easy

This a full filled example of what has been called 'literate 
programming'   . . .

    "The main idea is to treat a program as a piece of literature,
    addressed to human beings rather than to a computer. The program is
    also viewed as a hypertext document, rather like the World Wide Web." 
    -- Knuth [1]

> I'm asking because I thought about using the library's nice and  
> gentle comment style in other projects, instead of the doxygen style.  

It is interesting the effect of text which is conciously intended for 
another human being.

> I've tried to look for it in the CVS repository but can't find any  
> obviously evidence of any such script. I have the feeling that for  
> some years ago I read about this somewhere and somehow, but can't  
> find it now.

The winConfigure.pl script does several things; one of which is the 
header file transformation,

  sub htmlToH
  {
      my $output = shift;
      my $input = $output;
 
      local (*OPEN, *CLOSE, *NL) = (\0, \1, \2);
      my %transition = (
                '_TEXT' => ['','',''],
                'html'  => ['','',''],
                'title'  => ['                    ','',''],
                'pre'  => ['    ','','    '],
                'h1'  => ['!','!',''],
                'h2'  => ['.','.',''],
                'h3'  => ['(',')',''],
                'ul'  => ['     ','','     '],
                'li'  => ['o ','','     '],
                );
      if ($output =~ m/\.h$/) {
      $transition{'html'} = ["/*","*/",""];
      $transition{'pre'} = ["*/\n","\n/*",""];
      }
 
      $input =~ s/\.[^\.\/]*$//;
      $input .= '.html';
      (open(INPUT, "< $input")) || (warn "can't open input file 
\"$input\": $!", return);
      (open(OUTPUT, "> $output")) || (warn "can't open output file 
\"$output\": $!", return);
      my $contents = join('', <INPUT>);
      my $inTag = 0;
      my $tag = '';
      my $elem;
      foreach $elem (split('[<>]', $contents)) {
      if ($inTag) {
  #      print OUTPUT ${$transition{$tag}}[$CLOSE] if (defined 
$transition{$tag});
          ($close, $tag, $space, $rest) = $elem =~ m/(\/?)(\S+)(\s*)(.*)/si;
          $tag =~ tr/A-Z/a-z/;
          if ($close eq '/') {
          print OUTPUT $ {$transition{$tag}}[$CLOSE] if (defined 
$transition{$tag});
          } else {
          print OUTPUT $ {$transition{$tag}}[$OPEN] if (defined 
$transition{$tag});
          }
      } else {
          (defined $transition{$tag}) && ($elem =~ s/\n/"\n".$ 
{$transition{$tag}}[$NL]/ge);
          $elem =~ s/\&lt;/</g;
          $elem =~ s/\&gt;/>/g;
          $elem =~ s/\&amp;/&/g;
          print OUTPUT $elem;
      }
      $inTag ^= 1;
      }
  }

more,
l8r,
v

[1] http://www-cs-faculty.stanford.edu/~knuth/lp.html

-- 
"The future is here. It's just not evenly distributed yet."
 -- William Gibson, quoted by Whitfield Diffie

Received on Thursday, 18 January 2007 05:17:18 UTC