6 use CSS::Minifier::XS 0.07;
10 use File::Path qw(make_path);
14 use JavaScript::Minifier::XS;
20 my $canonical_url = 'https://www.exim.org/';
23 my %opt = parse_arguments();
25 ## setup static root location
26 ## TODO: for doc generation only this should be within the docs dir
27 $opt{staticroot} = File::Spec->catdir( $opt{docroot}, 'static' );
30 my %cache; # General cache object
31 do_doc( 'spec', $_ ) foreach @{ $opt{spec} || [] };
32 do_doc( 'filter', $_ ) foreach @{ $opt{filter} || [] };
33 do_web() if ( $opt{web} );
34 do_static() if ( $opt{web} or !$opt{localstatic} ); # need this for all other pages generated
36 ## Add the exim-html-current symlink
37 foreach my $type (qw(html pdf)) {
38 print "Symlinking exim-$type-current to exim-$type-$opt{latest}\n" if ( $opt{verbose} );
39 unlink("$opt{docroot}/exim-$type-current");
40 symlink( "exim-$type-$opt{latest}", "$opt{docroot}/exim-$type-current" )
41 || warn "symlink to $opt{docroot}/exim-$type-current failed";
44 # ------------------------------------------------------------------
45 ## Generate the website files
48 ## copy these templates to docroot...
49 copy_transform_files( "$opt{tmpl}/web", $opt{docroot}, 0 );
52 # ------------------------------------------------------------------
53 ## Generate the static file set
55 my $staticroot = shift || $opt{staticroot};
57 ## make sure I have a directory
58 mkdir($staticroot) or die "Unable to make staticroot: $!\n" unless ( -d $staticroot );
60 ## copy these templates to docroot...
61 copy_transform_files( "$opt{tmpl}/static", $staticroot, 1 );
64 # ------------------------------------------------------------------
65 ## Generate the website files
66 sub copy_transform_files {
71 ## Make sure the template web directory exists
72 die "No such directory: $source\n" unless ( -d $source );
74 ## Scan the web templates
77 my ($path) = substr( $File::Find::name, length("$source"), length($File::Find::name) ) =~ m#^/*(.*)$#;
79 if ( -d "$source/$path" ) {
81 ## Create the directory in the target if it doesn't exist
82 if ( !-d "$target/$path" ) {
83 mkdir("$target/$path") or die "Unable to make $target/$path: $!\n";
89 ## Build HTML from XSL files and simply copy static files which have changed
90 if ( ( !$static ) and ( $path =~ /(.+)\.xsl$/ ) ) {
91 print "Generating : /$1.html\n" if ( $opt{verbose} );
92 transform( undef, "$source/$path", "$target/$1.html" );
94 elsif ( -f "$source/$path" ) {
96 ## Skip if the file hasn't changed (mtime/size based)
98 if (( -f "$target/$path" )
99 and ( ( stat("$source/$path") )[9] == ( stat("$target/$path") )[9] )
100 and ( ( stat("$source/$path") )[7] == ( stat("$target/$path") )[7] ) );
102 if ( $path =~ /(.+)\.css$/ ) {
103 print "CSS to : /$path\n" if ( $opt{verbose} );
104 my $content = read_file("$source/$path");
105 write_file( "$target/$path", $opt{minify} ? CSS::Minifier::XS::minify($content) : $content );
107 elsif ( $path =~ /(.+)\.js$/ ) {
108 print "JS to : /$path\n" if ( $opt{verbose} );
109 my $content = read_file("$source/$path");
110 write_file( "$target/$path",
111 $opt{minify} ? JavaScript::Minifier::XS::minify($content) : $content );
115 print "Copying to : /$path\n" if ( $opt{verbose} );
116 copy( "$source/$path", "$target/$path" ) or die "$path: $!";
119 utime( time, ( stat("$source/$path") )[9], "$target/$path" );
128 # ------------------------------------------------------------------
129 ## Generate index/chapter files for a doc
131 my ( $type, $xml_path ) = @_;
133 ## Read and validate the XML file
134 my $xml = XML::LibXML->new(expand_entities => 1)->parse_file($xml_path) or die $!;
136 ## Get the version number
138 my $version = $xml->findvalue('/book/bookinfo/revhistory/revision/revnumber');
139 die "Unable to get version number\n"
140 unless defined $version and $version =~ /^
143 (?:\.\d+(?:\.\d+)?)? # (minor(.patch))
144 (?:\.\d+(?:\.\d+(?:\.\d+)?)?)? # (minor(.patch.(fixes)))
146 (?:-RC\d+)?$/x; # -RCX
150 ## Prepend chapter filenames?
151 my $prepend_chapter = $type eq 'filter' ? 'filter_' : '';
153 ## Add the canonical url for this document
154 $xml->documentElement()
155 ->appendTextChild( 'canonical_url',
156 "${canonical_url}exim-html-current/doc/html/spec_html/" . ( $type eq 'spec' ? 'index' : 'filter' ) . ".html" );
158 ## Add a url for the latest version of this document
159 if ( $version ne $opt{latest} ) {
160 $xml->documentElement()
161 ->appendTextChild( 'current_url',
162 "../../../../exim-html-current/doc/html/spec_html/" . ( $type eq 'spec' ? 'index' : 'filter' ) . ".html" );
166 xref_fixup( $xml, $prepend_chapter );
168 ## set the staticroot
171 ? File::Spec->catdir( $opt{docroot}, "exim-html-$version", 'doc', 'html', 'static' )
173 unless ( -d $staticroot ) {
174 make_path( $staticroot, { verbose => $opt{verbose} } );
175 do_static($staticroot);
178 ## Generate the front page
180 my $path = "exim-html-$version/doc/html/spec_html/" . ( $type eq 'filter' ? $type : 'index' ) . ".html";
181 print "Generating : docroot:/$path\n" if ( $opt{verbose} );
182 transform( $xml, "$opt{tmpl}/doc/index.xsl", "$opt{docroot}/$path", $staticroot );
185 ## Generate a Table of Contents XML file
188 "exim-html-$version/doc/html/spec_html/" . ( $type eq 'filter' ? 'filter_toc' : 'index_toc' ) . ".xml";
189 print "Generating : docroot:/$path\n" if ( $opt{verbose} );
190 transform( $xml, "$opt{tmpl}/doc/toc.xsl", "$opt{docroot}/$path", $staticroot );
193 ## Generate the chapters
195 my @chapters = map { $_->cloneNode(1) } $xml->findnodes('/book/chapter');
196 my( $chapter_title, $chapter_title_prev, $chapter_title_next );
197 foreach my $chapter (@chapters) {
199 ## Add a <chapter_id>N</chapter_id> node for the stylesheet to use
200 $chapter->appendTextChild( 'chapter_id', ++$counter );
202 ## Get the current and surrounding chapter titles
203 $chapter_title_prev = $chapter_title;
204 $chapter_title = $chapter_title_next || $chapter->findvalue('title_uri');
205 $chapter_title_next = $chapters[$counter]->findvalue('title_uri') if $counter < int(@chapters);
207 ## Add previous/next/canonical urls for nav
209 $chapter->appendTextChild( 'prev_url',
214 : sprintf( '%sch-%s.html', $prepend_chapter, $chapter_title_prev ) );
215 $chapter->appendTextChild( 'this_url', sprintf( '%sch-%s.html', $prepend_chapter, $chapter_title ) );
216 $chapter->appendTextChild( 'next_url', sprintf( '%sch-%s.html', $prepend_chapter, $chapter_title_next ) )
217 unless int(@chapters) == $counter;
218 $chapter->appendTextChild( 'toc_url', ( $type eq 'filter' ? 'filter' : 'index' ) . '.html' );
219 $chapter->appendTextChild(
222 'https://www.exim.org/exim-html-current/doc/html/spec_html/%sch-%s.html',
223 $prepend_chapter, $chapter_title
226 if ( $version ne $opt{latest} ) {
227 $chapter->appendTextChild(
230 '../../../../exim-html-current/doc/html/spec_html/%sch-%s.html',
231 $prepend_chapter, $chapter_title
237 ## Create an XML document from the chapter
238 my $doc = XML::LibXML::Document->createDocument( '1.0', 'UTF-8' );
239 $doc->setDocumentElement($chapter);
241 ## Transform the chapter into html
243 my $real_path = sprintf( 'exim-html-%s/doc/html/spec_html/%sch-%s.html', $version, $prepend_chapter, $chapter_title );
244 my $link_path = sprintf( 'exim-html-%s/doc/html/spec_html/%sch%02d.html', $version, $prepend_chapter, $counter );
245 print "Generating : docroot:/$real_path\n" if ( $opt{verbose} );
246 transform( $doc, "$opt{tmpl}/doc/chapter.xsl", "$opt{docroot}/$real_path", $staticroot );
247 # Making a relative symlink to a file in the same directory.
248 # Extract just the filename portion of $real_path.
249 my $real_file = basename($real_path);
250 print "Symlinking : docroot:/$link_path to $real_file\n" if ( $opt{verbose} );
251 if ( -f "$opt{docroot}/$link_path" ) {
252 unlink("$opt{docroot}/$link_path") or die "failed removing $opt{docroot}/$link_path: $!";
254 symlink( "$real_file", "$opt{docroot}/$link_path" ) || die "symlink to $opt{docroot}/$link_path failed: $!";
259 # ------------------------------------------------------------------
262 my ( $xml, $prepend_chapter ) = @_;
266 ## Add the "prepend_chapter" info
267 ( $xml->findnodes('/book') )[0]->appendTextChild( 'prepend_chapter', $prepend_chapter );
269 ## Iterate over each chapter
270 my $chapter_counter = 0;
271 foreach my $chapter ( $xml->findnodes('/book/chapter') ) {
274 my $chapter_id = $chapter->getAttribute('id');
275 unless ($chapter_id) { # synthesise missing id
276 $chapter_id = sprintf( 'chapter_noid_%04d', $chapter_counter );
277 $chapter->setAttribute( 'id', $chapter_id );
279 my $chapter_title = $chapter->findvalue('title');
281 ## Set title_uri so we can use eg ch-introduction.html instead of ch01.html
282 $chapter->appendTextChild( 'title_uri', title_to_uri($chapter_title) );
284 $index{$chapter_id} = { chapter_id => $chapter_counter, chapter_title => $chapter_title };
286 ## Iterate over each section
287 my $section_counter = 0;
288 foreach my $section ( $chapter->findnodes('section') ) {
291 my $section_id = $section->getAttribute('id');
292 unless ($section_id) { # synthesise missing id
293 $section_id = sprintf( 'section_noid_%04d_%04d', $chapter_counter, $section_counter );
294 $section->setAttribute( 'id', $section_id );
296 my $section_title = $section->findvalue('title');
298 $index{$section_id} = {
299 chapter_id => $chapter_counter,
300 chapter_title => $chapter_title,
301 section_id => $section_counter,
302 section_title => $section_title
306 ## Build indexes as new chapters
307 build_indexes( $xml, $prepend_chapter, \%index );
309 ## Replace all of the xrefs in the XML
310 foreach my $xref ( $xml->findnodes('//xref') ) {
311 my $linkend = $xref->getAttribute('linkend');
312 if ( exists $index{$linkend} ) {
313 $xref->setAttribute( 'chapter_id', $index{$linkend}{'chapter_id'} );
314 $xref->setAttribute( 'chapter_title', $index{$linkend}{'chapter_title'} );
315 $xref->setAttribute( 'section_id', $index{$linkend}{'section_id'} ) if ( $index{$linkend}{'section_id'} );
316 $xref->setAttribute( 'section_title', $index{$linkend}{'section_title'} )
317 if ( $index{$linkend}{'section_title'} );
318 $xref->setAttribute( 'url',
319 sprintf( '%sch-%s.html', $prepend_chapter, title_to_uri($index{$linkend}{'chapter_title'}) )
320 . ( $index{$linkend}{'section_id'} ? '#' . $linkend : '' ) );
325 # ------------------------------------------------------------------
328 my ( $xml, $prepend_chapter, $xref ) = @_;
332 foreach my $node ( $xml->findnodes('//section | //chapter | //indexterm') ) {
333 if ( $node->nodeName eq 'indexterm' ) {
334 my $role = $node->getAttribute('role') || 'concept';
335 my $primary = $node->findvalue('child::primary');
336 my $first = ( $primary =~ /^[A-Za-z]/ ) ? uc( substr( $primary, 0, 1 ) ) : ''; # first letter or marker
337 my $secondary = $node->findvalue('child::secondary') || '';
338 my $see = $node->findvalue('child::see');
339 my $see_also = $node->findvalue('child::seealso');
341 next unless ( $primary || $secondary ); # skip blank entries for now...
344 # not perfect; the whole line ends up bold
346 $secondary .= ' see ' . $see;
348 $primary .= ' see ' . $see;
350 } elsif ( $see_also ) {
352 $secondary .= ' see also ' . $see_also;
354 $primary .= ' see also ' . $see_also;
358 $index_hash->{$role}{$first}{$primary}{$secondary} ||= [];
359 next if ( $see || $see_also );
362 # The $current_id being pushed here is presumably the section, given where the
363 # hyperlink end up pointing to. For bug 2889 we'd like to have something more
364 # precise; tha presumably requires an anchor at the indexed point?
366 push @{ $index_hash->{$role}{$first}{$primary}{$secondary} }, $current_id;
369 $current_id = $node->getAttribute('id');
373 # now we build a set of new chapters with the index data in
374 my $book = ( $xml->findnodes('/book') )[0];
375 foreach my $role ( sort { $a cmp $b } keys %{$index_hash} ) {
376 my $chapter = XML::LibXML::Element->new('chapter');
377 $book->appendChild($chapter);
378 $chapter->setAttribute( 'id', join( '_', 'index', $role ) );
379 $chapter->setAttribute( 'class', 'index' );
380 $chapter->appendTextChild( 'title', ( ucfirst($role) . ' Index' ) );
381 $chapter->appendTextChild( 'title_uri', title_to_uri(ucfirst($role) . ' Index') );
383 foreach my $first ( sort { $a cmp $b } keys %{ $index_hash->{$role} } ) {
384 my $section = XML::LibXML::Element->new('section');
385 my $list = XML::LibXML::Element->new('variablelist');
386 $chapter->appendChild($section);
387 $section->setAttribute( 'id', join( '_', 'index', $role, $first ) );
388 $section->setAttribute( 'class', 'index' );
389 $section->appendTextChild( 'title', $first ? $first : 'Symbols' );
390 $section->appendChild($list);
391 foreach my $primary ( sort { $a cmp $b } keys %{ $index_hash->{$role}{$first} } ) {
392 my $entry = XML::LibXML::Element->new('varlistentry');
393 my $item = XML::LibXML::Element->new('listitem');
394 $list->appendChild($entry)->appendTextChild( 'term', $primary );
395 $entry->appendChild($item);
397 foreach my $secondary ( sort { $a cmp $b } keys %{ $index_hash->{$role}{$first}{$primary} } ) {
398 my $para = XML::LibXML::Element->new('para');
399 if ( $secondary eq '' ) {
400 $item->appendChild($para); # skip having extra layer of heirarchy
404 $slist = XML::LibXML::Element->new('variablelist');
405 $item->appendChild($slist);
407 my $sentry = XML::LibXML::Element->new('varlistentry');
408 my $sitem = XML::LibXML::Element->new('listitem');
409 $slist->appendChild($sentry)->appendTextChild( 'term', $secondary );
410 $sentry->appendChild($sitem)->appendChild($para);
413 foreach my $ref ( @{ $index_hash->{$role}{$first}{$primary}{$secondary} } ) {
414 $para->appendText(', ')
416 my $xrefel = XML::LibXML::Element->new('xref');
417 $xrefel->setAttribute( linkend => $ref );
418 $xrefel->setAttribute( longref => 1 );
419 $para->appendChild($xrefel);
427 # ------------------------------------------------------------------
428 ## Handle the transformation
430 my ( $xml, $xsl_path, $out_path, $staticroot_abs ) = @_;
432 ## make sure $staticroot is set
433 $staticroot_abs ||= $opt{staticroot};
435 ## Build an empty XML structure if an undefined $xml was passed
436 unless ( defined $xml ) {
437 $xml = XML::LibXML::Document->createDocument( '1.0', 'UTF-8' );
438 $xml->setDocumentElement( $xml->createElement('content') );
441 ## Add the current version of Exim to the XML
442 $xml->documentElement()->appendTextChild( 'current_version', $opt{latest} );
444 ## Add the old versions of Exim to the XML
445 $xml->documentElement()->appendTextChild( 'old_versions', $_ ) foreach old_docs_versions();
447 ## Parse the ".xsl" file as XML
448 my $xsl = XML::LibXML->new(expand_entities => 1)->parse_file($xsl_path) or die $!;
450 ## Generate a stylesheet from the ".xsl" XML.
451 my $stylesheet = XML::LibXSLT->new()->parse_stylesheet($xsl);
453 ## work out the static root relative to the target
454 my $target_dir = ( File::Spec->splitpath($out_path) )[1];
455 my $staticroot = File::Spec->abs2rel( $staticroot_abs, $target_dir );
457 ## Generate a doc from the XML transformed with the XSL
458 my $doc = $stylesheet->transform( $xml, staticroot => sprintf( "'%s'", $staticroot ) );
460 ## Make the containing directory if it doesn't exist
461 make_path( ( $out_path =~ /^(.+)\/.+$/ )[0], { verbose => $opt{verbose} } );
463 ## Write out the document
464 open my $out, '>', $out_path or die "Unable to write $out_path - $!";
465 print $out $stylesheet->output_as_bytes($doc);
469 # ------------------------------------------------------------------
470 ## Takes a chapter title and fixes it up so it is suitable for use in a URI
472 my $title = lc(shift);
473 $title =~ s/[^a-z0-9\s]+//gi; # Only allow spaces, numbers and letters
474 $title =~ s/\s+/_/g; # Replace spaces with underscores so URLs are easier to copy about
478 # ------------------------------------------------------------------
479 ## Look in the docroot for old versions of the documentation
480 sub old_docs_versions {
481 if ( !exists $cache{old_docs_versions} ) {
483 foreach ( glob("$opt{docroot}/exim-html-*") ) {
484 push @versions, $1 if /-(\d+(?:\.\d+)?)$/ && $1 lt $opt{latest} && -d $_;
486 $cache{old_docs_versions} = [ reverse sort { $a cmp $b } @versions ];
488 return @{ $cache{old_docs_versions} };
491 # ------------------------------------------------------------------
497 pod2usage( -exitval => 1, -verbose => 0 );
500 # ------------------------------------------------------------------
502 sub parse_arguments {
504 my %opt = ( spec => [], filter => [], help => 0, man => 0, web => 0, minify => 1, verbose => 0, localstatic => 0, tmpl => "$Bin/../templates" );
506 \%opt, 'help|h!', 'man!', 'web!', 'spec=s{1,}', 'filter=s{1,}',
507 'latest=s', 'tmpl=s', 'docroot=s', 'minify!', 'verbose!', 'localstatic!'
508 ) || pod2usage( -exitval => 1, -verbose => 0 );
511 pod2usage(0) if ( $opt{help} );
512 pod2usage( -verbose => 2 ) if ( $opt{man} );
514 ## --spec and --filter lists
515 foreach my $set (qw[spec filter]) {
517 [ map { my $f = File::Spec->rel2abs($_); error_help( 'No such file: ' . $_ ) unless -f $f; $f }
521 error_help('Missing value for latest') unless ( exists( $opt{latest} ) && defined( $opt{latest} ) );
522 error_help('Invalid value for latest') unless $opt{latest} =~ /^\d+(?:\.\d+)*$/;
524 ## --tmpl and --docroot
525 foreach my $set (qw[tmpl docroot]) {
526 error_help( 'Missing value for ' . $set ) unless ( exists( $opt{$set} ) && defined( $opt{$set} ) );
527 my $f = File::Spec->rel2abs( $opt{$set} );
528 error_help( 'No such directory: ' . $opt{$set} ) unless -d $f;
531 error_help('Excess arguments') if ( scalar(@ARGV) );
533 error_help('Must include at least one of --web, --spec or --filter')
534 unless ( $opt{web} || scalar( @{ $opt{spec} || [] } ) || scalar( @{ $opt{filter} || [] } ) );
539 # ------------------------------------------------------------------
546 gen - Generate exim html documentation and website
553 --help display this help and exits
554 --man displays man page
555 --spec file... spec docbook/XML source files
556 --filter file... filter docbook/XML source files
557 --web Generate the general website pages
558 --latest VERSION Required. Specify the latest stable version of Exim.
559 --tmpl PATH Required. Path to the templates directory
560 --docroot PATH Required. Path to the website document root
561 --[no-]minify [Don't] minify CSS and Javascript
562 --localstatic Makes the static files local to each doc ver
570 Display help and exits
576 =item B<--spec> I<file...>
578 List of files that make up the specification documentation docbook/XML source
581 =item B<--filter> I<file...>
583 List of files that make up the filter documentation docbook/XML source files.
587 Generate the website from the template files.
589 =item B<--latest> I<version>
591 Specify the current exim version. This is used to create links to the current
594 This option is I<required>
596 =item B<--tmpl> I<directory>
598 Specify the directory that the templates are kept in.
600 This option is I<required>
602 =item B<--docroot> I<directory>
604 Specify the directory that the output should be generated into. This is the
605 website C<docroot> directory.
607 This option is I<required>
611 If this option is set then both the CSS and Javascript files processed are
612 minified using L<CSS::Minifier::XS> and L<JavaScript::Minifier::XS>
615 This option is set by default - to disable it specify C<--no-minify>
617 =item B<--localstatic>
619 Makes the static files (CSS, images etc), local for each version of the
620 documentation. This is more suitable for packaged HTML documentation.
626 Generates the exim website and HTML documentation.
632 --spec docbook/*/spec.xml \
633 --filter docbook/*/filter.xml \
636 --docroot /tmp/website
642 Nigel Metheringham <nigel@exim.org> - mostly broke the framework Mike produced.
646 Copyright 2010-2012 Exim Maintainers. All rights reserved.