]> git.ipfire.org Git - thirdparty/squid.git/blob - scripts/www/build-cfg-help.pl
bd4bd715f59a3306b0a41a84db1904458634ac64
[thirdparty/squid.git] / scripts / www / build-cfg-help.pl
1 #!/usr/bin/perl -w
2 #
3 # * Copyright (C) 1996-2025 The Squid Software Foundation and contributors
4 # *
5 # * Squid software is distributed under GPLv2+ license and includes
6 # * contributions from numerous individuals and organizations.
7 # * Please see the COPYING and CONTRIBUTORS files for details.
8 #
9
10 use strict;
11 use IO::File;
12 use Getopt::Long;
13 use File::Basename;
14
15 # This mess is designed to parse the squid config template file
16 # cf.data.pre and generate a set of HTML pages to use as documentation.
17 #
18 # Adrian Chadd <adrian@squid-cache.org>
19
20 #
21 # The template file is reasonably simple to parse. There's a number of
22 # directives which delineate sections but there's no section delineation.
23 # A section will "look" somewhat like this, most of the time:
24 # NAME: <name>
25 # IFDEF: <the ifdef bit>
26 # TYPE: <the config type>
27 # LOC: <location in the Config struct>
28 # DEFAULT: <the default value(s) - may be multiple lines>
29 # DEFAULT_IF_NONE: <alternative default value>
30 # DEFAULT_DOC: <the text to display instead of default value(s)>
31 # DOC_START
32 # documentation goes here
33 # NOCOMMENT_START
34 # stuff which goes verbatim into the config file goes here
35 # NOCOMMENT_END
36 # DOC_END
37 #
38 # Now, we can't assume its going to be nicely nested, so I'll say that
39 # sections are delineated by NAME: lines, and then stuff is marked up
40 # appropriately.
41 #
42 # Then we have to fake paragraph markups as well for the documentation.
43 # We can at least use <PRE> type markups for the NOCOMMENT_START/_END stuff.
44
45 #
46 # Configuration sections are actually broken up by COMMENT_START/COMMENT_END
47 # bits, which we can use in the top-level index page. Nifty!
48 #
49
50 # XXX NAME: can actually have multiple entries on it; we should generate
51 # XXX a configuration index entry for each, linking back to the one entry.
52 # XXX I'll probably just choose the first entry in the list.
53
54 #
55 # This code is ugly, but meh. We'll keep reading, line by line, and appending
56 # lines into 'state' variables until the next NAME comes up. We'll then
57 # shuffle everything off to a function to generate the page.
58
59
60 my ($state) = "";
61 my (%option);
62 my (%all_names);
63 my ($comment);
64 my (%defines);
65
66 my $version = "3.1.0";
67 my $verbose = '';
68 my $path = "/tmp";
69 my $format = "splithtml";
70 my $pagetemplate;
71
72 my ($index) = new IO::File;
73
74 my $top = dirname($0);
75
76 GetOptions(
77 'verbose' => \$verbose, 'v' => \$verbose,
78 'out=s' => \$path,
79 'version=s' => \$version,
80 'format=s' => \$format
81 );
82
83 if ($format eq "splithtml") {
84 $pagetemplate = "template.html";
85 } elsif ($format eq "singlehtml") {
86 $pagetemplate = "template_single.html";
87 }
88
89 # Load defines
90 my ($df) = new IO::File;
91
92 $df->open("$top/../../src/cf_gen_defines", "r") || die;
93 while(<$df>) {
94 $defines{$1} = $2 if /define\["([^"]*)"\]="([^"]*)"/;
95 }
96 close $df;
97 undef $df;
98
99 # XXX should implement this!
100 sub uriescape($)
101 {
102 my ($line) = @_;
103 return $line;
104 }
105
106 sub filename($)
107 {
108 my ($name) = @_;
109 return $path . "/" . $name . ".html";
110 }
111
112 sub htmlescape($)
113 {
114 my ($line) = @_;
115 return "" if !defined $line;
116 $line =~ s/&/\&amp;/g;
117 $line =~ s/</\&lt;/g;
118 $line =~ s/>/\&gt;/g;
119 $line =~ s/[^\x{20}-\x{7e}\s]/sprintf ("&#%d;", ord ($1))/ge;
120 return $line;
121 }
122
123 sub section_link($)
124 {
125 return uriescape($_[0]).".html" if $format eq "splithtml";
126 return "#".$_[0] if $format eq "singlehtml";
127 }
128
129 sub toc_link($)
130 {
131 return "index.html#toc_".uriescape($_[0]) if $format eq "splithtml";
132 return "#toc_".uriescape($_[0]) if $format eq "singlehtml";
133 }
134
135 sub alpha_link($)
136 {
137 return "index_all.html#toc_".uriescape($_[0]);
138 }
139
140 #
141 # Yes, we could just read the template file in once..!
142 #
143 sub generate_page($$)
144 {
145 my ($template, $data) = @_;
146 my $fh;
147 my $fh_open = 0;
148 # XXX should make sure the config option is a valid unix filename!
149 if ($format eq "splithtml") {
150 my ($fn) = filename($data->{'name'});
151 $fh = new IO::File;
152 $fh->open($fn, "w") || die "Couldn't open $fn: $!\n";
153 $fh_open = 1;
154 } else {
155 $fh = $index;
156 }
157
158 $data->{"ifdef"} = $defines{$data->{"ifdef"}} if (exists $data->{"ifdef"} && exists $defines{$data->{"ifdef"}});
159
160 my ($th) = new IO::File;
161 $th->open($template, "r") || die "Couldn't open $template: $!\n";
162
163 # add in the local variables
164 $data->{"title"} = $data->{"name"};
165 $data->{"ldoc"} = $data->{"doc"};
166 $data->{"toc_link"} = toc_link($data->{"name"});
167 $data->{"alpha_link"} = alpha_link($data->{"name"});
168 if (exists $data->{"aliases"}) {
169 $data->{"aliaslist"} = join(", ", @{$data->{"aliases"}});
170 }
171 # XXX can't do this and then HTML escape..
172 # $data->{"ldoc"} =~ s/\n\n/<\/p>\n<p>\n/;
173 # XXX and the end-of-line formatting to turn single \n's into <BR>\n's.
174
175 while (<$th>) {
176 # Do variable substitution
177 s/%(.*?)%/htmlescape($data->{$1})/ge;
178 print $fh $_;
179 }
180 close $th;
181 undef $th;
182
183 if ($fh_open) {
184 close $fh;
185 undef $fh;
186 }
187 }
188
189 $index->open(filename("index"), "w") || die "Couldn't open ".filename("index").": $!\n" if ($format eq "splithtml");
190 $index->open($path, "w") || die "Couldn't open ".filename("index").": $!\n" if ($format eq "singlehtml");
191 print $index <<EOF
192 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
193 <html xmlns="http://www.w3.org/1999/xhtml">
194 <head>
195 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
196 <title>Squid $version configuration file</title>
197 <meta name="keywords" content="squid squid.conf config configure" />
198 <meta name="description" content="Squid $version" />
199 <link rel="stylesheet" type="text/css" href="http://www.squid-cache.org/default.css" />
200 <link rel="stylesheet" type="text/css" href="http://www.squid-cache.org/cfgman.css" />
201 </head>
202 <body>
203 EOF
204 ;
205
206
207 my ($name, $data);
208 my (@chained);
209
210 my $in_options = 0;
211 sub start_option($$)
212 {
213 my ($name, $type) = @_;
214 if (!$in_options) {
215 print $index "<ul>\n";
216 $in_options = 1;
217 }
218 return if $type eq "obsolete";
219 print $index ' <li><a href="' . htmlescape(section_link($name)) . '" name="toc_' . htmlescape($name) . '">' . htmlescape($name) . "</a></li>\n";
220 }
221 sub end_options()
222 {
223 return if !$in_options;
224 print $index "</ul>\n";
225 $in_options = 0;
226 }
227 sub section_heading($)
228 {
229 my ($comment) = @_;
230 print $index "<pre>\n";
231 print $index $comment;
232 print $index "</pre>\n";
233 }
234 sub update_defaults()
235 {
236 if (defined($data->{"default_doc"})) {
237 # default text description masks out the default value display
238 if($data->{"default_doc"} ne "") {
239 print "REPLACE: default '". $data->{"default"} ."' with '" . $data->{"default_doc"} . "'\n" if $verbose;
240 $data->{"default"} = $data->{"default_doc"};
241 }
242 }
243 # when we have no predefined default use the DEFAULT_IF_NONE
244 if (defined($data->{"default_if_none"})) {
245 print "REPLACE: default '". $data->{"default"} ."' with '" . $data->{"default_if_none"} . "'\n" if $verbose && $data->{"default"} eq "";
246 $data->{"default"} = $data->{"default_if_none"} if $data->{"default"} eq "";
247 }
248 }
249
250 my @ifelse = ();
251 while (<>) {
252 chomp;
253 last if (/^EOF$/);
254 if ($_ =~ /^NAME: (.*)$/) {
255 my (@aliases) = split(/ /, $1);
256 $data = {};
257 $data->{'version'} = $version;
258 foreach (@aliases) {
259 $all_names{$_} = $data;
260 }
261
262 $name = shift @aliases;
263
264 $option{$name} = $data;
265 $data->{'name'} = $name;
266 $data->{'aliases'} = \@aliases;
267 $data->{'default'} = "";
268 $data->{'default_doc'} = "";
269 $data->{'default_if_none'} = "";
270
271 print "DEBUG: line $.: new option: $name\n" if $verbose;
272 next;
273 } elsif ($_ =~ /^IF (.*)$/) {
274 my $cond = $1;
275 push(@ifelse, "$.: $1");
276 if (! defined $defines{$1}) {
277 print "NOTICE: line $.: unknown ./configure option '$1'\n";
278 } else {
279 $cond = $defines{$1};
280 }
281 if ($state eq "doc") {
282 $data->{"doc"} .= "if " . $cond . "\n";
283 } elsif ($state eq "comment") {
284 $comment .= "if " . $cond . "\n";
285 }
286 } elsif ($_ =~ /^ENDIF$/) {
287 pop(@ifelse);
288 if ($state eq "doc") {
289 $data->{"doc"} .= "endif\n";
290 } elsif ($state eq "comment") {
291 $comment .= "endif\n";
292 }
293 } elsif ($_ =~ /^COMMENT: (.*)$/) {
294 $data->{"comment"} = $1;
295 } elsif ($_ =~ /^TYPE: (.*)$/) {
296 $data->{"type"} = $1;
297 start_option($data->{"name"}, $data->{"type"});
298 } elsif ($_ =~ /^DEFAULT: (.*)$/) {
299 if ($1 eq "none") {
300 $data->{"default"} = "$1\n";
301 } else {
302 $data->{"default"} .= "$name $1\n";
303 }
304 } elsif ($_ =~ /^POSTSCRIPTUM: (.*)$/) {
305 if ($data->{"default"} eq "none") {
306 $data->{"default"} = "";
307 }
308 $data->{"default"} .= "$name $1\n";
309 } elsif ($_ =~ /^DEFAULT_DOC: (.*)$/) {
310 $data->{"default_doc"} .= "$1\n";
311 } elsif ($_ =~ /^DEFAULT_IF_NONE: (.*)$/) {
312 $data->{"default_if_none"} .= "$1\n";
313 } elsif ($_ =~ /^LOC:(.*)$/) {
314 $data->{"loc"} = $1;
315 $data->{"loc"} =~ s/^[\s\t]*//;
316 } elsif ($_ =~ /^DOC_START$/) {
317 update_defaults;
318 $state = "doc";
319 } elsif ($_ =~ /^DOC_END$/) {
320 $state = "";
321 my $othername;
322 foreach $othername (@chained) {
323 $option{$othername}{'doc'} = $data->{'doc'};
324 }
325 undef @chained;
326 } elsif ($_ =~ /^DOC_NONE$/) {
327 update_defaults;
328 push(@chained, $name);
329 } elsif ($_ =~ /^NOCOMMENT_START$/) {
330 $state = "nocomment";
331 } elsif ($_ =~ /^NOCOMMENT_END$/) {
332 $state = "";
333 } elsif ($_ =~ /^IFDEF: (.*)$/) {
334 $data->{"ifdef"} = $1;
335 } elsif ($_ =~ /^#/ && $state eq "doc") {
336 $data->{"config"} .= $_ . "\n";
337 } elsif ($state eq "nocomment") {
338 $data->{"config"} .= $_ . "\n";
339 } elsif ($state eq "doc") {
340 $data->{"doc"} .= $_ . "\n";
341 } elsif ($_ =~ /^COMMENT_START$/) {
342 end_options;
343 $state = "comment";
344 $comment = "";
345 } elsif ($_ =~ /^COMMENT_END$/) {
346 section_heading($comment);
347 } elsif ($state eq "comment") {
348 $comment .= $_ . "\n";
349 } elsif (/^#/) {
350 next;
351 } elsif ($_ ne "") {
352 print "NOTICE: line $.: unknown line '$_'\n";
353 }
354 }
355 foreach my $condition (@ifelse) {
356 print "ERROR: missing ENDIF to match $condition\n";
357 }
358 end_options;
359 print $index "<p><a href=\"index_all.html\">Alphabetic index</a></p>\n" if $format eq "splithtml";
360 print $index "<p><a href=\"#index\">Alphabetic index</a></p>\n" if $format eq "singlehtml";
361 print $index "<hr />\n" if $format eq "singlehtml";
362
363 # and now, build the option pages
364 my (@names) = keys %option;
365 foreach $name (@names) {
366 next if $option{$name}->{'type'} eq "obsolete";
367 generate_page("${top}/${pagetemplate}", $option{$name});
368 }
369
370 # and now, the alphabetic index file!
371 my $fh;
372 my $fh_open = 0;
373
374 if ($format eq "splithtml") {
375 $fh = new IO::File;
376 my ($indexname) = filename("index_all");
377 $fh->open($indexname, "w") || die "Couldn't open $indexname for writing: $!\n";
378 $fh_open = 1;
379 print $fh <<EOF
380 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
381 <html xmlns="http://www.w3.org/1999/xhtml">
382 <head>
383 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
384 <title>Squid $version configuration file</title>
385 <meta name="keywords" content="squid squid.conf config configure" />
386 <meta name="description" content="Squid $version" />
387 <link rel="stylesheet" type="text/css" href="http://www.squid-cache.org/default.css" />
388 <link rel="stylesheet" type="text/css" href="http://www.squid-cache.org/cfgman.css" />
389 </head>
390 <body>
391 <div id="header">
392 <div id="logo">
393 <h1><a href="http://www.squid-cache.org/"><span>Squid-</span>Cache.org</a></h1>
394 <h2>Optimising Web Delivery</h2>
395 </div>
396 </div>
397
398 <p>| <a href="index.html">Table of contents</a> |</p>
399
400 <h1>Alphabetic index of all options</h1>
401 EOF
402 ;
403 } elsif ($format eq "singlehtml") {
404 $fh = $index;
405 print $fh "<h2><a name=\"index\">Alphabetic index of all options</a></h2>\n";
406 }
407
408 print $fh "<ul>\n";
409
410 foreach $name (sort keys %all_names) {
411 my ($data) = $all_names{$name};
412 next if $data->{'type'} eq "obsolete";
413 print $fh ' <li><a href="' . uriescape($data->{'name'}) . '.html" name="toc_' . htmlescape($name) . '">' . htmlescape($name) . "</a></li>\n";
414 }
415
416 print $fh "</ul>\n";
417 if ($fh_open) {
418 print $fh <<EOF
419 <p>| <a href="index.html">Table of contents</a> |</p>
420 </body>
421 </html>
422 EOF
423 ;
424 $fh->close;
425 }
426 undef $fh;
427
428 print $index <<EOF
429 </body>
430 </html>
431 EOF
432 ;
433 $index->close;
434 undef $index;