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

[paul]

Author: paul
Date: 2007-05-14 21:22:38 +0200 (Mon, 14 May 2007)
New Revision: 6447

Log:
 r24933@polar:  paul | 2007-05-14 14:16:54 -0500
 Revise document dependency generation to include the idmap files
 that define the IDs to which the document refers. This means that,
 for targets that require ID resolution/remapping, the requisite
 idmap files will be built first, so that we don't get "ID xxx not
 found internally or externally" errors, even after make realclean
 or make clean.
 
 Because idmap information is used for this, you should run "make idmap"
 from the top-level directory prior to running "make depend".


Modified:
   trunk/make.d/vars-docbook
   trunk/make.d/xml-depend
   trunk/tools/xmldepend-post.pl
   trunk/tools/xmldepend.pl

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


Modified: trunk/make.d/vars-docbook
===================================================================
--- trunk/make.d/vars-docbook	2007-05-14 19:22:16 UTC (rev 6446)
+++ trunk/make.d/vars-docbook	2007-05-14 19:22:38 UTC (rev 6447)
Changed blocks: 1, Lines Added: 6, Lines Deleted: 1; 964 bytes

@@ -57,8 +57,13 @@
 # on the entire set of sources for a given file (that is, the file
 # itself and those files that it includes).
 
-XMLDEPEND_POST_TARGET_LIST ?=
.valid,.validwarn,.validpure,-prepped.xml,-manprepped.xml,-remprepped.xml,.titles,.useless
+XMLDEPEND_POST_FILE_DEP_TARGETS ?= .validpure,.titles,.useless
 
+# Similar, but these targets also require ID remapping and thus depend
+# on ID map files as well.
+
+XMLDEPEND_POST_FILE_AND_ID_DEP_TARGETS ?=
.valid,.validwarn,-prepped.xml,-manprepped.xml,-remprepped.xml
+
 # Comma-separated list of source files that xmldepend-post.pl should exclude
 # from the xxx_IDMAP_SOURCES variables.  This should be set to the
 # names of any dynamically generated documents because we do not need


Modified: trunk/make.d/xml-depend
===================================================================
--- trunk/make.d/xml-depend	2007-05-14 19:22:16 UTC (rev 6446)
+++ trunk/make.d/xml-depend	2007-05-14 19:22:38 UTC (rev 6447)
Changed blocks: 1, Lines Added: 14, Lines Deleted: 1; 1135 bytes

@@ -8,13 +8,26 @@
 #   this: include Makefile.depends
 # - Create an empty Makefile.depends file: touch Makefile.depends
 
+ifdef IDMAP_REFS
 depend::
 	$(XMLDEPEND) $(DEPEND_FILES) \
 		| $(XMLDEPEND_POST) \
-			--target-list=$(XMLDEPEND_POST_TARGET_LIST) \
+			--file-dep-targets=$(XMLDEPEND_POST_FILE_DEP_TARGETS) \
+			--file-and-id-dep-targets=$(XMLDEPEND_POST_FILE_AND_ID_DEP_TARGETS) \
 			--idmap-exclusions=$(XMLDEPEND_IDMAP_EXCLUSIONS_LIST) \
+			--srcpaths="$(IDMAP_REFS)" \
 		> Makefile.depends.new
 	mv Makefile.depends.new Makefile.depends
+else
+depend::
+	$(XMLDEPEND) $(DEPEND_FILES) \
+		| $(XMLDEPEND_POST) \
+			--file-dep-targets=$(XMLDEPEND_POST_FILE_DEP_TARGETS) \
+			--file-and-id-dep-targets=$(XMLDEPEND_POST_FILE_AND_ID_DEP_TARGETS) \
+			--idmap-exclusions=$(XMLDEPEND_IDMAP_EXCLUSIONS_LIST) \
+		> Makefile.depends.new
+	mv Makefile.depends.new Makefile.depends
+endif
 
 clean::
 	$(RM) Makefile.depends.new


Modified: trunk/tools/xmldepend-post.pl
===================================================================
--- trunk/tools/xmldepend-post.pl	2007-05-14 19:22:16 UTC (rev 6446)
+++ trunk/tools/xmldepend-post.pl	2007-05-14 19:22:38 UTC (rev 6447)
Changed blocks: 6, Lines Added: 152, Lines Deleted: 26; 8284 bytes

@@ -1,4 +1,4 @@
-#! /usr/bin/perl -w 
+#!/usr/bin/perl
 # vim:set ts=2 sw=2 expandtab:
 
 # xmldepend-post.pl - postprocess output of xmldepend.pl into a format

@@ -21,15 +21,19 @@
 # suffixes, a line is written making each abc<suffix> dependent on
 # $(abc_SOURCES).
 
