From 080ad9f4f6bf572e773458911d3c57e7192aadaa Mon Sep 17 00:00:00 2001 From: Mike Cardwell Date: Thu, 6 Dec 2012 16:13:40 +0000 Subject: [PATCH] Navigation updates and fixes --- script/gen.pl | 47 +++++++++++++++++++++++++------- templates/doc/chapter.xsl | 4 +-- templates/doc/index.xsl | 9 +----- templates/doc/toc.xsl | 9 +----- templates/static/doc/chapter.css | 5 ++-- templates/static/doc/chapter.js | 16 +++++++++++ 6 files changed, 59 insertions(+), 31 deletions(-) diff --git a/script/gen.pl b/script/gen.pl index 298fb14..fa0cc7e 100755 --- a/script/gen.pl +++ b/script/gen.pl @@ -179,11 +179,17 @@ sub do_doc { ## Generate the chapters my $counter = 0; 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', @@ -191,23 +197,24 @@ sub do_doc { ? $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 ) ) + : 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%02d.html', - $prepend_chapter, $counter + '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%02d.html', - $prepend_chapter, $counter + '../../../../exim-html-current/doc/html/spec_html/%sch-%s.html', + $prepend_chapter, $chapter_title ) ); } @@ -219,9 +226,15 @@ 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" if ( $opt{verbose} ); - transform( $doc, "$opt{tmpl}/doc/chapter.xsl", "$opt{docroot}/$path", $staticroot ); + 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 ); + print "Symlinking : docroot:/$link_path to docroot:$real_path\n" if ( $opt{verbose} ); + if ( -f "$opt{docroot}/$link_path" ) { + unlink("$opt{docroot}/$link_path") or die "failed removing $opt{docroot}/$link_path: $!"; + } + symlink( "$opt{docroot}/$real_path", "$opt{docroot}/$link_path" ) || die "symlink to $opt{docroot}/$link_path failed: $!"; } } } @@ -248,6 +261,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 @@ -283,7 +299,7 @@ sub xref_fixup { $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'} ) + sprintf( '%sch-%s.html', $prepend_chapter, title_to_uri($index{$linkend}{'chapter_title'}) ) . ( $index{$linkend}{'section_id'} ? '#' . $linkend : '' ) ); } } @@ -319,6 +335,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'); @@ -405,6 +423,15 @@ sub transform { close $out; } +# ------------------------------------------------------------------ +## 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 { diff --git a/templates/doc/chapter.xsl b/templates/doc/chapter.xsl index 0b0bc06..6430eee 100644 --- a/templates/doc/chapter.xsl +++ b/templates/doc/chapter.xsl @@ -60,7 +60,7 @@

- +

@@ -72,7 +72,7 @@ - + ]]> diff --git a/templates/doc/index.xsl b/templates/doc/index.xsl index 6237269..751f83f 100644 --- a/templates/doc/index.xsl +++ b/templates/doc/index.xsl @@ -75,14 +75,7 @@ - - - - - - - - + diff --git a/templates/doc/toc.xsl b/templates/doc/toc.xsl index 31d7bc1..f118bff 100644 --- a/templates/doc/toc.xsl +++ b/templates/doc/toc.xsl @@ -20,14 +20,7 @@ - - - - - - - - + diff --git a/templates/static/doc/chapter.css b/templates/static/doc/chapter.css index 9f9b22e..74c0086 100644 --- a/templates/static/doc/chapter.css +++ b/templates/static/doc/chapter.css @@ -49,9 +49,8 @@ body.no-js #old_version_warning span.closebar { .toc_page { position: absolute; - right: 13em; - left: 13em; - text-align: center; + width: 10em; + left: 45%; } #chapter { diff --git a/templates/static/doc/chapter.js b/templates/static/doc/chapter.js index add4bd3..45bb4af 100644 --- a/templates/static/doc/chapter.js +++ b/templates/static/doc/chapter.js @@ -1,3 +1,19 @@ +// Rewrite chapter urls using the canonical name. e.g ch01.html becomes introduction.html +(function ($) { + if (document.location.pathname.match(/\/ch\d+\.html$/)) { + var url = document.location.href; + var canonical = $('link[rel="canonical"]').attr('href'); + if (canonical) { + canonical = canonical.replace(/^[^#]+(\/[^\/#]+).*/,'$1'); + url = url.replace(/\/ch\d+\.html/, canonical); + if ("history" in window && "replaceState" in window.history) + window.history.replaceState("", document.title, url); + else + document.location.href = url; + } + } +})(jQuery); + // Warnings about reading old version of documentation (function ($) { if( $.grep( document.cookie.split(/\s*;\s*/), function(a){return a === 'old_version_warning_removed=true' ? true : false }).length === 0 ){ -- 2.30.2