[docs] xmldocs - docelic modified bin/refs-autogen
docs at icdevgroup.org
docs at icdevgroup.org
Tue Oct 26 06:00:55 EDT 2004
User: docelic
Date: 2004-10-26 10:00:55 GMT
Modified: bin refs-autogen
Log:
- although not yet fully tested and working, the support for multiple
symbols with the same name is generally implemented.
For the 'value' symbol for example, which is both a systemtag and filter,
you need to create refs/value.filter and refs/value.tag (it should be
refs/value.systemtag actually, but we allow tags to fluctuate between
tag subgroups, so...). (The support for this just mentioned feature
(.tag) is yet to be added ;-)
It is also possible to have only refs/<name> for a multiple-times-appearing
symbol, in which case the symbols will share a description. (This is handy
to keep single description for both global and catalog config directive).
Revision Changes Path
1.53 +84 -68 xmldocs/bin/refs-autogen
rev 1.53, prev_rev 1.52
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.52
retrieving revision 1.53
diff -u -r1.52 -r1.53
--- refs-autogen 26 Oct 2004 08:56:56 -0000 1.52
+++ refs-autogen 26 Oct 2004 10:00:55 -0000 1.53
@@ -16,16 +16,19 @@
# - go through all the symbols found in the cache, and:
# - push symbol name to @$symbol_lists{group name} (if not there already)
# - call process_symbol() which creates the skel entry in
-# $autogenerated{$symbol} if not present (and also fixes stuff if the
-# item IS present, but the path changed so Source contexts wouldn't work).
-# - we then call populate() which updates $autogenerated{$symbol} with
-# user-supplied information from the filesystem (refs/*/*).
+# $autogenerated{$group}{$symbol} if not present
+# (and also fixes stuff if the item IS present, but the path changed
+# so Source contexts wouldn't work).
+# - we then call populate() which updates $autogenerated{$group}$symbol}
+# with user-supplied information from the filesystem (refs/*/*).
# - we update the "Available in" line
# - we do some more tuning
# - we construct the "Source" section (only dealing with formatting
# and display; what's actually in there is already decided in
# bin/stattree run)
-# - XXX finish the list
+# - When all items are read-in and generated, the templates are filled
+# with items, expanding variables.
+# - Finally, the whole thing is output as .xml
use warnings;
use strict;
use File::Find;
@@ -40,28 +43,26 @@
$Data::Dumper::Sortkeys++;
}
-my $force_regenerate = 1; # Rebuild pages even if they exist
my $dumpdb = 0;
my $verbose = 0;
my $OUTPUT = "OUTPUT";
my %refcache; # memory cache of Storable files. Not really needed but I
# copied old code which had it, so ...
-my %hash; # complete tree data
+my %hash; # complete tree data for each IC version we parse
my $cachedir = $ENV{CACHE} || "cache";
-my %i; # internally derived data
-my %autogenerated; # Data for symbols autogenerated in this run
+my %i; # internally derived data (only $i{ver} for now).
+my %autogenerated; # Content of autogenerated symbols
my %invalid; # Information about missing documentation
my %covered; # Weed out duplicate context reports
my %symbol_lists; # symbols listed in categories
my %symbols; # FINAL symbol refentries
-my %templates;
-my $max_ctxs = 10;
-my @set_missing_all;
-my @parsed_versions;
-my $specific_only;
-my $output_spec;
-my $output_both;
-my %first; # Keep track if symbol group appears first time or not. (! logic)
+my %templates; # Templates for various symbol types
+my $max_ctxs = 10; # Trim more than $max_ctxs source context reports
+my @set_missing_all; # Helper to better manage %invalid
+my @parsed_versions; # IC versions we parsed
+my $specific_only; # Build only one specific .xml ?
+my $output_spec; # 'list' produces tag list, 'xml' produces real xml source
+my $output_both; # Unconditionally override $output_spec
my $no_autodefs; # Generate autodefs.ent collection of entities by default
my $autopath = "docbook/autodefs.ent";
@@ -140,18 +141,22 @@
# Inner loop: actual symbols
while ( my ($gkey,$gval) = each %{ $hash{symbols} } ) {
next if $specific_only and $gkey ne $specific_only;
- if (! $symbol_lists{$gkey} ) { # So the item is new
+
+ # Simply for display purpose
+ if (! $symbol_lists{$gkey} ) {
my @olist;
push @olist, "refs/${gkey}s.xml" if $output_xml;
push @olist, "tmp/${gkey}s.list" if $output_list;
local $" = ", ";
print "GEN: @olist\n";
}
+
+
for my $key (keys(%$gval)) {
my $val = $gval->{$key};
# Register the symbol name ($key) under group name ($gkey) in
- # %symbol_lists. We need to check if it already exists in all
+ # %symbol_lists. We need to check if it already exists
# under %symbol_lists, searching in the same group is not enough
# because group might have changed in next version (usertag -> uitag).
# UPDATE: Item can only float between categories if it is a tag,
@@ -172,8 +177,11 @@
warn "$key IS BOTH $gk and $gkey!\n";
goto SKIPDUPCHECK;
}
-
- # Delete item from old location
+
+ # If it was just the same symbol changing tag subgroup
+ # (uitag -> usertag), then delete it from the old location.
+ # (That means we'll trat it as new item, and it will be properly
+ # re-created at the new position).
my $prev = scalar @{ $symbol_lists{$gk} }; # Quick sanity check
@{ $symbol_lists{$gk} } = grep {!/^$key$/} @{ $symbol_lists{$gk} };
my $now = scalar @{ $symbol_lists{$gk} }; # Quick sanity check
@@ -187,9 +195,9 @@
SKIPDUPCHECK:
!$found and push @{ $symbol_lists{$gkey} }, $key;
- # Define basic hash for the item ( $autogenerated{<name>} ), and
+ # Define basic hash for the item ( $autogenerated{$gkey}{<name>} ), and
# load values from files. The function returns if
- # $autogenerated{<name>} is present already (that is, the basic
+ # $autogenerated{group}{<name>} is present already (that is, the basic
# skeleton was already made).
# 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.
@@ -197,9 +205,9 @@
process_symbol($gkey, $key, $val);
# Register the presence of this item in this version.
- push @{ $autogenerated{$key}{"_available in"} }, $hash{version};
- $autogenerated{$key}{"available in"} =
- join ", ", @{ $autogenerated{$key}{"_available in"} };
+ push @{ $autogenerated{$gkey}{$key}{"_available in"} }, $hash{version};
+ $autogenerated{$gkey}{$key}{"available in"} =
+ join ", ", @{ $autogenerated{$gkey}{$key}{"_available in"} };
# Prepare source contexts, avoiding those cases
# where a symbol appears multiple times inside the same
@@ -210,7 +218,7 @@
# Having this code in this loop will make all symbols
# end up having the last version they appear in displayed in
# source section.
- my $ag = $autogenerated{$key};
+ my $ag = $autogenerated{$gkey}{$key};
my $ar = $hash{symbols}{ $$ag{"_symbol type"} }{$key};
if ( $ar ) {$$ag{source} = "" }
@@ -328,7 +336,8 @@
### THIS IS LAST RUN ###
# Final entry. That's where we add examples
# (which don't have version-specific data, they're always "latest")
-while ( my($k,$v) = each %autogenerated ) {
+for my $group ( keys %autogenerated ) {
+while ( my($k,$v) = each %{ $autogenerated{$group} } ) {
my %ag = %$v;
# Do temporary-only modifications to %ag
@@ -361,15 +370,15 @@
# _See Also_ section: "bidirectional" linking
if ( defined @{ $ag{'_see also'} } ) {
my $list = $ag{'_see also'};
- @$list = grep {$autogenerated{$_} and $_ ne $ag{name}} @$list;
+ @$list = grep {$autogenerated{$group}{$_} and $_ ne $ag{name}} @$list;
#$ag{'see also'} = join ", ", @{ $ag{'_see also'} }; # Done below anyway
for my $sym ( @$list ) {
- my $list2 = $autogenerated{$sym}{'_see also'};
+ my $list2 = $autogenerated{$group}{$sym}{'_see also'};
push @$list2, @$list, $k;
{ my %h; @$list2 = grep {!$h{$_}++ and $sym ne $_} @$list2 }
- @{ $autogenerated{$sym}{'_see also'} } = @$list2;
- $autogenerated{$sym}{'see also'} = join ", ", @$list2;
+ @{ $autogenerated{$group}{$sym}{'_see also'} } = @$list2;
+ $autogenerated{$group}{$sym}{'see also'} = join ", ", @$list2;
}
}
@@ -379,10 +388,11 @@
# olink to link between documents
for my $itm ( @see_items ) {
next if $itm =~ /^</;
- if ( $autogenerated{$itm} ) {
+ if ( $autogenerated{$group}{$itm} ) {
my $linktype = "link"; # the default, linking inside the same document
my $linkarg = "linkend";
- if ( $autogenerated{$itm}{'_symbol type'} eq $ag{'_symbol type'} ) {
+ if ( $autogenerated{$group}{$itm}{'_symbol type'} eq
+ $ag{'_symbol type'} ) {
# Nothing, just use link linkend= if the targets are inside the same
# document.
} else {
@@ -445,7 +455,9 @@
}
# Save
- $symbols{$k} = $template unless ( $ag{ignore} and $ag{ignore} =~ /[y1d]/i );
+ $symbols{$group}{$k} =
+ $template unless ( $ag{ignore} and $ag{ignore} =~ /[y1d]/i );
+}
}
sub compress_availability {
@@ -497,7 +509,7 @@
## Add items
for my $item (sort @$v) {
- $refpage .= $symbols{$item} if $symbols{$item}
+ $refpage .= $symbols{$k}{$item} if $symbols{$k}{$item}
}
## Close up
@@ -577,25 +589,25 @@
# To fix this, we simply leave item skeleton to be autoregenerated in
# those cases (we could leave through in any case, but that would waste
# time).
- if ( ref $autogenerated{$name} ) { # Symbol known
- if ( $autogenerated{$name}{"_symbol type"} ne $group ) { # But changed grp.
- # The good entry is already in symbol_lists (done in wanted()), we
- # only need to remove this invalid one here.
- @{$symbol_lists{$group} } = grep{!/^$name$/} @{ $symbol_lists{$group}};
-
- # XXX In a new system, add file pathname change to NOTES section.
-
- # And correct the field (we can't simply let through to regenerate
- # the skeleton because that would delete previous "available in"
- # information):
- $autogenerated{$name}{"_symbol type"} = $group;
- $autogenerated{$name}{"symbol type"} = "&SYMBOL_" . uc($group) . ";",
- }
- return
- }
+
+ # TODO: Move some of this to the above code that calls process_symbol() ?
+ #if ( ref $autogenerated{$group}{$name} ) { # Symbol known
+ # if ( $autogenerated{$group}{$name}{"_symbol type"} ne $group ) { # But changed grp.
+ # # The good entry is already in symbol_lists (done in wanted()), we
+ # # only need to remove this invalid one here.
+ # @{$symbol_lists{$group} } = grep{!/^$name$/} @{ $symbol_lists{$group}};
+ # # XXX In a new system, add file pathname change to NOTES section.
+ # # And correct the field (we can't simply let through to regenerate
+ # # the skeleton because that would delete previous "available in"
+ # # information):
+ # $autogenerated{$name}{"_symbol type"} = $group;
+ # $autogenerated{$name}{"symbol type"} = "&SYMBOL_" . uc($group) . ";",
+ # }
+ # return
+ #}
# Make skel
- $autogenerated{$name} = {
+ $autogenerated{$group}{$name} = {
name => $name,
id => $name,
"_symbol type" => $group,
@@ -603,19 +615,23 @@
};
# Suplement with information from a control file
- populate($autogenerated{$name}, $name, 'control', 'override');
- populate($autogenerated{$name}, $name, '', 'append');
+ populate($autogenerated{$group}{$name}, $group, $name, 'control', 'override');
+ populate($autogenerated{$group}{$name}, $group, $name, '', 'append');
}
# XXX support reading from refs/<name> file.
sub populate {
- my ($ref, $name, $file, $mode) = @_;
+ my ($ref, $group, $name, $file, $mode) = @_;
+
+ my $specpath = "refs/$name.$group"; # Specific path
+ my $genpath = "refs/$name"; # Generic path (no type visible in it)
+ my $refpath = -e $specpath ? $specpath : $genpath; # USE THIS FOR PATHNAME
# From one specific file (control file usually)
if ( $file ) {
- open IN, "< refs/$name/$file" or do {
+ open IN, "< $refpath/$file" or do {
push @{ $invalid{$name} }, "Requested file '$file' ($!)"
- unless -f "refs/$name";
+ unless -f "$refpath";
return;
};
if ( $file eq 'control' ) {
@@ -633,16 +649,16 @@
# From other file sets
} elsif (! length $file) { # all files
- if ( -d "refs/$name" ) {
- opendir INDIR, "refs/$name/" or do {
- warn "Can't open refs/$name/ ($!)\n";
+ if ( -d "$refpath" ) {
+ opendir INDIR, "$refpath/" or do {
+ warn "Can't open $refpath/ ($!)\n";
return
};
while (my $fn = readdir INDIR) {
next if $fn =~ /^\.|^CVS$/;
next if $fn eq 'control';
- open INF, "< refs/$name/$fn" or
- die "Can't open refs/$name/$fn ($!)\n";
+ open INF, "< $refpath/$fn" or
+ die "Can't open $refpath/$fn ($!)\n";
my $sect = $fn;
@@ -653,9 +669,9 @@
}
closedir INDIR;
- } elsif ( -f "refs/$name" ) {
- open IN, "< refs/$name" or do {
- warn "Can't open refs/$name ($!)\n";
+ } elsif ( -f "$refpath" ) {
+ open IN, "< $refpath" or do {
+ warn "Can't open $refpath ($!)\n";
return
};
my @c = <IN>;
@@ -666,7 +682,7 @@
for my $line (@c) {
if ( $line =~ /^__NAME__ (.+)\s*$/ ) { $section = $1; next }
if ( $line =~ /^__END__/ ) {
- update_field("append", $name, $ref, "refs/$name", $section, $content);
+ update_field("append", $name, $ref, "$refpath", $section, $content);
$section = "";
$content = "";
}
@@ -741,7 +757,7 @@
%hash = %{ $refcache{$dbpath} };
if ( $dumpdb ) {
- print STDERR Dumper \%hash;
+ print STDERR Dumper \%autogenerated;
exit 0;
}
}
More information about the docs
mailing list