+# Who-to-blame:
 # Paul DuBois
 # paul@stripped
 # 2007-04-17
 
 use strict;
-
+use warnings;
+use File::Basename;
 use Getopt::Long;
 $Getopt::Long::ignorecase = 0; # options are case sensitive
 $Getopt::Long::bundling = 1;   # allow short options to be bundled
+use lib qw(./tools ../tools ../../tools);
+use IDMap;
 
 my $XMLDEPEND_POST_VERSION = "1.00";
 my $prog_name = "xmldepend-post.pl";

@@ -45,12 +49,25 @@
 --help, -h
     Print this message
 --idmap-exclusions-list=file[,file]...
-    List of files to be excluded from the _IDMAP_SOURCES variable
-    definitions
---target-list=suffix[,suffix]...
-    List of target types to be made dependent on files named in input
-    (e.g., --target-list=-prepped.xml causes abc-prepped.xml to be
-    made dependent on the sources for abc.xml)
+    Comma-separated list of files to be excluded from the _IDMAP_SOURCES
+    variable definitions.
+--srcpaths="pathlist"
+    Space-separated list of directories to search for ID map files.
+    Order of directories determines which to use first in case of
+    multiple matches for a given ID. (Default: ".")
+--file-dep-targets=suffix[,suffix]...
+    Comma-separated list of target types that are dependent on an input
+    .xml file and its inclusions.
+    Example: --file-dep-targets=.useless causes abc.useless to be made
+    dependent on the sources for abc.xml.
+--file-and-id-dep-targets=suffix[,suffix]...
+    Comma-separated list of target types that are dependent on an input
+    .xml file and its inclusions and that also require ID remapping
+    Example: --file-and-id-dep-targets=.valid causes abc.valid to be
+    made dependent on the sources for abc.xml and any ID map files
+    required for ID remapping.
+    NOTE: If this option is specified, all ID map files in all document
+    directories named by --srcpaths MUST have been generated first.
 --version, -V
     Show version information and exit
 EOF

@@ -58,14 +75,19 @@
 # Variables for command line options
 my $help;
 my $idmap_excl_list;
-my $target_list;
+my $file_dep_target_list;
+my $file_and_id_dep_target_list;
+my $srcpathopt;
 my $show_version;
 
+
 GetOptions (
-  "help|h"               => \$help,            # print help message
-  "idmap-exclusions|X:s" => \$idmap_excl_list, # ID map exclusions
-  "target-list|T:s"      => \$target_list,     # target types
-  "version|V"            => \$show_version,    # show version info
+  "help|h"                    => \$help,
+  "idmap-exclusions:s"        => \$idmap_excl_list,
+  "srcpaths=s"                => \$srcpathopt,
+  "file-dep-targets:s"        => \$file_dep_target_list,
+  "file-and-id-dep-targets:s" => \$file_and_id_dep_target_list,
+  "version|V"                 => \$show_version,
 ) or do { print "$usage\n"; exit (1); };
 
 if (defined ($help))

@@ -80,44 +102,121 @@
   exit (0);
 }
 
-my @idmap_excl_list = split(/,/, $idmap_excl_list) if defined $idmap_excl_list;
-my @target_list = split(/,/, $target_list) if defined $target_list;
+my @idmap_excl_list = split(/,/, $idmap_excl_list)
+     if defined $idmap_excl_list;
 
+my @file_dep_targets = split(/,/, $file_dep_target_list)
+     if defined $file_dep_target_list;
+my @file_and_id_dep_targets = split(/,/, $file_and_id_dep_target_list)
+     if defined $file_and_id_dep_target_list;
+
+my @srcpaths = (".");
+@srcpaths = split(/ /,$srcpathopt) if defined $srcpathopt;
+
+die "No source paths given\n" unless @srcpaths;
+my $idmap = IDMap->new({sources => \@srcpaths});
+
+# Read input, categorize lines into file-dependency lines and ID-reference
+# lines, each keyed by the file to which the information in the line apllies
+
+my %file_lines;
+my %idref_lines;
+
 while (<>)
 {
-  my (@files, $file, $base, $base_under);
+  my (@words, $type, $file);
 
   chomp;
-  @files = split(/\s+/, $_);
-  $file = shift (@files);
+  @words = split(/\s+/, $_);
+  $type = shift (@words);
+  $file = shift (@words);
   # skip files except those in current directory with .xml suffix
   next unless $file !~ m|/| && $file =~ /\.xml$/;
+  if (/^files /)
+  {
+    $file_lines{$file} = [ @words ]
+  }
+  elsif (/^idrefs /)
+  {
+    $idref_lines{$file} = [ @words ]
+  }
+  else
+  {
+    die "LOGIC ERROR: unknown line type: $_\n";
+  }
+}
+
+# For each file, put out all the variable definitions that apply to it,
+# then dependencies for target types given in --target-list. The
+# variables must be defined first, before the target dependencies
+# that use the definitions.
+
+foreach my $file (sort keys %file_lines)
+{
+  my (@words, $base, $base_under);
+
   $base = $file;
   $base =~ s/\.xml$//;
   ($base_under = $base) =~ s/[-.]/_/g;
+
   # produce variable definition for all included files
-  define_variable ($base_under . "_INCLUDES", @files);
+
+  @words = @{$file_lines{$file}};
+
+  define_variable ($base_under . "_INCLUDES", @words);
   # produce variable definition for included image files
   define_variable ($base_under . "_IMAGES",
-                   grep { $_ =~ /\.(png|gif|jpg|jpeg)/ } @files);
+                   grep { $_ =~ /\.(png|gif|jpg|jpeg)/ } @words);
   # produce variable definition for all source files
   print "${base_under}_SOURCES = $file \$(${base_under}_INCLUDES)\n";
