svn commit - mysqldoc@docsrva: r7738 - in trunk: . make.d mysqltest tools

[paul]

Author: paul
Date: 2007-09-06 21:16:04 +0200 (Thu, 06 Sep 2007)
New Revision: 7738

Log:
 r29982@polar:  paul | 2007-09-06 14:15:29 -0500
 First crack at script that generates error pages for expired
 node remappings. This will need tweaking.


Added:
   trunk/tools/map-expired-nodes.pl
Modified:
   trunk/make.d/vars-docbook
   trunk/make.d/xml-html-web
   trunk/mysqltest/renamed-nodes.txt

Property changes on: trunk
___________________________________________________________________
Name: svk:merge
   - 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:29979
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:24623
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:20005
   + 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:29982
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:24623
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:20005

Property changes on: trunk/tools/map-expired-nodes.pl
___________________________________________________________________
Name: svn:executable
   + *


Modified: trunk/make.d/vars-docbook
===================================================================
--- trunk/make.d/vars-docbook	2007-09-06 18:16:10 UTC (rev 7737)
+++ trunk/make.d/vars-docbook	2007-09-06 19:16:04 UTC (rev 7738)
Changed blocks: 1, Lines Added: 4, Lines Deleted: 0; 497 bytes

@@ -200,6 +200,10 @@
 
 PREP_FOR_CHM = $(TOOLS_DIR)/prep-for-chm.pl
 
+# Script that maps expired old-name/new-name redirections
+
+MAP_EXPIRED_NODES = $(TOOLS_DIR)/map-expired-nodes.pl
+
 # ----------------------------------------------------------------------
 # Transforms
 


Modified: trunk/make.d/xml-html-web
===================================================================
--- trunk/make.d/xml-html-web	2007-09-06 18:16:10 UTC (rev 7737)
+++ trunk/make.d/xml-html-web	2007-09-06 19:16:04 UTC (rev 7738)
Changed blocks: 1, Lines Added: 5, Lines Deleted: 1; 578 bytes

