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