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

[paul]

Author: paul
Date: 2007-09-10 21:44:46 +0200 (Mon, 10 Sep 2007)
New Revision: 7776

Log:
 r30095@polar:  paul | 2007-09-10 14:41:53 -0500
 map-expired-nodes.pl:
 - In error pages, compute full URL for pages in other documents from
   document base URL and relative page path.
 - In error pages, display full URL of the page that we're pointing the user
   to.
 - Don't require --output-dir if --dry-run is given.
 Revise %.html-web rule to require DOC_BASE_URL to be set, because
 map-expired-nodes.pl needs it for URL calculation.
 Define DOC_BASE_URL in mysqltest Makefile.


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

Property changes on: trunk
___________________________________________________________________
Name: svk:merge
   - 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:30094
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:24745
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:30095
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:24745
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:20005


Modified: trunk/make.d/xml-html-web
===================================================================
--- trunk/make.d/xml-html-web	2007-09-10 19:44:21 UTC (rev 7775)
+++ trunk/make.d/xml-html-web	2007-09-10 19:44:46 UTC (rev 7776)
Changed blocks: 2, Lines Added: 8, Lines Deleted: 0; 1136 bytes

@@ -5,6 +5,9 @@
 # The l10n.gentext.default.language parameter MUST be set because
 # mysqlweb-chunk.xsl includes its value in each output page.
 
+# The --doc-url-base option MUST be set because $(MAP_EXPIRED_NODES) uses
+# it to compute page URLs. Its value MUST end with a slash.
+
 # Disabling css.decoration suppresses the 'style="clear: both'
 # attribute. This is important because that attribute causes many
 # online manual pages to display incorrectly.