@@ -32,7 +32,11 @@
 	cat $@-tmp/*.html | openssl dgst -md5 > $@-tmp/checksum.txt
 	set -e; \
 	if [ -f renamed-nodes.txt ]; then \
-		cp renamed-nodes.txt $@-tmp/ ; \
+		$(MAP_EXPIRED_NODES) \
+			--doc-lang=$(DOC_LANG) \
+			--doc-name=$(MAIN_DOC_BASENAME) \
+			--output-dir=$@-tmp \
+			renamed-nodes.txt > $@-tmp/renamed-nodes.txt ; \
 	fi
 	mv $@-tmp $@
 


Modified: trunk/mysqltest/renamed-nodes.txt
===================================================================
--- trunk/mysqltest/renamed-nodes.txt	2007-09-06 18:16:10 UTC (rev 7737)
+++ trunk/mysqltest/renamed-nodes.txt	2007-09-06 19:16:04 UTC (rev 7738)
Changed blocks: 1, Lines Added: 10, Lines Deleted: 0; 718 bytes

@@ -19,3 +19,13 @@
 # comments and ignored.
 #
 mysql-test-run mysql-test-run-pl
+
+# Test non-expired redirections to local page, external page, URL
+redirect-a mysql-test-run-pl 2008-01-01
+redirect-b ../../4.1/en/charset-map 2008-01-01
+redirect-c http://dev.mysql.com 2008-01-01
+
+# Test expired redirections to local page, external page, URL
+expired-a mysql-test-run-pl 2007-01-01
+expired-b ../../4.1/en/charset-map 2007-01-01
+expired-c http://dev.mysql.com 2007-01-01


Added: trunk/tools/map-expired-nodes.pl
===================================================================
--- trunk/tools/map-expired-nodes.pl	                        (rev 0)
+++ trunk/tools/map-expired-nodes.pl	2007-09-06 19:16:04 UTC (rev 7738)
Changed blocks: 1, Lines Added: 278, Lines Deleted: 0; 8761 bytes

@@ -0,0 +1,278 @@
+#!/usr/bin/perl
+# map-expired-nodes.pl - Identify expired nodes, add "expired" page for them
+
+# To do:
+# - Add option for "test mode" that just checks node syntax, non-existence
+#   of old_name values and existence of local new_name values.
+# - Add new prolog to rewritten renamed-nodes.txt that describes its
+#   format?
+# - Perhaps show the URL for the new page, but not as a hyperlink.
+#   This would require passing in the document basename. (With a hyperlink,
+#   need only the basename and the browser will derive the full link path.)
+
+# Document directories contain a renamed-nodes.txt file that contains
+# information used for online manuals. It indicates which page "node
+# names" have been renamed, and is used on the public web sites to
+# redirect requests for the old pages to the new pages. However, we want
+# out of date pages to "expire" eventually. For old names that are old
+# enough, we provide an expiration date, and then instead of mapping them
+# to requests for the new page, we create a page that announces "this
+# page is out of date, here's the new page link, please update your
+# bookmarks."  In other words, we don't support redirection of old pages
+# forever, but eventually require users to click through an error page
+# explicitly.
+
+# Example: old_name new_name
+# In this case, the mapping has not expired, so we'll write the line
+# as is to the new renamed-nodes.txt file and let the web server's
+# usual redirection take place.
+
+# Example: old_name new_name 2007-01-01
+# In this case, the mapping expires as of 2007-01-01. After that date,
+# we'll no longer write the line the to the new renamed-nodes.txt file.
+# Instead, we'll create old_name.html in the output directory
+# with content that says the page is expired and points the user to
+# new_name.html.
+
+# Some constraints:
+# - old_name.html MUST NOT exist in the output directory.
+#   If it does, we have a renamed-nodes.txt line that specifies a page
+#   that actually does exist in the document, which is an error.
+# - new_name.html MUST exist in the output directory, because otherwise
+#   we'll be trying to map the old page to a new page that isn't there.
+#   However, this check is done only if new_name specifies a local page
+#   (in the current document). Some new_name values that indicate pages
+#   in other MySQL documents or elsewhere look like this:
+#     ../../4.1/en/charset-upgrading
+#     http://solutions.mysql.com/solutions/partners/
+
+# Who-to-blame:
+# Paul DuBois
+# paul@stripped
+# 2007-08-10
+
+use strict;
+use warnings;
+use Getopt::Long;
+$Getopt::Long::ignorecase = 0; # options are case sensitive
+$Getopt::Long::bundling = 1;   # allow short options to be bundled
+
+my $usage = <<EOF;
+Usage: $0 [options] [renamed-nodes.txt]
+
+Options:
+--help, -h
+    Print this message
+--doc-name=name
+    Document basename
+--doc-lang=lang
+    Document language code
+--output-dir=dir_name
+    Directory containing the output pages (required)
+--verbose, -v
+    Print extra information to STDERR
+
+If no renamed-nodes.txt file is named on the command line,
+input is taken from STDIN.
+EOF
+
+# Variables for command line options; most are undefined initially.
+my $help;
+my $doc_name = "none";
+my $doc_lang = "en";
+my $output_dir;
+my $verbose;
+
+GetOptions (
+  "help|h"            => \$help,
+  "doc-lang=s"        => \$doc_lang,
+  "doc-name=s"        => \$doc_name,
+  "output-dir=s"      => \$output_dir,
+  "verbose|v",        => \$verbose,
+) or die "$usage\n";
+
+if (defined $help)
+{
+  print "$usage\n";
+  exit (0);
+}
+
+if (!defined $output_dir)
+{
+  warn "--output-dir option must be specified\n";
+  die "$usage\n";
+}
+if (!-d $output_dir)
+{
+  die "$output_dir does not exist or is not a directory.\n";
+}
+
+# This is the template for expired pages. %NEW_PAGE% should be
+# replaced with the correct URL for the current page that contains
+# the content now.
+
+my $expired_page_template = q{
+<?php 
+  require 'docbook.php';
+  $pagedata['charset'] = 'utf-8';
+  $pagedata['lang'] = '%DOC_LANG%';
+  $pagedata['product'] = '%DOC_NAME%';
+  $pagedata['pagecomment'] = ($pagedata['lang'] == 'en' ? 'on' : 'off');
+  $pagedata['css'] = '/doc/docs.css';
+  $pagedata['after_related'] = get_promo('meca');
+
+
+doc_navigation(array(
+    'home' => array(),
+    'this' => array(),
+    'prev' => array(),
+    'next' => array(),
+    'up'   => array(),
+    'siblings'  => array(),
+    'children'  => array(),
+    'ancestors'  => array(),
+));
+doc_header();
+?>
+<div class="%OLD_NAME%" lang="%DOC_LANG%">
+<div class="titlepage"><div><div><h2 class="title">
+<a
name="%OLD_NAME%"></a>%OLD_NAME%</h2></div></div></div>
+<p>
+This page has expired.
+The new page is located <a href="%NEW_PAGE%">here</a>.
+</p>
+<p>
+Please update your bookmarks.
+</p>
+</div>
+<?php doc_footer();?>
+};
+
+# Determine current date
+my ($mday, $mon, $year) = ((localtime)[3..5]);
+my $cur_date = ($year+1900)*10000 + ($mon+1)*100 + $mday;
+
+my $errors = 0;
+
+# Read the original renamed-nodes.txt file
+
+while (<>)
+{
+  chomp;
+  next if /^\s*$/ || /^\s*#/;   # skip blank lines and comments
+  my @f = split;
+
+  if (@f < 2 || @f > 3)
+  {
+    warn "ERROR: Malformed renamed-nodes.txt line:\n$_\n"
+       . "(expecting 2 or 3 fields)\n";
+    ++$errors;
+    next;
+  }
+
+  # Get old and new names, perform constraint checking on them, and
+  # construct URL corresponding to new name in case we need to generate
+  # an error page.
+  my $old_name = $f[0];
+  my $new_name = $f[1];
+  my $url;
+
+  # Verify that $old_name is a simple node name
+  if ($old_name !~ /^[-_a-zA-Z0-9]+$/)
+  {
+    warn "ERROR: Old name $old_name is illegal!\n";
+    ++$errors;
+    next;
+  }
+  # Page corresponding to old node name *must not* exist (otherwise we'd
+  # be redirecting a valid page in the document)
+  if (-e "$output_dir/$old_name.html")
+  {
+    warn "ERROR: \"Expired\" page $old_name.html exists in document!\n";
+    ++$errors;
+    next;
+  }
+
+  # Classify $new_name, check existence of corresponding page if it's a
+  # local name (in the current document), and construct the URL to use
+  # in an error page if the mapping is expired.
+
+  if ($new_name =~ /^http:/) # URL?
+  {
+    # Remap using URL as given
+    $url = $new_name;
+  }
+  elsif ($new_name =~ /\.html/)
+  {
+    warn "ERROR: $new_name is illegal (non-URL names cannot have .html)\n";
+    ++$errors;
+    next;
+  }
+  elsif ($new_name =~ m|/|) # Pathname to external page in another MySQL doc?
+  {
+    # Add .html to get page name
+    $url = $new_name . ".html";
+  }
+  elsif ($new_name =~ /^[-_a-zA-Z0-9]+$/) # Local page (in current document)?
+  {
+    # Add .html to get page name (this has no leading directory because it's
+    # in the same directory as the page for the old name)
+    $url = $new_name . ".html";
+    # Verify that page really exists in output directory
+    if (! -e "$output_dir/$url")
+    {
+      warn "ERROR: New page $output_dir/$url fails to exist in document!\n";
+      ++$errors;
+      next;
+    }
+  }
+  else
+  {
+    warn "ERROR: New name $new_name is illegal (unrecognizable format)\n";
+    ++$errors;
+    next;
+  }
+
+  my $expired = 0;    # Is the mapping expired?
+  if (@f == 3)
+  {
+    # There is an expiration-date third field. Verify that it's a date
+    # and determine whether the date has been reached.
+    my $exp_date = $f[2];
+    $f[2] =~ /^(\d{4})-(\d{2})-(\d{2})$/ or die "Bad date: $f[2]\n";
+    $exp_date = $1*10000 + $2*100 + $3;
+    if ($exp_date < $cur_date)
+    {
+      $expired = 1;
+      warn "$old_name has expired as of $f[2]\n" if $verbose;
+    }
+  }
+
+  if (!$expired)
+  {
+    # This is a non-expired mapping. Write the line unchanged and let
+    # the web server take care of redirecting requests for the old
+    # page to the new page.
+
+    print "$old_name $new_name\n";
+  }
+  else
+  {
+    # This is an expired mapping.  Produce an error page using the old
+    # name that points people to the new page but does not redirect
+    # them automatically.
+
+    # Path to page for old node in the output directory
+    my $old_page = "$output_dir/$old_name.html";
+    my $content = $expired_page_template;
+    $content =~ s/%DOC_LANG%/$doc_lang/g;
+    $content =~ s/%DOC_NAME%/$doc_name/g;
+    $content =~ s/%OLD_NAME%/$old_name/g;
+    $content =~ s/%NEW_PAGE%/$url/g;
+    open (EXPIRED, ">$old_page") or die "Cannot open $old_page: $!\n";
+    print EXPIRED $content;
+    close (EXPIRED);
+  }
+}
+
+die "Number of errors found: $errors\n" if $errors > 0;


Property changes on: trunk/tools/map-expired-nodes.pl
___________________________________________________________________
Name: svn:executable
   + *