-  # produce variable definition for all ID map source files
+  # produce variable definition for all source files used to produce ID
+  # map files
   # (same as .xml files in _SOURCES minus anything in the ID map exclusions)
   my @idfiles = ();
   push (@idfiles, $file) unless grep { $_ eq $file } @idmap_excl_list;
-  foreach my $f (grep { $_ =~ /\.xml$/} @files)
+  foreach my $f (grep { $_ =~ /\.xml$/} @words)
   {
     push (@idfiles, $f) unless grep { $_ eq $f } @idmap_excl_list;
   }
   define_variable ($base_under . "_IDMAP_SOURCES", @idfiles);
-#  # make the file dependent on those that it includes
-#  print "$file: \$(${base_under}_INCLUDES)\n";
-  # produce dependencies for target types given in --target-list
-  foreach my $suffix (@target_list)
+
+  # produce variable definition for ID map files for referred-to IDs
+
+  @words = @{$idref_lines{$file}};
+
+  # Map IDs to files that define them
+  my %idfiles = ();
+  foreach my $id (@words)
   {
+    my $xfile = $idmap->id_file ($id);
+    die "ID $id not found in current maps (@srcpaths)\n"
+      unless defined $xfile;
+    $idfiles{$xfile} = 1;
+  }
+#warn "idrefs $file ", join (" ", sort (keys (%idfiles))), "\n";
+  # Convert each .xml filename to its corresponding .idmap file
+  my @idmaps = ();
+  foreach my $xfile (keys (%idfiles))
+  {
+    my ($base, $dir, $suffix) = fileparse ($xfile, ".xml");
+    my $mapfile = "metadata/$base.idmap";
+    $mapfile = $dir . $mapfile unless $dir eq "./";
+    push @idmaps, $mapfile;
+  }
+#warn "idmaps $file ", join (" ", @idmaps), "\n";
+  # produce variable definition for all required idmap files
+  define_variable ($base_under . "_IDMAPS", @idmaps);
+
+  # produce dependencies for target types given in --file-dep-targets
+  # and --file-and-id-dep-targets options
+  foreach my $suffix (@file_dep_targets)
+  {
     print "$base$suffix: \$(${base_under}_SOURCES)\n";
   }
+  foreach my $suffix (@file_and_id_dep_targets)
+  {
+    print "$base$suffix: \$(${base_under}_SOURCES) \$(${base_under}_IDMAPS)\n";
+  }
   print "\n";
 }
 

@@ -129,3 +228,30 @@
   print " \\\n\t", join (" \\\n\t", @files) if @files;
   print "\n";
 }
+
+# ----------------------------------------------------------------------
+
+# IDMap package extensions
+
+package IDMap;
+
+# Look up an ID in the ID map and return the pathname to the file in which
+# the ID occurs.  The pathname is relative to the current directory.
+
+sub id_file
+{
+my ($self, $id) = @_;
+my $file = undef;
+
+  if (defined $self->{$id} && defined $self->{$id}->{file})
+  {
+    # Get directory path to file (don't bother if it's "./")
+    $file = $self->{$id}->{prefix} ne "."
+              ? $self->{$id}->{prefix} . "/"
+              : "";
+    $file .= $self->{$id}->{file};
+  }
+  $file;
+}
+
+1;


Modified: trunk/tools/xmldepend.pl
===================================================================
--- trunk/tools/xmldepend.pl	2007-05-14 19:22:16 UTC (rev 6446)
+++ trunk/tools/xmldepend.pl	2007-05-14 19:22:38 UTC (rev 6447)
Changed blocks: 8, Lines Added: 74, Lines Deleted: 7; 4302 bytes

@@ -74,9 +74,9 @@
 
 my %deps = ();
 
