[interchange-docs] xmldocs - docelic modified bin/refs-autogen
docs at icdevgroup.org
docs at icdevgroup.org
Mon Nov 5 18:38:54 EST 2007
User: docelic
Date: 2007-11-05 23:38:54 GMT
Modified: bin refs-autogen
Log:
* When some symbol changes group (for example, when moving a tag file
from uitag to usertag), in xmldocs we lose its previous information
and start tracking "history" from that new point in time.
This was suboptimal, and there was also a bug which sometimes caused
only the old info (before the change) to be displayed instead of the
new one.
This new code fixes this problem and also manages to keep history
from the original introduction of the symbol (even if it was in
a different group). Also an appropriate note about the symbol
group change is automatically appended to NOTES section for the
tag.
Closes #91: Wrong version and source code on [component] documentation
Revision Changes Path
1.120 +55 -14 xmldocs/bin/refs-autogen
rev 1.120, prev_rev 1.119
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.119
retrieving revision 1.120
diff -u -r1.119 -r1.120
--- refs-autogen 20 Aug 2007 18:37:37 -0000 1.119
+++ refs-autogen 5 Nov 2007 23:38:53 -0000 1.120
@@ -338,6 +338,7 @@
# UPDATE: Item can only float between categories if it is a tag,
# for all other symbols it means we have different symbols of
# the same name (such as 'value' which is both a tag and filter).
+ my %extra_process = (); # Pass extra info to process_symbol()
for my $gk ( keys %symbol_lists ) {
if ( grep {/^$key$/} @{ $symbol_lists{$gk} } ) {
if ( $gk ne $gkey ) { # SPLAT! Symbol changed category over time.
@@ -363,6 +364,20 @@
@{ $symbol_lists{$gk} } = grep {!/^$key$/} @{ $symbol_lists{$gk} };
my $now = scalar @{ $symbol_lists{$gk} }; # Quick sanity check
if ($prev - $now != 1) { warn "GREP took out more than 1 item!\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
+ # group to another (for example, from uitag to usertag)
+ # and to keep some of the history and to be able to
+ # auto-include this info in NOTES section.
+ %extra_process = (
+ migration => {
+ from => $gk,
+ to => $gkey,
+ in_version => $hash{version},
+ }
+ );
# Else the symbol is not new, didn't change category or antything
# and it's a normal already-existing symbol.
@@ -382,7 +397,7 @@
# It is okay to add info from refs/<name>/* to the item at this step
# because that information is not version-specific; it's constant.
# ** This fills %autogenerated **
- process_symbol($gkey, $key, $val);
+ process_symbol($gkey, $key, $val, \%extra_process);
# Register the presence of this item in this version.
push @{ $autogenerated{$gkey}{$key}{"_available in"} }, $hash{version};
@@ -949,7 +964,7 @@
# Helpers below
sub process_symbol {
- my ($group, $name, $ref) = @_;
+ my ($group, $name, $ref, $extra) = @_;
# XXX: Ok, now, I figured this thing out. Some files changed location
# between versions and their type changed, so this fell apart.
@@ -982,8 +997,16 @@
# How easily one can comment too much of code ;-)
return if ( ref $autogenerated{$group}{$name} );
+ # To better support migrations from group to group:
+ if ( $$extra{migration} ) {
+ $autogenerated{$group}{$name} =
+ $autogenerated{$$extra{migration}{from}}{$name};
+ delete $autogenerated{$$extra{migration}{from}}{$name};
+ }
+
# Make skel
$autogenerated{$group}{$name} = {
+ ( $$extra{migration} ? %{ $autogenerated{$group}{$name} } : ()),
name => $name,
id => $name,
"_symbol type" => $group,
@@ -993,18 +1016,27 @@
#"symbol type" => "&SYMBOL_" . uc($group) . ";",
};
- # Skel is done, now:
-
- # Suplement with information from a control file. Control file overrides
- # settings, but this is only available if multi-file method is used to
- # document an item (so, refs/itemname/*). If multi-file method is not used,
- # nothing gets done here.
- populate($autogenerated{$group}{$name}, $group, $name, 'control', 'override');
-
- # Supplement information with other files, that is, either
- # all but 'control' file from refs/itemname/*, or just refs/itemname
- # if single-file method is used (which is standard).
- populate($autogenerated{$group}{$name}, $group, $name, '', 'append');
+ # Skel is done, now only if it wasn't a migration:
+ if (! $$extra{migration} ) {
+ # Suplement with information from a control file. Control file overrides
+ # settings, but this is only available if multi-file method is used to
+ # document an item (so, refs/itemname/*). If multi-file method is not used,
+ # nothing gets done here.
+ populate($autogenerated{$group}{$name},$group,$name,'control','override');
+
+ # Supplement information with other files, that is, either
+ # all but 'control' file from refs/itemname/*, or just refs/itemname
+ # if single-file method is used (which is standard).
+ 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>');
+ }
}
sub populate {
@@ -1160,6 +1192,15 @@
}
}
+# Update section of a symbol. Some more info:
+# mode: override or append
+# group: symbol group
+# name: symbol name
+# $sref: $autogenerated{$group}{$name}
+# $fn: unused
+# $sect: section
+# $content: body
+# $pre/$post: usually nothing
sub update_field {
my ($mode, $group, $name, $sref, $fn, $sect, $content, $pre, $post) = @_;
More information about the docs
mailing list