Header documentation script

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Header documentation script

Frode-2

Hi!

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?

I'm asking because I thought about using the library's nice and  
gentle comment style in other projects, instead of the doxygen style.  
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.

Thanks for any hints,
Frode


Reply | Threaded
Open this post in threaded view
|

Re: Header documentation script

Vic Bancroft-2

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


Reply | Threaded
Open this post in threaded view
|

Re: Header documentation script

Frode-2

Hi!

18 jan 2007 kl. 06.17 skrev Vic Bancroft:

>> 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,


Aha, that was the case...  :-)

> 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.

This was something interesting and news to me. One never stops to  
learning, as they say...

Even though I'll have to use autodoc for practical reasons at the  
moment, this principle sounds cool (consider the object-oriented  
principle of encapsulation that basically says that interface and  
implementation should be separated so that changing the  
implementation does not change the interface.)

Are you aware of other projects that use similar technique for  
generating the interface?

 From a practical viewpoint the program is partly specified in a  
manifest, and the interface is generated from a manifest. This  
translation would really correspond to a macro language that reads  
inputs, separates attributes, and then generates output. Is libwww  
the first to realise this paradigm, or is there any other projects  
that do this? (And besides Xml Stylesheet Language XSL that does this  
at runtime.) A macro language that performs substitutions on  
attributes basis can be compared to m4, that performs substitution on  
token or postfix basis.