--------------------- PatchSet 10802 Date: 2007/05/18 00:43:28 Author: hno Branch: HEAD Tag: (none) Log: Imported cf.data.pre -> HTML script from Squid-2. Imported changes: 2007/05/13 12:18:00 adrian +114 -0 Flesh out the beginnings of a cf.data.pre -> web interface. 2007/05/13 12:34:31 adrian +23 -2 Flesh out a little more for testing. I need to treat NAME entries with 2007/05/13 13:49:56 adrian +18 -2 Handle name aliases right. 2007/05/13 14:02:40 hno +6 -1 Add --out and --verbose command line options 2007/05/13 14:04:40 adrian +33 -32 Prepare for the actual page generating code. 2007/05/13 14:33:12 adrian +72 -19 Begin writing pages. 2007/05/13 14:43:50 adrian +8 -7 More HTML generation fixes. 2007/05/13 14:46:32 adrian +3 -2 Fix escaping. 2007/05/13 14:51:55 adrian +20 -3 Add in some more "full" template.. 2007/05/13 14:58:40 adrian +15 -6 * try to show the aliases in the output; they're not yet working 2007/05/13 17:01:45 hno +133 -54 Get the ToC running, with raw section separators. 2007/05/13 21:12:56 hno +8 -0 Dump out the config manual while making snapshots 2007/05/13 21:13:14 hno +5 -3 Pick up the templates relative to the script location 2007/05/13 22:16:56 hno +108 -34 Hacked up a single page document mode 2007/05/13 22:28:49 hno +2 -0 Build single-page config manual as well as part of the snapshot process 2007/05/13 22:34:18 hno +2 -1 Compress the single-page config manual 2007/05/13 22:38:26 hno +1 -1 Correct format of single page configuration manual 2007/05/14 14:34:21 amosjeffries +102 -67 Fancy-Up the squid.conf documentation output. 2007/05/14 14:51:26 adrian +11 -2 Fix the templates to
'ify suggested config. 2007/05/14 14:55:48 adrian +11 -1 Use the new format CSS now. 2007/05/14 15:16:31 adrian +16 -29 * remove the CSS stuff for now; eww. 2007/05/15 11:45:59 amosjeffries +9 -9 Fixed HTML structure somehow broken:=> Members: scripts/www/build-cfg-help.pl:INITIAL->1.1 scripts/www/template.html:INITIAL->1.1 scripts/www/template_single.html:INITIAL->1.1 --- /dev/null Fri May 18 00:52:30 2007 +++ squid3/scripts/www/build-cfg-help.pl Fri May 18 00:52:30 2007 @@ -0,0 +1,348 @@ +#!/usr/bin/perl -w + +use strict; +use IO::File; +use Getopt::Long; + +# This mess is designed to parse the squid config template file +# cf.data.pre and generate a set of HTML pages to use as documentation. +# +# Adrian Chadd +# +# $Id: build-cfg-help.pl,v 1.1 2007/05/18 00:43:28 hno Exp $ + +# +# The template file is reasonably simple to parse. There's a number of +# directives which delineate sections but there's no section delineation. +# A section will "look" somewhat like this, most of the time: +# NAME: +# IFDEF: +# TYPE: +# DEFAULT: +# LOC: +# DOC_START +# documentation goes here +# NOCOMMENT_START +# stuff which goes verbatim into the config file goes here +# NOCOMMENT_END +# DOC_END +# +# Now, we can't assume its going to be nicely nested, so I'll say that +# sections are delineated by NAME: lines, and then stuff is marked up +# appropriately. +# +# Then we have to fake paragraph markups as well for the documentation. +# We can at least use type markups for the NOCOMMENT_START/_END stuff. + +# +# Configuration sections are actually broken up by COMMENT_START/COMMENT_END +# bits, which we can use in the top-level index page. Nifty! +# + +# XXX NAME: can actually have multiple entries on it; we should generate +# XXX a configuration index entry for each, linking back to the one entry. +# XXX I'll probably just choose the first entry in the list. + +# +# This code is ugly, but meh. We'll keep reading, line by line, and appending +# lines into 'state' variables until the next NAME comes up. We'll then +# shuffle everything off to a function to generate the page. + + +my ($state) = ""; +my (%option); +my (%all_names); +my ($comment); + +my $version = "2.HEAD"; +my $verbose = ''; +my $path = "/tmp"; +my $format = "splithtml"; +my $pagetemplate; + +my ($index) = new IO::File; + +my $top = $0; +$top =~ s%[^/]*$%%; + +GetOptions( + 'verbose' => \$verbose, 'v' => \$verbose, + 'out=s' => \$path, + 'version=s' => \$version, + 'format=s' => \$format + ); + +if ($format eq "splithtml") { + $pagetemplate = "template.html"; +} elsif ($format eq "singlehtml") { + $pagetemplate = "template_single.html"; +} + +# XXX should implement this! +sub uriescape($) +{ + my ($line) = @_; + return $line; +} + +sub filename($) +{ + my ($name) = @_; + return $path . "/" . $name . ".html"; +} + +sub htmlescape($) +{ + my ($line) = @_; + return "" if !defined $line; + $line =~ s/([^\w\s])/sprintf ("%d;", ord ($1))/ge; + return $line; +} + +sub section_link($) +{ + return uriescape($_[0]).".html" if $format eq "splithtml"; + return "#".$_[0] if $format eq "singlehtml"; +} + +sub toc_link($) +{ + return "index.html#toc_".uriescape($_[0]) if $format eq "splithtml"; + return "#toc_".uriescape($_[0]) if $format eq "singlehtml"; +} + +sub alpha_link($) +{ + return "index_all.html#toc_".uriescape($_[0]); +} + +# +# Yes, we could just read the template file in once..! +# +sub generate_page($$) +{ + my ($template, $data) = @_; + my $fh; + my $fh_open = 0; + # XXX should make sure the config option is a valid unix filename! + if ($format eq "splithtml") { + my ($fn) = filename($data->{'name'}); + $fh = new IO::File; + $fh->open($fn, "w") || die "Couldn't open $fn: $!\n"; + $fh_open = 1; + } else { + $fh = $index; + } + + + my ($th) = new IO::File; + $th->open($template, "r") || die "Couldn't open $template: $!\n"; + + # add in the local variables + $data->{"title"} = $data->{"name"}; + $data->{"ldoc"} = $data->{"doc"}; + $data->{"toc_link"} = toc_link($data->{"name"}); + $data->{"alpha_link"} = alpha_link($data->{"name"}); + if (exists $data->{"aliases"}) { + $data->{"aliaslist"} = join(", ", @{$data->{"aliases"}}); + } + # XXX can't do this and then HTML escape.. + # $data->{"ldoc"} =~ s/\n\n/<\/p>\n\n/; + # XXX and the end-of-line formatting to turn single \n's into
+ + +EOF +; +$fh->close; +} +undef $fh; + +print $index <
\n's. + + while (<$th>) { + # Do variable substitution + s/%(.*?)%/htmlescape($data->{$1})/ge; + print $fh $_; + } + close $th; + undef $th; + + if ($fh_open) { + close $fh; + undef $fh; + } +} + +$index->open(filename("index"), "w") || die "Couldn't open ".filename("index").": $!\n" if ($format eq "splithtml"); +$index->open($path, "w") || die "Couldn't open ".filename("index").": $!\n" if ($format eq "singlehtml"); +print $index <+ + + + Squid $version configuration file + + + + +EOF +; + + +my ($name, $data); +my (@chained); + +my $in_options = 0; +sub start_option($) +{ + my ($name) = @_; + if (!$in_options) { + print $index "\n"; + $in_options = 1; + } + print $index '
\n"; + $in_options = 0; +} +while (<>) { + chomp; + last if (/^EOF$/); + if ($_ =~ /^NAME: (.*)$/) { + my (@aliases) = split(/ /, $1); + $data = {}; + $data->{'version'} = $version; + foreach (@aliases) { + $all_names{$_} = $data; + } + + $name = shift @aliases; + + $option{$name} = $data; + $data->{'name'} = $name; + $data->{'aliases'} = \@aliases; + + start_option($name); + print "DEBUG: new option: $name\n" if $verbose; + } elsif ($_ =~ /^COMMENT: (.*)$/) { + $data->{"comment"} = $1; + } elsif ($_ =~ /^TYPE: (.*)$/) { + $data->{"type"} = $1; + } elsif ($_ =~ /^DEFAULT: (.*)$/) { + if ($1 eq "none") { + $data->{"default"} = "$1"; + } else { + $data->{"default"} = "$name $1"; + } + } elsif ($_ =~ /^LOC:(.*)$/) { + $data->{"loc"} = $1; + $data->{"loc"} =~ s/^[\s\t]*//; + } elsif ($_ =~ /^DOC_START$/) { + $state = "doc"; + } elsif ($_ =~ /^DOC_END$/) { + $state = ""; + my $othername; + foreach $othername (@chained) { + $option{$othername}{'doc'} = $data->{'doc'}; + } + undef @chained; + } elsif ($_ =~ /^DOC_NONE$/) { + push(@chained, $name); + } elsif ($_ =~ /^NOCOMMENT_START$/) { + $state = "nocomment"; + } elsif ($_ =~ /^DEFAULT_IF_NONE: (.*)$/) { + $data->{"default_if_none"} = $1; + } elsif ($_ =~ /^NOCOMMENT_END$/) { + $state = ""; + } elsif ($_ =~ /^IFDEF: (.*)$/) { + $data->{"ifdef"} = $1; + } elsif ($_ =~ /^#/ && $state eq "doc") { + $data->{"config"} .= $_ . "\n"; + } elsif ($state eq "nocomment") { + $data->{"config"} .= $_ . "\n"; + } elsif ($state eq "doc") { + $data->{"doc"} .= $_ . "\n"; + } elsif ($_ =~ /^COMMENT_START$/) { + end_options; + $state = "comment"; + $comment = ""; + } elsif ($_ =~ /^COMMENT_END$/) { + print $index "- ' . htmlescape($name) . "
\n"; +} +sub end_options() +{ + return if !$in_options; + print $index "\n"; + print $index $comment; + print $index "\n"; + } elsif ($state eq "comment") { + $comment .= $_ . "\n"; + } elsif (/^#/) { + next; + } elsif ($_ ne "") { + print "NOTICE: unknown line '$_'\n"; + } +} +end_options; +print $index "\n"; +print $index "\n" if $format eq "splithtml"; +print $index "\n" if $format eq "singlehtml"; +print $index "
\n" if $format eq "singlehtml"; + +# and now, build the option pages +my (@names) = keys %option; +foreach $name (@names) { + generate_page("${top}${pagetemplate}", $option{$name}); +} + +# and now, the alpabetic index file! +my $fh; +my $fh_open = 0; + +if ($format eq "splithtml") { + $fh = new IO::File; + my ($indexname) = filename("index_all"); + $fh->open($indexname, "w") || die "Couldn't open $indexname for writing: $!\n"; + $fh_open = 1; + print $fh <+ + + + Squid $version configuration file + + + + +++ + + +++Squid-Cache.org
+Optimising Web Delivery
+Alphabetic index of all options
+EOF +; +} elsif ($format eq "singlehtml") { + $fh = $index; + print $fh "Alphabetic index of all options
\n"; +} + +print $fh "\n"; + +foreach $name (sort keys %all_names) { + my ($data) = $all_names{$name}; + print $fh '
\n"; +if ($fh_open) { +print $fh <- ' . htmlescape($name) . "
\n"; +} + +print $fh "| Table of contents | + +EOF +; +$index->close; +undef $index; --- /dev/null Fri May 18 00:52:30 2007 +++ squid3/scripts/www/template.html Fri May 18 00:52:30 2007 @@ -0,0 +1,54 @@ + + + + + Squid %version% Configuration File: %title% + + + + + + ++ | Index + | Alphabetical Index | +
+ ++
+ ++ +Option Name: %name% ++ +Also Known As: %aliaslist% ++ +Requires: %ifdef% ++ +Default Value: %default% ++ +Suggested Config: ++ ++%config% +++ ++ ++%ldoc% +++ + | Index + | Alphabetical Index | +
+ + + --- /dev/null Fri May 18 00:52:30 2007 +++ squid3/scripts/www/template_single.html Fri May 18 00:52:30 2007 @@ -0,0 +1,32 @@ + +Option: %name%
++
+ +Option Name: %name% ++ +Also Known As: %aliaslist% ++ +Compile Requires: %ifdef% ++ +Default Value: %default% ++ +Suggested Config: ++ ++%config% +++ ++ ++%ldoc% +++