From: Martin Mares Date: Tue, 9 Sep 2008 10:29:19 +0000 (+0200) Subject: Doc. system: Renamed doc utilities to match local conventions. X-Git-Tag: holmes-import~326 X-Git-Url: http://mj.ucw.cz/gitweb/?a=commitdiff_plain;h=776f1a3bb4ee326f60cf4e1944ff80c1a3878d1e;p=libucw.git Doc. system: Renamed doc utilities to match local conventions. First, we do not use filename extensions for scripts which are not "compiled" (e.g., the scripts that are a part of the build system). Second, we prefer to build the naming hierarchy from the opposite end. --- diff --git a/build/Makebottom b/build/Makebottom index a0063756..772b4cbc 100644 --- a/build/Makebottom +++ b/build/Makebottom @@ -201,12 +201,12 @@ $(o)/%.html: $(o)/%.txt $(patsubst %.html,%.txt,$(DOC_INDICES)): $(o)/%.txt: $(M)"DOC-DEFS $@" $(Q)echo $@: $(DOC_HEAD) $(DOC_LIST) >> $(o)/depend.new - $(Q)$(s)/build/def-doc.pl $(DOC_HEAD) $@ $(DOC_LIST) + $(Q)$(s)/build/doc-defs $(DOC_HEAD) $@ $(DOC_LIST) #FIXME: this one outputs .deflist too. How do I specify that one run of the rule has multiple target files? $(patsubst %.html,%.txt,$(DOCS)): $(o)/%.txt: $(s)/%.txt $(M)"DOC-EXT $<" - $(Q)$(s)/build/extract-doc.pl $< $@ $(o)/depend.new $(s) $(patsubst %.txt,%.deflist,$@) + $(Q)$(s)/build/doc-extract $< $@ $(o)/depend.new $(s) $(patsubst %.txt,%.deflist,$@) # Default installation target diff --git a/build/def-doc.pl b/build/def-doc.pl deleted file mode 100755 index a39cda40..00000000 --- a/build/def-doc.pl +++ /dev/null @@ -1,35 +0,0 @@ -#!/usr/bin/perl -# Script for formatting documentation from definition lists -# (they get out of extract-doc.pl as a side-product). -# (c) 2008 Michal Vaner -use strict; -use warnings; - -my $head = shift; -my $out = shift; - -open OUT, ">$out" or die "Could not write output $out ($!)\n"; -open HEAD, $head or die "Could not open head $head ($!)\n"; -print OUT foreach( ); -close HEAD; - -my $dir = $out; -$dir =~ s/\/[^\/]+$//; - -while( defined( my $line = <> ) ) { - chomp $line; - my( $file, $num, $text ) = split /,/, $line, 3; - my $dircp = $dir; - while( shift @{[ $dircp =~ /([^\/]+)/, "//" ]} eq shift @{[ $file =~ /([^\/]+)/, "///" ]} ) { - $dircp =~ s/[^\/]+\/?//; - $file =~ s/[^\/]+\/?//; - } - $dircp =~ s/[^\/]+/../g; - $file = $dircp."/".$file; - $file =~ s/^\///; - $file =~ s/\.[^.]+$//; - $text =~ s/\(/!!PARENT_OPEN!!/g; - print OUT "- <<$file:auto_$num,`$text`>>\n"; -} - -close OUT; diff --git a/build/doc-defs b/build/doc-defs new file mode 100755 index 00000000..a39cda40 --- /dev/null +++ b/build/doc-defs @@ -0,0 +1,35 @@ +#!/usr/bin/perl +# Script for formatting documentation from definition lists +# (they get out of extract-doc.pl as a side-product). +# (c) 2008 Michal Vaner +use strict; +use warnings; + +my $head = shift; +my $out = shift; + +open OUT, ">$out" or die "Could not write output $out ($!)\n"; +open HEAD, $head or die "Could not open head $head ($!)\n"; +print OUT foreach( ); +close HEAD; + +my $dir = $out; +$dir =~ s/\/[^\/]+$//; + +while( defined( my $line = <> ) ) { + chomp $line; + my( $file, $num, $text ) = split /,/, $line, 3; + my $dircp = $dir; + while( shift @{[ $dircp =~ /([^\/]+)/, "//" ]} eq shift @{[ $file =~ /([^\/]+)/, "///" ]} ) { + $dircp =~ s/[^\/]+\/?//; + $file =~ s/[^\/]+\/?//; + } + $dircp =~ s/[^\/]+/../g; + $file = $dircp."/".$file; + $file =~ s/^\///; + $file =~ s/\.[^.]+$//; + $text =~ s/\(/!!PARENT_OPEN!!/g; + print OUT "- <<$file:auto_$num,`$text`>>\n"; +} + +close OUT; diff --git a/build/doc-extract b/build/doc-extract new file mode 100755 index 00000000..ca4e42e2 --- /dev/null +++ b/build/doc-extract @@ -0,0 +1,155 @@ +#!/usr/bin/perl +# Script for extracting documentation out of header files +# (c) 2008 Michal Vaner + +use strict; +use warnings; + +my( $inname, $outname, $depname, $basedir, $defdump ) = @ARGV; +if( defined $inname ) { + open IN, $inname or die "Could not read $inname ($!)\n"; +} else { + open IN, "<&STDIN" or die "Could not read stdin ($!)\n"; +} +if( defined $outname ) { + open OUT, ">$outname" or die "Could not write $outname ($!)\n"; +} else { + open OUT, ">&STDOUT" or die "Could not write to stdout ($!)\n"; +} +my $hasdump; +if( defined $defdump ) { + open DUMP, ">>$defdump" or die "Could not write definition dump $defdump ($!)\n"; + $hasdump = 1; +} + +my @deps; +my $id = 0; + +sub formatNote( $$ ) { + my( $head, $comment ) = @_; + $head =~ s/(\S)[ ]+/$1 /g; + print OUT "\n"; + print OUT "''''\n"; + chomp $head; + print OUT "[[auto_$id]]\n"; + if($head =~ /\w+\([^()]*\)/ && $head !~ /\n/) { + print OUT "!!f!$head!!!\n\n"; + } else { + print OUT "..................\n"; + print OUT "$head\n"; + print OUT "..................\n\n"; + } + if( $hasdump ) { + $head =~ s/\n.*//s; + print DUMP "$outname,$id,$head\n"; + $id ++; + } + print OUT "$comment\n\n"; +} + +sub process( $ ) { + my $file = shift; + open FILE, $file or die "Could nod read $file ($!)\n"; + my $line; + my $active; + my $verbatim; + my $buff; + my $head; + my $struct; + while( defined( $line = ) ) { + chomp $line; + if( $struct ) { + $head .= "\n".$line; + if( $line =~ /}/ ) { + formatNote( $head, $buff ); + $struct = 0; + $buff = undef; + $head = undef; + } + } elsif( $verbatim ) { + if( $line =~ /\*\// ) { + $verbatim = 0; + print OUT "\n"; + } else { + $line =~ s/^\s*\* ?//; + print OUT "$line\n"; + } + } elsif( $active ) { + if( $line =~ /\*\// ) { + $active = 0; + } else { + $line =~ s/^\s*\* ?//; + $buff .= "$line\n"; + } + } else { + if( ( $line =~ /\S/ ) && ( defined $buff ) ) { + if( $line =~ /\(/ || $line !~ /{/ ) { + $_ = $line; + s/^\s*\s?//; + s/\/\/.*//; + s/\/\*.*?\*\///gs; + s/([;{]).*/";"x length( $1 )/e; + s/\)\s*;$/);/; + formatNote( $_, $buff ); + $head = undef; + $buff = undef; + } else { + $head = $line; + $struct = 1; + } + } elsif( ( $buff ) = ( $line =~ /\/\*\*\*(.*)\*\*\*\// ) ) { + $buff =~ s/\s?//; + print OUT "$buff\n\n"; + $buff = undef; + } elsif( ( $head, $buff ) = ( $line =~ /^(.*)\/\*\*(.*)\*\*\// ) ) { + $buff =~ s/^\s*//; + $buff =~ s/\s*$//; + if( $head =~ /\(/ || $head !~ /{/ ) { + $head =~ s/^\s*//; + $head =~ s/\/\*.*?\*\///gs; + $head =~ s/([;{]).*/";"x length( $1 )/e; + $head =~ s/\)\s*;$/);/; + formatNote( $head, $buff ); + $head = undef; + $buff = undef; + } else { + $struct = 1; + } + } elsif( $line =~ /\/\*\*\*/ ) { + $verbatim = 1; + } elsif( $line =~ /\/\*\*/ ) { + $active = 1; + } + } + } + close FILE; +} + +my $line; +while( defined( $line = ) ) { + chomp $line; + if( my( $fname ) = ( $line =~ /^!!\s*(.*\S)/ ) ) { + $fname = "$basedir/$fname" if( ( $fname !~ /^\// ) && defined $basedir ); + process( $fname ); + push @deps, $fname; + } else { + print OUT "$line\n"; + } +} + +if( defined $depname ) { + open DEP, ">>$depname" or die "Could not write dep file $depname ($!)\n"; + print DEP "$outname:"; + print DEP " $_" foreach( @deps ); + print DEP "\n"; + if( $hasdump ) { + print DEP "$defdump:"; + print DEP " $_" foreach( @deps ); + print DEP "\n"; + } + close DEP; +} + +close IN; +close OUT; +close DUMP; diff --git a/build/extract-doc.pl b/build/extract-doc.pl deleted file mode 100755 index ca4e42e2..00000000 --- a/build/extract-doc.pl +++ /dev/null @@ -1,155 +0,0 @@ -#!/usr/bin/perl -# Script for extracting documentation out of header files -# (c) 2008 Michal Vaner - -use strict; -use warnings; - -my( $inname, $outname, $depname, $basedir, $defdump ) = @ARGV; -if( defined $inname ) { - open IN, $inname or die "Could not read $inname ($!)\n"; -} else { - open IN, "<&STDIN" or die "Could not read stdin ($!)\n"; -} -if( defined $outname ) { - open OUT, ">$outname" or die "Could not write $outname ($!)\n"; -} else { - open OUT, ">&STDOUT" or die "Could not write to stdout ($!)\n"; -} -my $hasdump; -if( defined $defdump ) { - open DUMP, ">>$defdump" or die "Could not write definition dump $defdump ($!)\n"; - $hasdump = 1; -} - -my @deps; -my $id = 0; - -sub formatNote( $$ ) { - my( $head, $comment ) = @_; - $head =~ s/(\S)[ ]+/$1 /g; - print OUT "\n"; - print OUT "''''\n"; - chomp $head; - print OUT "[[auto_$id]]\n"; - if($head =~ /\w+\([^()]*\)/ && $head !~ /\n/) { - print OUT "!!f!$head!!!\n\n"; - } else { - print OUT "..................\n"; - print OUT "$head\n"; - print OUT "..................\n\n"; - } - if( $hasdump ) { - $head =~ s/\n.*//s; - print DUMP "$outname,$id,$head\n"; - $id ++; - } - print OUT "$comment\n\n"; -} - -sub process( $ ) { - my $file = shift; - open FILE, $file or die "Could nod read $file ($!)\n"; - my $line; - my $active; - my $verbatim; - my $buff; - my $head; - my $struct; - while( defined( $line = ) ) { - chomp $line; - if( $struct ) { - $head .= "\n".$line; - if( $line =~ /}/ ) { - formatNote( $head, $buff ); - $struct = 0; - $buff = undef; - $head = undef; - } - } elsif( $verbatim ) { - if( $line =~ /\*\// ) { - $verbatim = 0; - print OUT "\n"; - } else { - $line =~ s/^\s*\* ?//; - print OUT "$line\n"; - } - } elsif( $active ) { - if( $line =~ /\*\// ) { - $active = 0; - } else { - $line =~ s/^\s*\* ?//; - $buff .= "$line\n"; - } - } else { - if( ( $line =~ /\S/ ) && ( defined $buff ) ) { - if( $line =~ /\(/ || $line !~ /{/ ) { - $_ = $line; - s/^\s*\s?//; - s/\/\/.*//; - s/\/\*.*?\*\///gs; - s/([;{]).*/";"x length( $1 )/e; - s/\)\s*;$/);/; - formatNote( $_, $buff ); - $head = undef; - $buff = undef; - } else { - $head = $line; - $struct = 1; - } - } elsif( ( $buff ) = ( $line =~ /\/\*\*\*(.*)\*\*\*\// ) ) { - $buff =~ s/\s?//; - print OUT "$buff\n\n"; - $buff = undef; - } elsif( ( $head, $buff ) = ( $line =~ /^(.*)\/\*\*(.*)\*\*\// ) ) { - $buff =~ s/^\s*//; - $buff =~ s/\s*$//; - if( $head =~ /\(/ || $head !~ /{/ ) { - $head =~ s/^\s*//; - $head =~ s/\/\*.*?\*\///gs; - $head =~ s/([;{]).*/";"x length( $1 )/e; - $head =~ s/\)\s*;$/);/; - formatNote( $head, $buff ); - $head = undef; - $buff = undef; - } else { - $struct = 1; - } - } elsif( $line =~ /\/\*\*\*/ ) { - $verbatim = 1; - } elsif( $line =~ /\/\*\*/ ) { - $active = 1; - } - } - } - close FILE; -} - -my $line; -while( defined( $line = ) ) { - chomp $line; - if( my( $fname ) = ( $line =~ /^!!\s*(.*\S)/ ) ) { - $fname = "$basedir/$fname" if( ( $fname !~ /^\// ) && defined $basedir ); - process( $fname ); - push @deps, $fname; - } else { - print OUT "$line\n"; - } -} - -if( defined $depname ) { - open DEP, ">>$depname" or die "Could not write dep file $depname ($!)\n"; - print DEP "$outname:"; - print DEP " $_" foreach( @deps ); - print DEP "\n"; - if( $hasdump ) { - print DEP "$defdump:"; - print DEP " $_" foreach( @deps ); - print DEP "\n"; - } - close DEP; -} - -close IN; -close OUT; -close DUMP;