-# Flags to track dependency expansion after parsing and before output.
+# Map of ID references.
 
-my %expanded = ();
+my %idrefs = ();
 
 # Parse input files
 

@@ -84,7 +84,7 @@
 
 foreach my $file (@ARGV)
 {
-  my $xi_handler = XIncluder->new ($file, \%deps, $verbose);
+  my $xi_handler = XIncluder->new ($file, \%deps, \%idrefs, $verbose);
 
   if (!defined ($xi_handler))
   {

@@ -111,25 +111,47 @@
 # indirectly through *those* files. Expand all the dependency lists to
 # include indirectly referenced files.
 
+# After expanding dependencies, for each file, add the idrefs of each
+# dependent file to its own idrefs.
+
+# Flags to track dependency expansion after parsing and before output.
+my %expanded = ();
+
 foreach my $file (keys (%deps))
 {
   expand_deps ($file);
 }
 
-# Write dependency information:
-# - One line for each file named on the command line or referenced by them.
-# - Each line lists a file followed by all files referenced by (included
+foreach my $file (keys (%idrefs))
+{
+  expand_idrefs ($file);
+}
+
+# Write dependency and ID reference information:
+# - One line of each type for each file named on the command line or
+#   referenced by them.
+# - "files" line lists a file followed by all files referenced by (included
 #   within) that file.
+# - "idrefs" line lists a file followed by all IDs referenced by that file.
 
 binmode (STDOUT, ":utf8");
+
 foreach my $file (sort (keys (%deps)))
 {
   my @deps = sort (keys (%{$deps{$file}}));
-  print $file;
+  print "files $file";
   print " ", join (" ", @deps) if @deps;
   print "\n";
 }
 
+foreach my $file (sort (keys (%idrefs)))
+{
+  my @idrefs = sort (keys (%{$idrefs{$file}}));
+  print "idrefs $file";
+  print " ", join (" ", @idrefs) if @idrefs;
+  print "\n";
+}
+
 # Expand the dependencies for a file to include all indirectly referenced
 # files, not just directly referenced files.
 

@@ -153,6 +175,25 @@
   $expanded{$parent} = 1;
 }
 
+# Expand the idrefs for a file to include all those for its dependent files.
+# There is no need for this to recurse like expand_deps() because each
+# file's dependencies have been expanded and they are all known.
+
+sub expand_idrefs
+{
+my $parent = $_[0];
+
+  # Look through each dependent file and add its own
+  # idrefs to those of the parent.
+  foreach my $child (keys (%{$deps{$parent}}))
+  {
+    foreach my $id (keys (%{$idrefs{$child}}))
+    {
+      $idrefs{$parent}->{$id} = 1;
+    }
+  }
+}
+
 # ----------------------------------------------------------------------
 
 # This module provides a handler object for XML::Parser::PerlSAX.

@@ -187,6 +228,7 @@
 my $class = shift;
 my $file = shift;    # file to be parsed (needed to initialize file_stack)
 my $deps = shift;    # current dependency map
+my $idrefs = shift;  # current ID ref map
 my $verbose = shift; # be verbose?
 my $self = {};
 

@@ -210,6 +252,10 @@
   # if there are no dependent files.
   $self->{deps}->{$file} = {};
 
+  # Similar for map of idrefs
+  $self->{idrefs} = $idrefs;
+  $self->{idrefs}->{$file} = {};
+
   # Bless hash into an object of the class
   bless ($self, $class);
 

@@ -253,6 +299,13 @@
     warn "File reference to $file\n" if $self->{verbose};
     $self->add_dependency ($file, "fileref");
   }
+  elsif ($elt->{Attributes}->{linkend})
+  {
+    my $idref = $elt->{Attributes}->{linkend};
+
+    warn "ID reference to $idref\n" if $self->{verbose};
+    $self->add_idref ($idref);
+  }
   elsif (($elt->{Name} eq 'remark') &&
          (exists($elt->{Attributes}->{role})) &&
          ($elt->{Attributes}->{role} eq 'dependency'))

@@ -403,6 +456,20 @@
   pop (@{$self->{file_stack}});
 }
 
+# Add argument as ID reference for the current file.
+
+sub add_idref
+{
+my $self = shift;
+my $idref = shift;
+my $curfile = $self->{file_stack}[-1];
+
+  # Initialize curfile idrefs to empty hash if necessary
+  $self->{idrefs}->{$curfile} = {} unless exists $self->{idrefs}->{$curfile};
+  # Add argument as idref of curfile (eliminating duplicates)
+  $self->{idrefs}->{$curfile}->{$idref} = 1;
+}
+
 # Try to create a file that is to be read if it is missing.
 # Route stdout to stderr so it doesn't pollute dependency output.