[docs] xmldocs - docelic modified bin/refs-autogen
docs at icdevgroup.org
docs at icdevgroup.org
Tue Sep 21 12:08:01 EDT 2004
User: docelic
Date: 2004-09-21 16:08:01 GMT
Modified: bin refs-autogen
Log:
bin/refs-autogen:
- Added some description
- Number of source contexts shown is now limited to 10 (to prevent manpages
from being too long, like it was for MV_PAGE or MV_PREV_PAGE which occured
everywhere)
- Each symbol now has its own template
- File CVS revision (and revision date) included in context reports
- Correctly handle cases where the same symbol was moved to another location
(file/directory) in the source
Revision Changes Path
1.28 +218 -53 xmldocs/bin/refs-autogen
rev 1.28, prev_rev 1.27
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.27
retrieving revision 1.28
diff -u -r1.27 -r1.28
--- refs-autogen 21 Sep 2004 11:40:26 -0000 1.27
+++ refs-autogen 21 Sep 2004 16:08:01 -0000 1.28
@@ -1,5 +1,31 @@
#! /usr/bin/perl
+# docelic at icdevgroup.org
+
+# The script parses cache files made by bin/stattree, and generates
+# the refs/*.xml files.
+# Currently that includes pragmas, globvars, uitags, usertags, systemtags.
+
+# Ok, so this is how the .xml generation process goes:
+#
+# - We first load all templates to $templates{sybol_name}. Each symbol type
+# has its own template (which are specified at the end of this file).
+#
+# - Then for each IC version mentioned on the command line, we:
+# - load the cache file
+# - 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/*/*).
+# - 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)
+# -
use warnings;
use strict;
use Fatal qw/chdir/;
@@ -29,9 +55,10 @@
my %covered; # Weed out duplicate context reports
my %symbol_lists; # symbols listed in categories
my %symbols; # FINAL symbol refentries
-my @template = <DATA>;
+my %templates;
+my $max_ctxs = 10;
-my @page_order = (qw/purpose synopsis description example notes bugs/, "symbol type", "source", "author", "copyright", "see also");
+my @page_order = (qw/purpose default structure synopsis description example notes bugs/, "symbol type", "source", "author", "copyright", "see also");
unless ( GetOptions (
"verbosedb|dumpdb|d!" => \$dumpdb,
@@ -55,7 +82,6 @@
example => "&DEF_EXAMPLE;",
notes => "&DEF_NOTES;",
bugs => "&DEF_BUGS;",
- 'symbol type' => "&DEF_SYMBOLTYPE;",
source => '&DEF_SOURCE;',
author => "&DEF_AUTHOR;",
copyright => "&DEF_COPYRIGHT;",
@@ -63,8 +89,7 @@
purpose => "&DEF_PURPOSE;",
);
-my @mandatory = (qw/synopsis example description purpose/, "symbol type");
-
+my @mandatory = (qw/synopsis example description purpose/);
my $path;
my $dumppath;
@@ -72,27 +97,41 @@
my @paths = @ARGV;
my $lastpath;
-while ( $path = shift @paths) {
+load_templates();
+
+while ( $path = shift @paths) { # For each version specified
$lastpath = $path;
$dumppath = $path;
$i{ver} = $dumppath;
$dumpdir = "$dumppath/";
$dumppath .= "/.cache.bin";
- # Load DB
+ # Load %hash with the cache for particular version (replaces previous one).
+ # (which is OK since the data was extraced and we need previous cache
+ # no more).
loaddb( "$cachedir/$dumppath" );
- # This fills %autogenerated
# Outer loop: symbol types (pragmas, globvars, ...)
# Inner loop: actual symbols
while ( my ($gkey,$gval) = each %{ $hash{symbols} } ) {
- # Let's include tags now, disable the skip
- #next unless $gkey =~ /^(globvar|pragma)$/;
for my $key (keys(%$gval)) {
my $val = $gval->{$key};
+
+ # Register the symbol name ($key) under group name ($gkey) in
+ # %symbol_lists.
push @{ $symbol_lists{$gkey} }, $key
unless grep {/^$key$/} @{ $symbol_lists{$gkey} };
+
+ # Define basic hash for the item ( $autogenerated{<name>} ), and
+ # load values from files. The function returns if
+ # $autogenerated{<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.
+ # ** This fills %autogenerated **
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"} };
@@ -108,28 +147,55 @@
# source section.
my $ag = $autogenerated{$key};
my $ar = $hash{symbols}{ $$ag{"_symbol type"} }{$key};
- if ( $ar and @$ar ) { $$ag{source} = "" }
+
+ if ( $ar ) {$$ag{source} = "" }
+
+ $$ag{"ctxs total"} = scalar @$ar;
+ $$ag{"ctxs shown"} = @$ar < $max_ctxs ? @$ar : $max_ctxs;
+
+ my $ctxcount = 0;
for my $ctx ( @$ar ) {
- my ($fi, $ln, $ctxmeta, $ctxdata) = @$ctx;
- my @ctxsize = split /\s/, $ctxmeta;
+
+ # Make sure we don't overdo it with source contexts.
+ # MV_PAGE appears on like 31 place. We definitely don't need to
+ # see more than 10.
+ if ( $ctxcount++ > $max_ctxs ) { last }
+# my $hidden = @$ar - $max_ctxs;
+# $$ag{source} .= <<ENDD;
+#<para>
+#</para>
+#<para>
+#(With $hidden contexts not shown).
+#</para>
+#ENDD
+
+ my $fi = $$ctx{file};
+ my $ln = $$ctx{lnum};
+
# Support item types with only context info in this field
- my $ctxsize = scalar @ctxsize == 2 ? $ctxsize[1] : $ctxsize[0];
- ( my $ctxpre = $ctxsize ) =~ s/:.+// or
- warn "CTXPRE didnt encounter x:y context ?\n";
- my $loc = "$fi:$ln";
for my $arr ( @{ $covered{$key}{$fi} } ) {
goto DONELOOP if $ln > $$arr[0] and $ln < $$arr[1];
}
- my $ctxsdata = join "\n", @$ctxdata;
+ my $ctxsdata = join "\n", @{ $$ctx{ctx} };
if ( length $ctxsdata ) {
- my $ls = $ln - $ctxpre; # line start nr.
-# XXX when xsltproc gets to support line numbering, add this below: XXX
+ my $ls = $$ctx{ctxs}; # line start nr.
+ ( my $plf = $$ctx{file} ) =~ s#.+?/##;
+ #my $loc = "$$ctx{file}:$$ctx{lnum}";
+ my $loc = $$ctx{file};
+ my $ctxmeta = "Line $$ctx{lnum} (context shows lines " .
+ ( $$ctx{lnum}-$$ctx{ctxpre}) . "-" .
+ ($$ctx{lnum}+$$ctx{ctxpost});
+ $ctxmeta .= " in $$ctx{func}():$$ctx{funclnum}" if $$ctx{funclnum};
+ $ctxmeta .= ")";
+ my $r = $hash{revision}{$plf}->[0];
+ my $d = $hash{revision}{$plf}->[1];
+# XXX when xsltproc gets to support line numbering, add this below:
#<screen linenumbering='numbered' startinglinenumber='$ls'><![CDATA[
$$ag{source} .= <<ENDD;
<para>
</para>
<example>
-<title>$loc ($ctxmeta)</title>
+<title>$loc (rev. $r from $d)<sbr/>$ctxmeta</title>
<screen><![CDATA[
$ctxsdata
@@ -139,8 +205,7 @@
ENDD
$$ag{"source ver"} = $hash{version};
}
- my ($less,$more) = split /:/, $ctxsize;
- push @{ $covered{$key}{$fi} }, [ $ln-$less, $ln+$more ];
+ push @{ $covered{$key}{$fi} }, [ $$ctx{ctxs}, $$ctx{ctxe} ];
DONELOOP:
}
}
@@ -161,18 +226,24 @@
$ag{name} ||= $ag{id} || $k;
$ag{name} = $hash{specific}{$ag{name}}{_name} if
$hash{specific}{$ag{name}}{_name};
+
+ ################################################################
+ # DO STUFF HERE IF IT'S COMMON FOR ALL SYMBOLS. IF it's not,
+ # jump out to symbol-specific-subroutine that will handle that.
+ ################################################################
+
+ # PLUG IN SYMBOL-SPECIFIC STUFF HERE
- # If we're dealing with a TAG, construct its "Default" section:
- # (Which is called "Tag Structure" for tags)
- if ( $ag{"_symbol type"} =~ /tag$/i and !$ag{default} ) {
- my @items;
- while ( my ($x,$y) = each %{ $hash{specific}{ $ag{name} } } ) {
- next unless $x =~ s/^_tagopt_//;
- push @items, "$x $y";
- }
- #$ag{default} = join '</para><para>', @items;
- $ag{default} = join '<sbr/>', @items;
- }
+ ## If we're dealing with a TAG, construct its "Default" section:
+ #if ( $ag{"_symbol type"} =~ /tag$/i and !$ag{default} ) {
+ # my @items;
+ # while ( my ($x,$y) = each %{ $hash{specific}{ $ag{name} } } ) {
+ # next unless $x =~ s/^_tagopt_//;
+ # push @items, "$x $y";
+ # }
+ # #$ag{default} = join '</para><para>', @items;
+ # $ag{default} = join '<sbr/>', @items;
+ #}
# _See Also_ section: "bidirectional" linking
if ( defined @{ $ag{'_see also'} } ) {
@@ -227,16 +298,13 @@
}
- # SYNOPSIS LINE
- #if ( $ag{'_symbol type'} =~ /tag$/ ) {
- # $ag{synopsis} = "[$ag{name} @{ $hash{specific}{$ag{name}}{order} }]";
- #}
-
# DONE
$ag{latest} = $hash{version};
# Expand template
- my $template = join "", @template;
+ my $template = $templates{ $ag{"_symbol type"} };
+ $template or warn "No template $ag{'_symbol type'} ?\n";
+
{ no warnings;
# I simply hate this, I can't find out which field
# is undefined
@@ -289,7 +357,28 @@
sub process_symbol {
my ($group, $name, $ref) = @_;
- return if ref $autogenerated{$name};
+ # XXX: Ok, now, I figured this thing out. Some files changed location
+ # between versions and their type changed, so this fell apart.
+ # ( for example, usertag moved to uitag ).
+ # 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} ) {
+ if ( $autogenerated{$name}{"_symbol type"} ne $group ) {
+ # 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} = {
@@ -297,7 +386,6 @@
id => $name,
"_symbol type" => $group,
"symbol type" => "&SYMBOL_" . uc($group) . ";",
- "_first section" => ( $group =~ /tag$/ ? "TAG STRUCTURE" : "DEFAULT" ),
};
# Suplement with information from a control file
@@ -305,6 +393,7 @@
populate($autogenerated{$name}, $name, '', 'append');
}
+# XXX support reading from refs/<name> file.
sub populate {
my ($ref, $name, $file, $mode) = @_;
@@ -400,7 +489,15 @@
sub O { print "@_\n"; print STDOUT "@_\n" if $verbose }
-__DATA__
+
+#
+# TEMPLATES, SYMBOL-SPECIFIC
+#
+
+sub load_templates {
+
+
+$templates{pragma} = <<'__ENDP__';
<refentry id="$ag{id}">
<refmeta>
@@ -419,8 +516,8 @@
$ag{"synopsis"}
</refsect1>
-<refsect1 id='$ag{"name"}_$ag{"_first section"}'>
-<title>$ag{"_first section"}</title>
+<refsect1 id='$ag{"name"}_default'>
+<title>DEFAULT</title>
<para>$ag{"default"}</para>
</refsect1>
@@ -439,9 +536,75 @@
<para>$ag{"notes"}</para>
</refsect1>
-<refsect1 id='$ag{"name"}_symbolType'>
-<title>SYMBOL TYPE</title>
-$ag{"symbol type"}
+<refsect1 id='$ag{"name"}_availability'>
+<title>AVAILABILITY</title>
+<para>$ag{"name"} is available in Interchange versions:
+</para><para>
+$ag{"available in"}</para>
+</refsect1>
+
+<refsect1 id='$ag{"name"}_source'>
+<title>SOURCE</title>
+<para>Interchange $ag{"source ver"} ($ag{"ctxs shown"}/$ag{"ctxs total"} contexts shown):</para>
+$ag{source}
+</refsect1>
+
+<refsect1 id='$ag{"name"}_authors'>
+<title>AUTHORS</title>
+<para>$ag{"author"}</para>
+</refsect1>
+
+<refsect1 id='$ag{"name"}_copyright'>
+<title>COPYRIGHT</title>
+$ag{"copyright"}
+</refsect1>
+
+<refsect1 id='$ag{"name"}_seeAlso'>
+<title>SEE ALSO</title>
+<para>$ag{"see also"}</para>
+</refsect1>
+
+</refentry>
+__ENDP__
+
+
+$templates{usertag} = <<'__ENDP__';
+<refentry id="$ag{id}">
+
+<refmeta>
+<refentrytitle>$ag{"name"}</refentrytitle>
+<manvolnum>7ic</manvolnum>
+<refmiscinfo class="title">$ag{"name"}</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>$ag{"name"}</refname>
+<refpurpose>$ag{"purpose"}</refpurpose>
+</refnamediv>
+
+<refsect1 id='$ag{"name"}_synopsis'>
+<title>SYNOPSIS</title>
+$ag{"synopsis"}
+</refsect1>
+
+<refsect1 id='$ag{"name"}_structure"}'>
+<title>TAG STRUCTURE</title>
+<para>$ag{"structure"}</para>
+</refsect1>
+
+<refsect1 id='$ag{"name"}_description'>
+<title>DESCRIPTION</title>
+<para>$ag{"description"}</para>
+</refsect1>
+
+<refsect1 id='$ag{"name"}_examples'>
+<title>EXAMPLES</title>
+$ag{"example"}
+</refsect1>
+
+<refsect1 id='$ag{"name"}_notes'>
+<title>NOTES</title>
+<para>$ag{"notes"}</para>
</refsect1>
<refsect1 id='$ag{"name"}_availability'>
@@ -463,11 +626,6 @@
<para>$ag{"author"}</para>
</refsect1>
-<refsect1 id='$ag{"name"}_bugs'>
-<title>BUGS</title>
-$ag{"bugs"}
-</refsect1>
-
<refsect1 id='$ag{"name"}_copyright'>
<title>COPYRIGHT</title>
$ag{"copyright"}
@@ -479,4 +637,11 @@
</refsect1>
</refentry>
+__ENDP__
+
+$templates{globvar} = $templates{pragma};
+$templates{uitag} = $templates{usertag};
+$templates{systemtag} = $templates{usertag};
+
+}
More information about the docs
mailing list