[interchange-docs] xmldocs - docelic modified 2 files
docs at icdevgroup.org
docs at icdevgroup.org
Sun Nov 11 21:24:57 EST 2007
User: docelic
Date: 2007-11-12 02:24:57 GMT
Modified: bin refs-autogen
Modified: refs UserDatabase
Log:
* refs/UserDatabase: minor typo fix
* bin/refs-autogen:
Solve specific problem where Require reference page was showing Require
as last being present in Interchange 4.6.0.
The problem was caused by the combination of the way we operate on
config directives and the fact that Require was only a catalog
directive in IC 4.6.0.
Closes: #129: See why Require conf directive is listed as last in 4.6.0
In the same change, I also added support for debugging individual
symbols. If some reference page has wrong data, put its name in
DEBUG_ITEM constant (at the top of bin/refs-autogen) and run
'make refxmls' as usual. The debug will show you whole logical line
of execution for that symbol, and from that it will hopefully be
clear what the problem is and in which version/case it happens.
Revision Changes Path
1.123 +63 -7 xmldocs/bin/refs-autogen
rev 1.123, prev_rev 1.122
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.122
retrieving revision 1.123
diff -u -r1.122 -r1.123
--- refs-autogen 12 Nov 2007 00:44:56 -0000 1.122
+++ refs-autogen 12 Nov 2007 02:24:57 -0000 1.123
@@ -13,6 +13,10 @@
use Storable qw/nstore_fd fd_retrieve/;
use Fcntl qw/:DEFAULT :flock/;
+# If you want to debug what exactly is happening with a certain item,
+# but its name in here and you'll get complete trace of the process.
+use constant DEBUG_ITEM => '';
+
{ no warnings;
$Data::Dumper::Indent = 1;
$Data::Dumper::Terse++;
@@ -302,7 +306,9 @@
# Outer loop: $gkey: symbol types (pragmas, globvars, ...)
# Inner loop (~25 lines below): $key, actual symbols from symbol groups
+
while ( my ($gkey,$gval) = each %{ $hash{symbols} } ) {
+
# Unfortunately - $specific_only is of limited use. If you use it,
# the script won't catch symbol "migrations" - that is, for example,
# a tag changing from ui_tag to usertag ...
@@ -365,6 +371,11 @@
my $now = scalar @{ $symbol_lists{$gk} }; # Quick sanity check
if ($prev - $now != 1) { warn "GREP took out more than 1 item!\n" }
+ if ( DEBUG_ITEM and DEBUG_ITEM eq $key ) {
+ print STDERR 'DEBUG ITEM ('.DEBUG_ITEM.'): ' .
+ "changed type from $gk to $gkey\n";
+ }
+
# Mon Nov 5 23:49:18 CET 2007 , this is great: Use
# %extra_process to pass info onto process_symbol() which
# can use it to better track symbol migration from one
@@ -402,6 +413,11 @@
# Register the presence of this item in this version.
push @{ $autogenerated{$gkey}{$key}{"_available in"} }, $hash{version};
+ if ( DEBUG_ITEM and DEBUG_ITEM eq $key ) {
+ print STDERR 'DEBUG ITEM ('.DEBUG_ITEM.'): ' .
+ qq{present in $hash{version}. List is now: @{ $autogenerated{$gkey}{$key}{"_available in"} }\n};
+ }
+
# Prepare source contexts, avoiding those cases
# where a symbol appears multiple times inside the same
# context lines span, but by stattree it gets counted
@@ -415,6 +431,7 @@
my $ar = $hash{symbols}{ $$ag{"_symbol type"} }{$key};
# Do one silly thing (again, compound docs are tearing me apart).
+ # GLOBCONF
if ( $gkey eq 'globconf' ) {
@{ $$ag{'_directive type'} } = ("Global directive");
@@ -1038,7 +1055,37 @@
#}
# How easily one can comment too much of code ;-)
- return if ( ref $autogenerated{$group}{$name} );
+ if ( ref $autogenerated{$group}{$name} ) {
+ if ( DEBUG_ITEM and DEBUG_ITEM eq $name ) {
+ print STDERR 'DEBUG ITEM ('.DEBUG_ITEM.'): ' .
+ "process_symbol(): skel $group/$name already exists, returning\n";
+ }
+ return;
+ }else {
+ if ( DEBUG_ITEM and DEBUG_ITEM eq $name ) {
+ print STDERR 'DEBUG ITEM ('.DEBUG_ITEM.'): ' .
+ "process_symbol(): skel does not exist, creating $group/$name\n";
+ }
+ };
+
+ # I don't know exactly how many places will this addition fix, but
+ # it fixes case where a config directive is first a catconf, and then
+ # later someone also adds it as globconf. At least one such is
+ # Require which was only a catconf in IC 4.6.0.
+ # In that case, catconf context stopped being updated when globconf
+ # was introduced, so the final reference page only showed revision
+ # history for those old versions, up to the introduction of globconf.
+ # It is not intuitively clear from the above code how it fixes the
+ # problem; it is by a combination of the below code and the fact that
+ # we deal with config directives by treating them all as globconfs
+ # by default. (search for GLOBCONF). When such case occurs,
+ # an appropriate note is added to notes section.
+ my $fake_migration = 0;
+ if ( $group eq 'globconf' and $autogenerated{catconf}{$name} ) {
+ $fake_migration++;
+ $$extra{migration}{from} = 'catconf';
+ $$extra{migration}{to} = 'globconf';
+ }
# To better support migrations from group to group:
if ( $$extra{migration} ) {
@@ -1073,12 +1120,21 @@
populate($autogenerated{$group}{$name}, $group, $name, '', 'append');
} else { # inform of migration in NOTES section
- update_field('append', $group, $name, $autogenerated{$group}{$name},
- '', 'notes',
- "In Interchange version $hash{version}, this symbol changed
- type from $longname{$$extra{migration}{from}} to
- $longname{$$extra{migration}{to}}.",
- '</para><para>', '</para><para>');
+ if (! $fake_migration ) {
+ update_field('append', $group, $name, $autogenerated{$group}{$name},
+ '', 'notes',
+ "In Interchange version $hash{version}, this symbol changed
+ type from $longname{$$extra{migration}{from}} to
+ $longname{$$extra{migration}{to}}.",
+ '</para><para>', '</para><para>');
+ } else {
+ update_field('append', $group, $name, $autogenerated{$group}{$name},
+ '', 'notes',
+ "In Interchange versions prior to $hash{version}, this symbol was
+ only a $longname{$$extra{migration}{from}}. In $hash{version} it
+ also became a $longname{$$extra{migration}{to}}.",
+ '</para><para>', '</para><para>');
+ }
}
}
1.4 +1 -1 xmldocs/refs/UserDatabase
rev 1.4, prev_rev 1.3
Index: UserDatabase
===================================================================
RCS file: /var/cvs/xmldocs/refs/UserDatabase,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- UserDatabase 10 Nov 2007 22:33:57 -0000 1.3
+++ UserDatabase 12 Nov 2007 02:24:57 -0000 1.4
@@ -18,7 +18,7 @@
__NAME__ notes
-See &glos-userDB; glossary entry for complete discussion.
+See &glos-UserDB; glossary entry for complete discussion.
__END__
__NAME__ example: UserDatabase layout
More information about the docs
mailing list