Initial attempt at index generation
[exim-website.git] / script / gen.pl
1 #!/usr/bin/perl
2 use strict;
3 use warnings;
4 use CSS::Minifier::XS;
5 use File::Copy;
6 use File::Find;
7 use File::Slurp;
8 use File::Spec;
9 use Getopt::Long;
10 use JavaScript::Minifier::XS;
11 use XML::LibXML;
12 use XML::LibXSLT;
13
14 my $canonical_url = 'http://www.exim.org/';
15
16 ## Parse arguments
17 my %opt = parse_arguments();
18
19 ## Generate the pages
20 do_doc( 'spec',   $_ ) foreach @{ $opt{spec}   || [] };
21 do_doc( 'filter', $_ ) foreach @{ $opt{filter} || [] };
22 do_web() if exists $opt{web};
23
24 ## Add the exim-html-current symlink
25 print "Symlinking exim-html-current to exim-html-$opt{latest}\n";
26 symlink( "$opt{docroot}/exim-html-$opt{latest}", "$opt{docroot}/exim-html-current" );
27
28 ## Generate the website files
29 sub do_web {
30
31     ## Make sure the template web directory exists
32     die "No such directory: $opt{tmpl}/web\n" unless -d "$opt{tmpl}/web";
33
34     ## Scan the web templates
35     find(
36         sub {
37             my ($path) = substr( $File::Find::name, length("$opt{tmpl}/web"), length($File::Find::name) ) =~ m#^/*(.*)$#;
38
39             if ( -d "$opt{tmpl}/web/$path" ) {
40
41                 ## Create the directory in the doc root if it doesn't exist
42                 if ( !-d "$opt{docroot}/$path" ) {
43                     mkdir("$opt{docroot}/$path") or die "Unable to make $opt{docroot}/$path: $!\n";
44                 }
45
46             }
47             else {
48
49                 ## Build HTML from XSL files and simply copy static files which have changed
50                 if ( $path =~ /(.+)\.xsl$/ ) {
51                     print "Generating  : docroot:/$1.html\n";
52                     transform( undef, "$opt{tmpl}/web/$path", "$opt{docroot}/$1.html" );
53                 }
54                 elsif ( -f "$opt{tmpl}/web/$path" ) {
55
56                     ## Skip if the file hasn't changed (mtime based)
57                     return if -f "$opt{docroot}/$path" && ( stat("$opt{tmpl}/web/$path") )[9] == ( stat("$opt{docroot}/$path") )[9];
58
59                     if ( $path =~ /(.+)\.css$/ ) {
60                         print "CSS to  : docroot:/$path\n";
61                         my $content = read_file("$opt{tmpl}/web/$path");
62                         write_file( "$opt{docroot}/$path", $opt{minify} ? CSS::Minifier::XS::minify($content) : $content );
63                     }
64                     elsif ( $path =~ /(.+)\.js$/ ) {
65                         print "JS to  : docroot:/$path\n";
66                         my $content = read_file("$opt{tmpl}/web/$path");
67                         write_file( "$opt{docroot}/$path", $opt{minify} ? JavaScript::Minifier::XS::minify($content) : $content );
68                     }
69                     else {
70                         ## Copy
71                         print "Copying to  : docroot:/$path\n";
72                         copy( "$opt{tmpl}/web/$path", "$opt{docroot}/$path" ) or die "$path: $!";
73                     }
74                     ## Set mtime
75                     utime( time, ( stat("$opt{tmpl}/web/$path") )[9], "$opt{docroot}/$path" );
76                 }
77             }
78
79         },
80         "$opt{tmpl}/web"
81     );
82 }
83
84 ## Generate index/chapter files for a doc
85 sub do_doc {
86     my ( $type, $xml_path ) = @_;
87
88     ## Read and validate the XML file
89     my $xml = XML::LibXML->new()->parse_file($xml_path) or die $!;
90
91     ## Get the version number
92     my $version = $xml->findvalue('/book/bookinfo/revhistory/revision/revnumber');
93     die "Unable to get version number\n" unless defined $version && $version =~ /^\d+(\.\d+)*$/;
94
95     ## Prepend chapter filenames?
96     my $prepend_chapter = $type eq 'filter' ? 'filter_' : '';
97
98     ## Add the canonical url for this document
99     $xml->documentElement()
100       ->appendTextChild( 'canonical_url',
101         "${canonical_url}exim-html-current/doc/html/spec_html/" . ( $type eq 'spec' ? 'index' : 'filter' ) . ".html" );
102
103     ## Fixup the XML
104     xref_fixup( $xml, $prepend_chapter );
105
106     ## Generate the front page
107     {
108         my $path = "exim-html-$version/doc/html/spec_html/" . ( $type eq 'filter' ? $type : 'index' ) . ".html";
109         print "Generating  : docroot:/$path\n";
110         transform( $xml, "$opt{tmpl}/doc/index.xsl", "$opt{docroot}/$path", );
111     }
112
113     ## Generate a Table of Contents XML file
114     {
115         my $path = "exim-html-$version/doc/html/spec_html/" . ( $type eq 'filter' ? 'filter_toc' : 'index_toc' ) . ".xml";
116         print "Generating  : docroot:/$path\n";
117         transform( $xml, "$opt{tmpl}/doc/toc.xsl", "$opt{docroot}/$path", );
118     }
119
120     ## Generate the chapters
121     my $counter = 0;
122     foreach my $chapter ( map { $_->cloneNode(1) } $xml->findnodes('/book/chapter') ) {
123
124         ## Add a <chapter_id>N</chapter_id> node for the stylesheet to use
125         $chapter->appendTextChild( 'chapter_id', ++$counter );
126
127         ## Add previous/next/canonical urls for nav
128         {
129             $chapter->appendTextChild( 'prev_url',
130                   $counter == 1
131                 ? $type eq 'filter'
132                       ? 'filter.html'
133                       : 'index.html'
134                 : sprintf( '%sch%02d.html', $prepend_chapter, $counter - 1 ) );
135             $chapter->appendTextChild( 'next_url', sprintf( '%sch%02d.html', $prepend_chapter, $counter + 1 ) );
136             $chapter->appendTextChild( 'canonical_url',
137                 sprintf( 'http://www.exim.org/exim-html-current/doc/html/spec_html/%sch%02d.html', $prepend_chapter, $counter ) );
138         }
139
140         ## Create an XML document from the chapter
141         my $doc = XML::LibXML::Document->createDocument( '1.0', 'UTF-8' );
142         $doc->setDocumentElement($chapter);
143
144         ## Transform the chapter into html
145         {
146             my $path = sprintf( 'exim-html-%s/doc/html/spec_html/%sch%02d.html', $version, $prepend_chapter, $counter );
147             print "Generating  : docroot:/$path\n";
148             transform( $doc, "$opt{tmpl}/doc/chapter.xsl", "$opt{docroot}/$path", );
149         }
150     }
151 }
152
153 ## Fixup xref tags
154 sub xref_fixup {
155     my ( $xml, $prepend_chapter ) = @_;
156
157     my %index = ();
158
159     ## Add the "prepend_chapter" info
160     ( $xml->findnodes('/book') )[0]->appendTextChild( 'prepend_chapter', $prepend_chapter );
161
162     ## Iterate over each chapter
163     my $chapter_counter = 0;
164     foreach my $chapter ( $xml->findnodes('/book/chapter') ) {
165         ++$chapter_counter;
166
167         my $chapter_id = $chapter->getAttribute('id');
168         unless ($chapter_id) {    # synthesise missing id
169             $chapter_id = sprintf( 'chapter_noid_%04d', $chapter_counter );
170             $chapter->setAttribute( 'id', $chapter_id );
171         }
172         my $chapter_title = $chapter->findvalue('title');
173
174         $index{$chapter_id} = { chapter_id => $chapter_counter, chapter_title => $chapter_title };
175
176         ## Iterate over each section
177         my $section_counter = 0;
178         foreach my $section ( $chapter->findnodes('section') ) {
179             ++$section_counter;
180
181             my $section_id = $section->getAttribute('id');
182             unless ($section_id) {    # synthesise missing id
183                 $section_id = sprintf( 'section_noid_%04d_%04d', $chapter_counter, $section_counter );
184                 $section->setAttribute( 'id', $section_id );
185             }
186             my $section_title = $section->findvalue('title');
187
188             $index{$section_id} =
189               { chapter_id => $chapter_counter, chapter_title => $chapter_title, section_id => $section_counter };
190         }
191     }
192     ## Build indexes as new chapters
193     build_indexes( $xml, $prepend_chapter, \%index );
194
195     ## Replace all of the xrefs in the XML
196     foreach my $xref ( $xml->findnodes('//xref') ) {
197         my $linkend = $xref->getAttribute('linkend');
198         if ( exists $index{$linkend} ) {
199             $xref->setAttribute( 'chapter_id',    $index{$linkend}{'chapter_id'} );
200             $xref->setAttribute( 'chapter_title', $index{$linkend}{'chapter_title'} );
201             $xref->setAttribute( 'section_id',    $index{$linkend}{'section_id'} ) if $index{$linkend}{'section_id'};
202             $xref->setAttribute( 'url',
203                 sprintf( '%sch%02d.html', $prepend_chapter, $index{$linkend}{'chapter_id'} )
204                   . ( $index{$linkend}{'section_id'} ? '#' . $linkend : '' ) );
205         }
206     }
207 }
208
209 ## Build indexes
210 sub build_indexes {
211     my ( $xml, $prepend_chapter, $xref ) = @_;
212
213     my $index_hash = {};
214     my $current_id;
215     foreach my $node ( $xml->findnodes('//section | //chapter | //indexterm') ) {
216         if ( $node->nodeName eq 'indexterm' ) {
217             my $role      = $node->getAttribute('role') || 'concept';
218             my $primary   = $node->findvalue('child::primary');
219             my $first     = uc( substr( $primary, 0, 1 ) );               # first char
220             my $secondary = $node->findvalue('child::secondary') || '';
221             $index_hash->{$role}{$first}{$primary}{$secondary} ||= [];
222             push @{ $index_hash->{$role}{$first}{$primary}{$secondary} }, $current_id;
223         }
224         else {
225             $current_id = $node->getAttribute('id');
226         }
227     }
228
229     # now we build a set of new chapters with the index data in
230     my $book = ( $xml->findnodes('/book') )[0];
231     foreach my $role ( sort { $a cmp $b } keys %{$index_hash} ) {
232         my $chapter = XML::LibXML::Element->new('chapter');
233         $book->appendChild($chapter);
234         $chapter->setAttribute( 'id', 'index_' . $role );
235         $chapter->appendTextChild( 'title', ( ucfirst($role) . ' Index' ) );
236         foreach my $first ( sort { $a cmp $b } keys %{ $index_hash->{$role} } ) {
237             my $section = XML::LibXML::Element->new('section');
238             my $list    = XML::LibXML::Element->new('itemizedlist');
239             $chapter->appendChild($section);
240             $section->setAttribute( 'id', 'index_' . $role . '_' . $first );
241             $section->appendTextChild( 'title', $first );
242             $section->appendChild($list);
243             foreach my $primary ( sort { $a cmp $b } keys %{ $index_hash->{$role}{$first} } ) {
244                 my $item = XML::LibXML::Element->new('listitem');
245                 my $para = XML::LibXML::Element->new('para');
246                 $list->appendChild($item);
247                 $item->appendChild($para);
248                 $para->appendText($primary);
249                 my $slist;
250                 foreach my $secondary ( sort { $a cmp $b } keys %{ $index_hash->{$role}{$first}{$primary} } ) {
251                     my $spara;
252                     my $sitem;
253                     if ( $secondary eq '' ) {
254                         $spara = $para;    # skip having extra layer of heirarchy
255                     }
256                     else {
257                         unless ($slist) {
258                             $slist = XML::LibXML::Element->new('itemizedlist');
259                             $item->appendChild($slist);
260                         }
261                         $sitem = XML::LibXML::Element->new('listitem');
262                         $spara = XML::LibXML::Element->new('para');
263                         $slist->appendChild($sitem);
264                         $slist->appendChild($spara);
265                         $spara->appendText($secondary);
266                     }
267                     $spara->appendText(': ');
268                     my $count = 0;
269                     foreach my $ref ( @{ $index_hash->{$role}{$first}{$primary}{$secondary} } ) {
270                         $spara->appendText(', ')
271                           if ( $count++ );
272                         my $xrefel = XML::LibXML::Element->new('xref');
273                         $xrefel->setAttribute( linkend => $ref );
274                         $spara->appendChild($xrefel);
275                     }
276                 }
277             }
278         }
279     }
280 }
281
282 ## Handle the transformation
283 sub transform {
284     my ( $xml, $xsl_path, $out_path ) = @_;
285
286     ## Build an empty XML structure if an undefined $xml was passed
287     unless ( defined $xml ) {
288         $xml = XML::LibXML::Document->createDocument( '1.0', 'UTF-8' );
289         $xml->setDocumentElement( $xml->createElement('content') );
290     }
291
292     ## Add the current version of Exim to the XML
293     $xml->documentElement()->appendTextChild( 'current_version', $opt{latest} );
294
295     ## Parse the ".xsl" file as XML
296     my $xsl = XML::LibXML->new()->parse_file($xsl_path) or die $!;
297
298     ## Generate a stylesheet from the ".xsl" XML.
299     my $stylesheet = XML::LibXSLT->new()->parse_stylesheet($xsl);
300
301     ## Generate a doc from the XML transformed with the XSL
302     my $doc = $stylesheet->transform($xml);
303
304     ## Make the containing directory if it doesn't exist
305     mkdirp( ( $out_path =~ /^(.+)\/.+$/ )[0] );
306
307     ## Write out the document
308     open my $out, '>', $out_path or die $!;
309     print $out $stylesheet->output_as_bytes($doc);
310     close $out;
311 }
312
313 ## "mkdir -p "
314 sub mkdirp {
315     my $path = shift;
316
317     my @parts = ();
318     foreach ( split( /\//, $path ) ) {
319         push @parts, $_;
320         my $make = join( '/', @parts );
321         next unless length($make);
322         next if -d $make;
323         mkdir($make) or die "Unable to mkdir $make: $!\n";
324     }
325 }
326
327 ## Parse arguments
328 sub parse_arguments {
329
330     my %opt = ( spec => [], filter => [], help => 0, web => 0, minify => 1 );
331     GetOptions( \%opt, 'help|h!', 'web!', 'spec=s{1,}', 'filter=s{1,}', 'latest=s', 'tmpl=s', 'docroot=s', 'minify!' )
332       || help( 1, 'Bad options' );
333
334     ## --help
335     help(0) if ( $opt{help} );
336
337     ## --spec and --filter lists
338     foreach my $set (qw[spec filter]) {
339         $opt{$set} = [ map { my $f = File::Spec->rel2abs($_); help( 1, 'No such file: ' . $_ ) unless -f $f; $f } @{ $opt{$set} } ];
340     }
341     ## --latest
342     help( 1, 'Missing value for latest' ) unless ( exists( $opt{latest} ) && defined( $opt{latest} ) );
343     help( 1, 'Invalid value for latest' ) unless $opt{latest} =~ /^\d+(?:\.\d+)*$/;
344
345     ## --tmpl and --docroot
346     foreach my $set (qw[tmpl docroot]) {
347         help( 1, 'Missing value for ' . $set ) unless ( exists( $opt{$set} ) && defined( $opt{$set} ) );
348         my $f = File::Spec->rel2abs( $opt{$set} );
349         help( 1, 'No such directory: ' . $opt{$set} ) unless -d $f;
350         $opt{$set} = $f;
351     }
352     help( 1, 'Excess arguments' ) if ( scalar(@ARGV) );
353
354     help( 1, 'Must include at least one of --web, --spec or --filter' )
355       unless ( defined $opt{web} || scalar( @{ $opt{spec} } ) || scalar( @{ $opt{web} } ) );
356
357     return %opt;
358 }
359
360 ## Help information
361 sub help {
362     my ( $exit_code, $msg ) = @_;
363
364     print "$msg\n\n" if defined $msg;
365
366     print << "END_HELP";
367 Options:
368    --help or -h  : Print this help information and then exit
369
370    --web         : Generate the general website pages
371    --spec PATH   : Generate the spec pages. PATH is the path to the spec.xml
372    --filter PATH : Generate the filter pages. PATH is the path to the filter.xml
373
374    One or more of the above three options are required. --spec and --filter can
375    take multiple values to generate different sets of documentation for
376    different versions at the same time.
377
378    --latest VERSION : Required. Specify the latest stable version of Exim.
379    --tmpl PATH      : Required. Path to the templates directory
380    --docroot PATH   : Required. Path to the website document root
381
382    If CSS::Minifier::XS is installed, then CSS will be minified.
383    If JavaScript::Minifier::XS is installed, then JavaScript will be minified.
384
385 Example:
386
387    ./gen.pl --latest 4.72
388             --web
389             --spec spec.xml 4.71/spec.xml
390             --filter filter.xml 4.71/filter.xml
391             --tmpl ~/www/templates
392             --docroot ~/www/docroot
393 END_HELP
394
395     exit($exit_code);
396 }