X-Git-Url: https://git.exim.org/exim-website.git/blobdiff_plain/f6fb1b4edc6b165cf5e84ce56a7a2efa8e6dc51b..d54be666e66c1211c652e7c7997a9729a5bf2a1f:/script/gen.pl diff --git a/script/gen.pl b/script/gen.pl index 217fdd4..298fb14 100755 --- a/script/gen.pl +++ b/script/gen.pl @@ -20,78 +20,108 @@ my $canonical_url = 'http://www.exim.org/'; ## Parse arguments my %opt = parse_arguments(); +## setup static root location +## TODO: for doc generation only this should be within the docs dir +$opt{staticroot} = File::Spec->catdir( $opt{docroot}, 'static' ); + ## Generate the pages +my %cache; # General cache object do_doc( 'spec', $_ ) foreach @{ $opt{spec} || [] }; do_doc( 'filter', $_ ) foreach @{ $opt{filter} || [] }; -do_web() if exists $opt{web}; +do_web() if ( $opt{web} ); +do_static() if ( $opt{web} or !$opt{localstatic} ); # need this for all other pages generated ## Add the exim-html-current symlink -print "Symlinking exim-html-current to exim-html-$opt{latest}\n"; +print "Symlinking exim-html-current to exim-html-$opt{latest}\n" if ( $opt{verbose} ); unlink("$opt{docroot}/exim-html-current") if ( -l "$opt{docroot}/exim-html-current" ); symlink( "exim-html-$opt{latest}", "$opt{docroot}/exim-html-current" ) || die "symlink to $opt{docroot}/exim-html-current failed"; +# ------------------------------------------------------------------ ## Generate the website files sub do_web { + ## copy these templates to docroot... + copy_transform_files( "$opt{tmpl}/web", $opt{docroot}, 0 ); +} + +# ------------------------------------------------------------------ +## Generate the static file set +sub do_static { + my $staticroot = shift || $opt{staticroot}; + + ## make sure I have a directory + mkdir($staticroot) or die "Unable to make staticroot: $!\n" unless ( -d $staticroot ); + + ## copy these templates to docroot... + copy_transform_files( "$opt{tmpl}/static", $staticroot, 1 ); +} + +# ------------------------------------------------------------------ +## Generate the website files +sub copy_transform_files { + my $source = shift; + my $target = shift; + my $static = shift; + ## Make sure the template web directory exists - die "No such directory: $opt{tmpl}/web\n" unless -d "$opt{tmpl}/web"; + die "No such directory: $source\n" unless ( -d $source ); ## Scan the web templates find( sub { - my ($path) = - substr( $File::Find::name, length("$opt{tmpl}/web"), length($File::Find::name) ) =~ m#^/*(.*)$#; + my ($path) = substr( $File::Find::name, length("$source"), length($File::Find::name) ) =~ m#^/*(.*)$#; - if ( -d "$opt{tmpl}/web/$path" ) { + if ( -d "$source/$path" ) { - ## Create the directory in the doc root if it doesn't exist - if ( !-d "$opt{docroot}/$path" ) { - mkdir("$opt{docroot}/$path") or die "Unable to make $opt{docroot}/$path: $!\n"; + ## Create the directory in the target if it doesn't exist + if ( !-d "$target/$path" ) { + mkdir("$target/$path") or die "Unable to make $target/$path: $!\n"; } } else { ## Build HTML from XSL files and simply copy static files which have changed - if ( $path =~ /(.+)\.xsl$/ ) { - print "Generating : docroot:/$1.html\n" if ( $opt{verbose} ); - transform( undef, "$opt{tmpl}/web/$path", "$opt{docroot}/$1.html" ); + if ( ( !$static ) and ( $path =~ /(.+)\.xsl$/ ) ) { + print "Generating : /$1.html\n" if ( $opt{verbose} ); + transform( undef, "$source/$path", "$target/$1.html" ); } - elsif ( -f "$opt{tmpl}/web/$path" ) { + elsif ( -f "$source/$path" ) { - ## Skip if the file hasn't changed (mtime based) + ## Skip if the file hasn't changed (mtime/size based) return - if -f "$opt{docroot}/$path" - && ( stat("$opt{tmpl}/web/$path") )[9] == ( stat("$opt{docroot}/$path") )[9]; + if (( -f "$target/$path" ) + and ( ( stat("$source/$path") )[9] == ( stat("$target/$path") )[9] ) + and ( ( stat("$source/$path") )[7] == ( stat("$target/$path") )[7] ) ); if ( $path =~ /(.+)\.css$/ ) { - print "CSS to : docroot:/$path\n" if ( $opt{verbose} ); - my $content = read_file("$opt{tmpl}/web/$path"); - write_file( "$opt{docroot}/$path", - $opt{minify} ? CSS::Minifier::XS::minify($content) : $content ); + print "CSS to : /$path\n" if ( $opt{verbose} ); + my $content = read_file("$source/$path"); + write_file( "$target/$path", $opt{minify} ? CSS::Minifier::XS::minify($content) : $content ); } elsif ( $path =~ /(.+)\.js$/ ) { - print "JS to : docroot:/$path\n" if ( $opt{verbose} ); - my $content = read_file("$opt{tmpl}/web/$path"); - write_file( "$opt{docroot}/$path", + print "JS to : /$path\n" if ( $opt{verbose} ); + my $content = read_file("$source/$path"); + write_file( "$target/$path", $opt{minify} ? JavaScript::Minifier::XS::minify($content) : $content ); } else { ## Copy - print "Copying to : docroot:/$path\n" if ( $opt{verbose} ); - copy( "$opt{tmpl}/web/$path", "$opt{docroot}/$path" ) or die "$path: $!"; + print "Copying to : /$path\n" if ( $opt{verbose} ); + copy( "$source/$path", "$target/$path" ) or die "$path: $!"; } ## Set mtime - utime( time, ( stat("$opt{tmpl}/web/$path") )[9], "$opt{docroot}/$path" ); + utime( time, ( stat("$source/$path") )[9], "$target/$path" ); } } }, - "$opt{tmpl}/web" + "$source" ); } +# ------------------------------------------------------------------ ## Generate index/chapter files for a doc sub do_doc { my ( $type, $xml_path ) = @_; @@ -111,14 +141,31 @@ sub do_doc { ->appendTextChild( 'canonical_url', "${canonical_url}exim-html-current/doc/html/spec_html/" . ( $type eq 'spec' ? 'index' : 'filter' ) . ".html" ); + ## Add a url for the latest version of this document + if ( $version ne $opt{latest} ) { + $xml->documentElement() + ->appendTextChild( 'current_url', + "../../../../exim-html-current/doc/html/spec_html/" . ( $type eq 'spec' ? 'index' : 'filter' ) . ".html" ); + } + ## Fixup the XML xref_fixup( $xml, $prepend_chapter ); + ## set the staticroot + my $staticroot = + $opt{localstatic} + ? File::Spec->catdir( $opt{docroot}, "exim-html-$version", 'doc', 'html', 'static' ) + : $opt{staticroot}; + unless ( -d $staticroot ) { + make_path( $staticroot, { verbose => $opt{verbose} } ); + do_static($staticroot); + } + ## Generate the front page { my $path = "exim-html-$version/doc/html/spec_html/" . ( $type eq 'filter' ? $type : 'index' ) . ".html"; - print "Generating : docroot:/$path\n"; - transform( $xml, "$opt{tmpl}/doc/index.xsl", "$opt{docroot}/$path", ); + print "Generating : docroot:/$path\n" if ( $opt{verbose} ); + transform( $xml, "$opt{tmpl}/doc/index.xsl", "$opt{docroot}/$path", $staticroot ); } ## Generate a Table of Contents XML file @@ -126,12 +173,13 @@ sub do_doc { my $path = "exim-html-$version/doc/html/spec_html/" . ( $type eq 'filter' ? 'filter_toc' : 'index_toc' ) . ".xml"; print "Generating : docroot:/$path\n" if ( $opt{verbose} ); - transform( $xml, "$opt{tmpl}/doc/toc.xsl", "$opt{docroot}/$path", ); + transform( $xml, "$opt{tmpl}/doc/toc.xsl", "$opt{docroot}/$path", $staticroot ); } ## Generate the chapters my $counter = 0; - foreach my $chapter ( map { $_->cloneNode(1) } $xml->findnodes('/book/chapter') ) { + my @chapters = map { $_->cloneNode(1) } $xml->findnodes('/book/chapter'); + foreach my $chapter (@chapters) { ## Add a N node for the stylesheet to use $chapter->appendTextChild( 'chapter_id', ++$counter ); @@ -144,7 +192,9 @@ sub do_doc { ? 'filter.html' : 'index.html' : sprintf( '%sch%02d.html', $prepend_chapter, $counter - 1 ) ); - $chapter->appendTextChild( 'next_url', sprintf( '%sch%02d.html', $prepend_chapter, $counter + 1 ) ); + $chapter->appendTextChild( 'next_url', sprintf( '%sch%02d.html', $prepend_chapter, $counter + 1 ) ) + unless int(@chapters) == $counter; + $chapter->appendTextChild( 'toc_url', ( $type eq 'filter' ? 'filter' : 'index' ) . '.html' ); $chapter->appendTextChild( 'canonical_url', sprintf( @@ -152,6 +202,15 @@ sub do_doc { $prepend_chapter, $counter ) ); + if ( $version ne $opt{latest} ) { + $chapter->appendTextChild( + 'current_url', + sprintf( + '../../../../exim-html-current/doc/html/spec_html/%sch%02d.html', + $prepend_chapter, $counter + ) + ); + } } ## Create an XML document from the chapter @@ -162,11 +221,12 @@ sub do_doc { { my $path = sprintf( 'exim-html-%s/doc/html/spec_html/%sch%02d.html', $version, $prepend_chapter, $counter ); print "Generating : docroot:/$path\n" if ( $opt{verbose} ); - transform( $doc, "$opt{tmpl}/doc/chapter.xsl", "$opt{docroot}/$path", ); + transform( $doc, "$opt{tmpl}/doc/chapter.xsl", "$opt{docroot}/$path", $staticroot ); } } } +# ------------------------------------------------------------------ ## Fixup xref tags sub xref_fixup { my ( $xml, $prepend_chapter ) = @_; @@ -229,6 +289,7 @@ sub xref_fixup { } } +# ------------------------------------------------------------------ ## Build indexes sub build_indexes { my ( $xml, $prepend_chapter, $xref ) = @_; @@ -302,9 +363,13 @@ sub build_indexes { } } +# ------------------------------------------------------------------ ## Handle the transformation sub transform { - my ( $xml, $xsl_path, $out_path ) = @_; + my ( $xml, $xsl_path, $out_path, $staticroot_abs ) = @_; + + ## make sure $staticroot is set + $staticroot_abs ||= $opt{staticroot}; ## Build an empty XML structure if an undefined $xml was passed unless ( defined $xml ) { @@ -315,17 +380,24 @@ sub transform { ## Add the current version of Exim to the XML $xml->documentElement()->appendTextChild( 'current_version', $opt{latest} ); + ## Add the old versions of Exim to the XML + $xml->documentElement()->appendTextChild( 'old_versions', $_ ) foreach old_docs_versions(); + ## Parse the ".xsl" file as XML my $xsl = XML::LibXML->new()->parse_file($xsl_path) or die $!; ## Generate a stylesheet from the ".xsl" XML. my $stylesheet = XML::LibXSLT->new()->parse_stylesheet($xsl); + ## work out the static root relative to the target + my $target_dir = ( File::Spec->splitpath($out_path) )[1]; + my $staticroot = File::Spec->abs2rel( $staticroot_abs, $target_dir ); + ## Generate a doc from the XML transformed with the XSL - my $doc = $stylesheet->transform($xml); + my $doc = $stylesheet->transform( $xml, staticroot => sprintf( "'%s'", $staticroot ) ); ## Make the containing directory if it doesn't exist - make_path( ( $out_path =~ /^(.+)\/.+$/ )[0], { verbose => 1 } ); + make_path( ( $out_path =~ /^(.+)\/.+$/ )[0], { verbose => $opt{verbose} } ); ## Write out the document open my $out, '>', $out_path or die "Unable to write $out_path - $!"; @@ -333,6 +405,20 @@ sub transform { close $out; } +# ------------------------------------------------------------------ +## Look in the docroot for old versions of the documentation +sub old_docs_versions { + if ( !exists $cache{old_docs_versions} ) { + my @versions; + foreach ( glob("$opt{docroot}/exim-html-*") ) { + push @versions, $1 if /-(\d+(?:\.\d+)?)$/ && $1 lt $opt{latest} && -d $_; + } + $cache{old_docs_versions} = [ reverse sort { $a cmp $b } @versions ]; + } + return @{ $cache{old_docs_versions} }; +} + +# ------------------------------------------------------------------ ## error_help sub error_help { my $msg = shift; @@ -341,13 +427,14 @@ sub error_help { pod2usage( -exitval => 1, -verbose => 0 ); } +# ------------------------------------------------------------------ ## Parse arguments sub parse_arguments { - my %opt = ( spec => [], filter => [], help => 0, man => 0, web => 0, minify => 1, verbose => 0 ); + my %opt = ( spec => [], filter => [], help => 0, man => 0, web => 0, minify => 1, verbose => 0, localstatic => 0 ); GetOptions( \%opt, 'help|h!', 'man!', 'web!', 'spec=s{1,}', 'filter=s{1,}', - 'latest=s', 'tmpl=s', 'docroot=s', 'minify!', 'verbose!' + 'latest=s', 'tmpl=s', 'docroot=s', 'minify!', 'verbose!', 'localstatic!' ) || pod2usage( -exitval => 1, -verbose => 0 ); ## --help @@ -357,7 +444,7 @@ sub parse_arguments { ## --spec and --filter lists foreach my $set (qw[spec filter]) { $opt{$set} = - [ map { my $f = File::Spec->rel2abs($_); help( 1, 'No such file: ' . $_ ) unless -f $f; $f } + [ map { my $f = File::Spec->rel2abs($_); error_help( 1, 'No such file: ' . $_ ) unless -f $f; $f } @{ $opt{$set} } ]; } ## --latest @@ -379,6 +466,7 @@ sub parse_arguments { return %opt; } +# ------------------------------------------------------------------ 1; __END__ @@ -400,7 +488,8 @@ gen.pl [options] --latest VERSION Required. Specify the latest stable version of Exim. --tmpl PATH Required. Path to the templates directory --docroot PATH Required. Path to the website document root - --[no-]minify [Don't] minify CSS and Javascript + --[no-]minify [Don't] minify CSS and Javascript + --localstatic Makes the static files local to each doc ver =head1 OPTIONS @@ -416,13 +505,12 @@ Display man page =item B<--spec> I -List of files that make up the specification documentation -docbook/XML source files. +List of files that make up the specification documentation docbook/XML source +files. =item B<--filter> I -List of files that make up the filter documentation docbook/XML -source files. +List of files that make up the filter documentation docbook/XML source files. =item B<--web> @@ -430,8 +518,8 @@ Generate the website from the template files. =item B<--latest> I -Specify the current exim version. This is used to create links to -the current documentation. +Specify the current exim version. This is used to create links to the current +documentation. This option is I @@ -443,19 +531,24 @@ This option is I =item B<--docroot> I -Specify the directory that the output should be generated into. -This is the website C directory. +Specify the directory that the output should be generated into. This is the +website C directory. This option is I =item B<--minify> -If this option is set then both the CSS and Javascript files -processed are minified using L and -L respectively. +If this option is set then both the CSS and Javascript files processed are +minified using L and L +respectively. This option is set by default - to disable it specify C<--no-minify> +=item B<--localstatic> + +Makes the static files (CSS, images etc), local for each version of the +documentation. This is more suitable for packaged HTML documentation. + =back =head1 DESCRIPTION @@ -476,11 +569,10 @@ Generates the exim website and HTML documentation. Mike Cardwell -Nigel Metheringham - mostly broke the framework -Mike produced. +Nigel Metheringham - mostly broke the framework Mike produced. =head1 COPYRIGHT -Copyright 2010 Exim Maintainers. All rights reserved. +Copyright 2010-2012 Exim Maintainers. All rights reserved. =cut