X-Git-Url: https://git.exim.org/exim-website.git/blobdiff_plain/7dbb215136b6b2471b40b55e3f285935df110224..0fba8083c852ef0f76862cb91f03b12e496dde6c:/script/gen.pl?ds=sidebyside diff --git a/script/gen.pl b/script/gen.pl index 82ab224..882e385 100755 --- a/script/gen.pl +++ b/script/gen.pl @@ -1,11 +1,13 @@ -#!/usr/bin/perl +#!/usr/bin/env perl # use strict; use warnings; use CSS::Minifier::XS 0.07; +use File::Basename; use File::Copy; use File::Find; +use File::Path qw(make_path); use File::Slurp; use File::Spec; use Getopt::Long; @@ -19,73 +21,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( "$opt{docroot}/exim-html-$opt{latest}", "$opt{docroot}/exim-html-current" ) - || die "symlink to $opt{docroot}/exim-html-current failed"; +symlink( "exim-html-$opt{latest}", "$opt{docroot}/exim-html-current" ) + || warn "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"; - 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) - return if -f "$opt{docroot}/$path" && ( stat("$opt{tmpl}/web/$path") )[9] == ( stat("$opt{docroot}/$path") )[9]; + ## Skip if the file hasn't changed (mtime/size based) + return + 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"; - 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"; - my $content = read_file("$opt{tmpl}/web/$path"); - write_file( "$opt{docroot}/$path", $opt{minify} ? JavaScript::Minifier::XS::minify($content) : $content ); + 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"; - 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 ) = @_; @@ -102,44 +139,86 @@ sub do_doc { ## Add the canonical url for this document $xml->documentElement() - ->appendTextChild( 'canonical_url', + ->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 { - my $path = "exim-html-$version/doc/html/spec_html/" . ( $type eq 'filter' ? 'filter_toc' : 'index_toc' ) . ".xml"; - print "Generating : docroot:/$path\n"; - transform( $xml, "$opt{tmpl}/doc/toc.xsl", "$opt{docroot}/$path", ); + 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", $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'); + my( $chapter_title, $chapter_title_prev, $chapter_title_next ); + foreach my $chapter (@chapters) { ## Add a N node for the stylesheet to use $chapter->appendTextChild( 'chapter_id', ++$counter ); + ## Get the current and surrounding chapter titles + $chapter_title_prev = $chapter_title; + $chapter_title = $chapter_title_next || $chapter->findvalue('title_uri'); + $chapter_title_next = $chapters[$counter]->findvalue('title_uri') if $counter < int(@chapters); + ## Add previous/next/canonical urls for nav { $chapter->appendTextChild( 'prev_url', $counter == 1 ? $type eq 'filter' - ? '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( 'canonical_url', - sprintf( 'http://www.exim.org/exim-html-current/doc/html/spec_html/%sch%02d.html', $prepend_chapter, $counter ) ); + ? 'filter.html' + : 'index.html' + : sprintf( '%sch-%s.html', $prepend_chapter, $chapter_title_prev ) ); + $chapter->appendTextChild( 'this_url', sprintf( '%sch-%s.html', $prepend_chapter, $chapter_title ) ); + $chapter->appendTextChild( 'next_url', sprintf( '%sch-%s.html', $prepend_chapter, $chapter_title_next ) ) + unless int(@chapters) == $counter; + $chapter->appendTextChild( 'toc_url', ( $type eq 'filter' ? 'filter' : 'index' ) . '.html' ); + $chapter->appendTextChild( + 'canonical_url', + sprintf( + 'http://www.exim.org/exim-html-current/doc/html/spec_html/%sch-%s.html', + $prepend_chapter, $chapter_title + ) + ); + if ( $version ne $opt{latest} ) { + $chapter->appendTextChild( + 'current_url', + sprintf( + '../../../../exim-html-current/doc/html/spec_html/%sch-%s.html', + $prepend_chapter, $chapter_title + ) + ); + } } ## Create an XML document from the chapter @@ -148,13 +227,23 @@ sub do_doc { ## Transform the chapter into html { - my $path = sprintf( 'exim-html-%s/doc/html/spec_html/%sch%02d.html', $version, $prepend_chapter, $counter ); - print "Generating : docroot:/$path\n"; - transform( $doc, "$opt{tmpl}/doc/chapter.xsl", "$opt{docroot}/$path", ); + my $real_path = sprintf( 'exim-html-%s/doc/html/spec_html/%sch-%s.html', $version, $prepend_chapter, $chapter_title ); + my $link_path = sprintf( 'exim-html-%s/doc/html/spec_html/%sch%02d.html', $version, $prepend_chapter, $counter ); + print "Generating : docroot:/$real_path\n" if ( $opt{verbose} ); + transform( $doc, "$opt{tmpl}/doc/chapter.xsl", "$opt{docroot}/$real_path", $staticroot ); + # Making a relative symlink to a file in the same directory. + # Extract just the filename portion of $real_path. + my $real_file = basename($real_path); + print "Symlinking : docroot:/$link_path to $real_file\n" if ( $opt{verbose} ); + if ( -f "$opt{docroot}/$link_path" ) { + unlink("$opt{docroot}/$link_path") or die "failed removing $opt{docroot}/$link_path: $!"; + } + symlink( "$real_file", "$opt{docroot}/$link_path" ) || die "symlink to $opt{docroot}/$link_path failed: $!"; } } } +# ------------------------------------------------------------------ ## Fixup xref tags sub xref_fixup { my ( $xml, $prepend_chapter ) = @_; @@ -176,6 +265,9 @@ sub xref_fixup { } my $chapter_title = $chapter->findvalue('title'); + ## Set title_uri so we can use eg ch-introduction.html instead of ch01.html + $chapter->appendTextChild( 'title_uri', title_to_uri($chapter_title) ); + $index{$chapter_id} = { chapter_id => $chapter_counter, chapter_title => $chapter_title }; ## Iterate over each section @@ -207,15 +299,17 @@ sub xref_fixup { if ( exists $index{$linkend} ) { $xref->setAttribute( 'chapter_id', $index{$linkend}{'chapter_id'} ); $xref->setAttribute( 'chapter_title', $index{$linkend}{'chapter_title'} ); - $xref->setAttribute( 'section_id', $index{$linkend}{'section_id'} ) if ( $index{$linkend}{'section_id'} ); - $xref->setAttribute( 'section_title', $index{$linkend}{'section_title'} ) if ( $index{$linkend}{'section_title'} ); + $xref->setAttribute( 'section_id', $index{$linkend}{'section_id'} ) if ( $index{$linkend}{'section_id'} ); + $xref->setAttribute( 'section_title', $index{$linkend}{'section_title'} ) + if ( $index{$linkend}{'section_title'} ); $xref->setAttribute( 'url', - sprintf( '%sch%02d.html', $prepend_chapter, $index{$linkend}{'chapter_id'} ) - . ( $index{$linkend}{'section_id'} ? '#' . $linkend : '' ) ); + sprintf( '%sch-%s.html', $prepend_chapter, title_to_uri($index{$linkend}{'chapter_title'}) ) + . ( $index{$linkend}{'section_id'} ? '#' . $linkend : '' ) ); } } } +# ------------------------------------------------------------------ ## Build indexes sub build_indexes { my ( $xml, $prepend_chapter, $xref ) = @_; @@ -226,9 +320,9 @@ sub build_indexes { if ( $node->nodeName eq 'indexterm' ) { my $role = $node->getAttribute('role') || 'concept'; my $primary = $node->findvalue('child::primary'); - my $first = ( $primary =~ /^[A-Za-z]/ ) ? uc( substr( $primary, 0, 1 ) ) : ''; # first letter or marker + my $first = ( $primary =~ /^[A-Za-z]/ ) ? uc( substr( $primary, 0, 1 ) ) : ''; # first letter or marker my $secondary = $node->findvalue('child::secondary') || ''; - next unless ( $primary || $secondary ); # skip blank entries for now... + next unless ( $primary || $secondary ); # skip blank entries for now... $index_hash->{$role}{$first}{$primary}{$secondary} ||= []; push @{ $index_hash->{$role}{$first}{$primary}{$secondary} }, $current_id; } @@ -245,6 +339,8 @@ sub build_indexes { $chapter->setAttribute( 'id', join( '_', 'index', $role ) ); $chapter->setAttribute( 'class', 'index' ); $chapter->appendTextChild( 'title', ( ucfirst($role) . ' Index' ) ); + $chapter->appendTextChild( 'title_uri', title_to_uri(ucfirst($role) . ' Index') ); + foreach my $first ( sort { $a cmp $b } keys %{ $index_hash->{$role} } ) { my $section = XML::LibXML::Element->new('section'); my $list = XML::LibXML::Element->new('variablelist'); @@ -277,7 +373,7 @@ sub build_indexes { my $count = 0; foreach my $ref ( @{ $index_hash->{$role}{$first}{$primary}{$secondary} } ) { $para->appendText(', ') - if ( $count++ ); + if ( $count++ ); my $xrefel = XML::LibXML::Element->new('xref'); $xrefel->setAttribute( linkend => $ref ); $xrefel->setAttribute( longref => 1 ); @@ -289,9 +385,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 ) { @@ -302,17 +402,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 - mkdirp( ( $out_path =~ /^(.+)\/.+$/ )[0] ); + make_path( ( $out_path =~ /^(.+)\/.+$/ )[0], { verbose => $opt{verbose} } ); ## Write out the document open my $out, '>', $out_path or die "Unable to write $out_path - $!"; @@ -320,20 +427,29 @@ sub transform { close $out; } -## "mkdir -p " -sub mkdirp { - my $path = shift; - - my @parts = (); - foreach ( split( /\//, $path ) ) { - push @parts, $_; - my $make = join( '/', @parts ); - next unless length($make); - next if -d $make; - mkdir($make) or die "Unable to mkdir $make: $!\n"; +# ------------------------------------------------------------------ +## Takes a chapter title and fixes it up so it is suitable for use in a URI +sub title_to_uri { + my $title = lc(shift); + $title =~ s/[^a-z0-9\s]+//gi; # Only allow spaces, numbers and letters + $title =~ s/\s+/_/g; # Replace spaces with underscores so URLs are easier to copy about + return $title; +} + +# ------------------------------------------------------------------ +## 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; @@ -342,12 +458,15 @@ 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 ); - GetOptions( \%opt, 'help|h!', 'man!', 'web!', 'spec=s{1,}', 'filter=s{1,}', 'latest=s', 'tmpl=s', 'docroot=s', 'minify!' ) - || pod2usage( -exitval => 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!', 'localstatic!' + ) || pod2usage( -exitval => 1, -verbose => 0 ); ## --help pod2usage(0) if ( $opt{help} ); @@ -355,7 +474,9 @@ 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 } @{ $opt{$set} } ]; + $opt{$set} = + [ map { my $f = File::Spec->rel2abs($_); error_help( 'No such file: ' . $_ ) unless -f $f; $f } + @{ $opt{$set} } ]; } ## --latest error_help('Missing value for latest') unless ( exists( $opt{latest} ) && defined( $opt{latest} ) ); @@ -371,11 +492,12 @@ sub parse_arguments { error_help('Excess arguments') if ( scalar(@ARGV) ); error_help('Must include at least one of --web, --spec or --filter') - unless ( $opt{web} || scalar( @{ $opt{spec} || [] } ) || scalar( @{ $opt{filter} || [] } ) ); + unless ( $opt{web} || scalar( @{ $opt{spec} || [] } ) || scalar( @{ $opt{filter} || [] } ) ); return %opt; } +# ------------------------------------------------------------------ 1; __END__ @@ -397,7 +519,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 @@ -413,13 +536,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> @@ -427,8 +549,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 @@ -440,19 +562,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 @@ -473,12 +600,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 -