@@ -35,9 +38,14 @@
 	cat $@-tmp/*.html | openssl dgst -md5 > $@-tmp/checksum.txt
 	set -e; \
 	if [ -f renamed-nodes.txt ]; then \
+		if [ x"$(DOC_URL_BASE)" = "x" ]; then \
+			echo DOC_URL_BASE must be defined in the Makefile; \
+			exit 1; \
+		fi; \
 		$(MAP_EXPIRED_NODES) \
 			--doc-lang=$(DOC_LANG) \
 			--doc-name=$(MAIN_DOC_BASENAME) \
+			--doc-url-base=$(DOC_URL_BASE) \
 			--output-dir=$@-tmp \
 			renamed-nodes.txt > $@-tmp/renamed-nodes.txt ; \
 	fi


Modified: trunk/mysqltest/Makefile
===================================================================
--- trunk/mysqltest/Makefile	2007-09-10 19:44:21 UTC (rev 7775)
+++ trunk/mysqltest/Makefile	2007-09-10 19:44:46 UTC (rev 7776)
Changed blocks: 1, Lines Added: 2, Lines Deleted: 0; 411 bytes

@@ -11,6 +11,8 @@
 DOC_LANG = en
 MAIN_DOC_BASENAME = mysqltest
 
+DOC_URL_BASE = http://dev.mysql.com/doc/mysqltest/$(DOC_LANG)/
+
 # Set IDMAP and remap variables
 
 IDMAP_LANG = $(DOC_LANG)


Modified: trunk/mysqltest/renamed-nodes.txt
===================================================================
--- trunk/mysqltest/renamed-nodes.txt	2007-09-10 19:44:21 UTC (rev 7775)
+++ trunk/mysqltest/renamed-nodes.txt	2007-09-10 19:44:46 UTC (rev 7776)
Changed blocks: 1, Lines Added: 2, Lines Deleted: 2; 767 bytes

@@ -22,10 +22,10 @@
 
 # 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-b ../../refman/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-b ../../refman/4.1/en/charset-map 2007-01-01
 expired-c http://dev.mysql.com 2007-01-01


Modified: trunk/tools/map-expired-nodes.pl
===================================================================
--- trunk/tools/map-expired-nodes.pl	2007-09-10 19:44:21 UTC (rev 7775)
+++ trunk/tools/map-expired-nodes.pl	2007-09-10 19:44:46 UTC (rev 7776)
Changed blocks: 8, Lines Added: 81, Lines Deleted: 40; 8420 bytes

@@ -1,50 +1,64 @@
 #!/usr/bin/perl
 # map-expired-nodes.pl - Identify expired nodes, add "expired" page for them
 
+# Reads an input renamed-nodes.txt file. Writes the processed lines from
+# that file to stdout, and possibly creates error pages in the directory
+# named by the --output-dir option.
+
 # 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.)
+# - Dump out URLs corresponding to new_name values that are URLs or pages
+#   in externals documents, so that a link-checker can verify them.
 
 # 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.
+# information used for online manuals. It indicates which page "node names"
+# have been renamed, and is used by the web server on the public web
+# site 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 an error 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.
 
+# 1) If there is no date, redirect old_name to new_name.
+# 2) If there is a date and it hasn't been reached, redirect old_name
+#    to new_name.
+# 3) If there is a date and it has been reached, don't redirect; instead,
+#    create an .html page in the output directory named old_name.html to
+#    "catch" requests for the old name.
+
 # 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.
+# Example: old_name new_name 2008-01-01
+# In this case, the mapping expires as of 2008-01-01.
+# - Before that date, the usual redirection should take place, so we
+#   write old_name and new_name to the new renamed-nodes.txt file.
+# - 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/
+# - If a third field exists, it must be a date.
+# - A given old_name value cannot be listed multiple types.
+# - old_name cannot map to itself.
+# - old_name must be a simple node name (/^[-_a-zA-Z0-9]+$/).
+# - The page corresponding to old_name (old_name.html) MUST NOT exist in
+#   the output directory. (That would mean we're trying to redirect requests
+#   for a valid page, which is an error.)
+# - new_name must be a URL (http://...) or else the basename of a local page
+#   (in the current document) or the basename of an external page (in some
+#   other MySQL document).
+# - For a local new_name value, the corresponding page (new_name.html) MUST
+#   exist in the output directory. (Otherwise, we'd be trying to redirect
+#   to a non-existent page.)
+# - For a local new_name value, the name must be a simple node name.
 
 # Who-to-blame:
 # Paul DuBois

@@ -67,10 +81,14 @@
     Document basename
 --doc-lang=lang
     Document language code
+--doc-url-base=URL
+    Base of the URL for document pages (must end with slash)
 --dry-run, -n
-    No production of output files (just warnings, if any)
+    No production of output files (just warnings, if any); if --output-dir
+    is not given, there is no check for existence of required pages in the
+    output directory
 --output-dir=dir_name
-    Directory containing the output pages (required)
+    Directory containing the output pages (required unless --dry-run is used)
 --verbose, -v
     Print extra information to STDERR
 

@@ -82,6 +100,7 @@
 my $help;
 my $doc_name = "none";
 my $doc_lang = "en";
+my $doc_url_base = "";
 my $dry_run;
 my $output_dir;
 my $verbose;

@@ -90,6 +109,7 @@
   "help|h"            => \$help,
   "doc-lang=s"        => \$doc_lang,
   "doc-name=s"        => \$doc_name,
+  "doc-url-base=s"    => \$doc_url_base,
   "dry-run|n"         => \$dry_run,,
   "output-dir=s"      => \$output_dir,
   "verbose|v",        => \$verbose,

@@ -103,10 +123,13 @@
 
 if (!defined $output_dir)
 {
-  warn "--output-dir option must be specified\n";
-  die "$usage\n";
+  if (!defined $dry_run)
+  {
+    warn "--output-dir option must be specified unless --dry-run is used\n";
+    die "$usage\n";
+  }
 }
-if (!-d $output_dir)
+elsif (!-d $output_dir)
 {
   die "$output_dir does not exist or is not a directory.\n";
 }

@@ -143,9 +166,12 @@
 <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>.
+The new page is located here:
 </p>
 <p>
+<a href="%NEW_PAGE%">%NEW_PAGE%</a>
+</p>
+<p>
 Please update any bookmarks that you may have had for the page.
 </p>
 </div>

@@ -215,8 +241,10 @@
     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")
+  # be redirecting a valid page in the document). Do this check only if
+  # the output directory is known. (It's allowable for it not to be
+  # specified if --dry-run was used.)
+  if (defined ($output_dir) && -e "$output_dir/$old_name.html")
   {
     ++$expired_old_name_exists{$old_name};
     next;

@@ -239,7 +267,20 @@
   elsif ($new_name =~ m|/|) # Pathname to external page in another MySQL doc?
   {
     # Add .html to get page name
-    $url = $new_name . ".html";
+    $url = $doc_url_base;
+    my $page = $new_name . ".html";
+    # Trim a component from the base URL end for each "../" at the beginning
+    # of the page path. Example:
+    # From: http://host/dir1/dir2/dir3/ and ../../page.html
+    # To:   http://host/dir1/ and page.html
+    # The resulting URL is http://host/dir1/page.html rather than
+    # http://host/dir1/dir2/dir3/../../page.html.
+    while ($page =~ m|^\.\./| && $url =~ m|[^/]*/$|)
+    {
+      $page =~ s|^\.\./||;
+      $url =~ s|[^/]*/$||;
+    }
+    $url = (defined ($doc_url_base) ? $doc_url_base : "") . $new_name . ".html";
   }
   elsif ($new_name =~ /^[-_a-zA-Z0-9]+$/) # Local page (in current document)?
   {