[docs] xmldocs - docelic modified bin/refs-autogen
docs at icdevgroup.org
docs at icdevgroup.org
Fri Jan 21 18:41:11 EST 2005
User: docelic
Date: 2005-01-21 23:41:11 GMT
Modified: bin refs-autogen
Log:
Ok, here's the deal:
- bin/refs-autogen works in a way that it reads symbol names from cache files,
the looks if those symbols are documented by means of a file or directory
of the same name being present in refs/.
This, however, made possible that you would document some stuff in refs/,
but it never got used because bin/stattree didn't find that symbol in
the source, and consequently bin/refs-autogen never looked for it.
(One day, bin/stattree will be able to sneak into all smelly corners of
IC source and find them all, but that's an incremental process).
So for the moment, bin/refs-autogen creates file tmp/unused with a list
of files that are in refs/, but didn't get used. Very useful stuff!
- Fixed missing <sbr/>
- *** Online examples are WORKING! ***
To build docs with support for online examples and see some early success
for yourself, simply do:
PROFILE="--stringparam profile.condition online" make OUTPUT/filters.html
(filters.html is particularily good because I added some online examples
for filters). Then just copy the page to an IC catalog and browse it!
On a side note,
I used [restrict] to completely prevent IC parsing of the page, except for
chunks of online examples where restrict is disabled. However, even using
[restrict log=none] writes tons of violation messages to the log files.
Did I miss something or it's a bug in restrict code?
Revision Changes Path
1.80 +57 -28 xmldocs/bin/refs-autogen
rev 1.80, prev_rev 1.79
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.79
retrieving revision 1.80
diff -u -r1.79 -r1.80
--- refs-autogen 3 Jan 2005 20:41:01 -0000 1.79
+++ refs-autogen 21 Jan 2005 23:41:11 -0000 1.80
@@ -36,6 +36,7 @@
my %templates; # Templates for various symbol types
my $max_ctxs = 20; # Trim more than $max_ctxs source context reports
my @set_missing_all; # Helper to better manage %invalid
+my @set_unused; # Notice which files inside refs/ were not used
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
@@ -154,6 +155,13 @@
load_templates();
+# Read all files in refs/. This will be later used to detect unused
+# files. (Files could be unused if bin/stattree didn't discover their symbol
+# name in the sources).
+opendir DIR, "refs" or die "Can't opendir refs/ ($!)\n";
+ at set_unused = readdir DIR; @set_unused = grep {!/^\.|^CVS$/} @set_unused;
+closedir DIR;
+
while ( $path = shift @paths) { # For each version specified
$lastpath = $path;
$dumppath = $path;
@@ -587,7 +595,7 @@
# The 'structure' field will show which other symbols the current
# symbol uses. Fill it:
if ( $hash{uses}{$group}{$ag{name}} ) {
- $ag{structure} = "This tag appears to be affected by, or affects, the following:\n";
+ $ag{structure} = "This tag appears to be affected by, or affects, the following:<sbr/>\n";
while (my($k,$v)=each %{ $hash{uses}{$group}{$ag{name}} }) {
s/^(.+)$/<$tagname{lc $k}>$1<\/$tagname{lc $k}>/ for @$v;
local $" = ", ";
@@ -656,6 +664,7 @@
<partintro>
<para>
+ <phrase condition='online'>[restrict log='none']</phrase>
$preamble{$group}
</para>
</partintro>
@@ -668,7 +677,8 @@
}
## Close up
- $refpage .= "\n" . '</reference>';
+ $refpage .= "\n" . "<phrase condition='online'>[/restrict]</phrase>" . '</reference>';
+;
# Dump page
my $prefix = ""; #$compounds ? "ic" : "";
@@ -737,6 +747,12 @@
# Boy, did I previously misplace this critical code...
if ( $dumpdb ) { print STDERR Dumper \%autogenerated; exit 0; }
+if (@set_unused) {
+ open OUT, "> tmp/unused";
+ print OUT "UNUSED refs/ FILES ARE:\n", Dumper @set_unused;
+ close OUT;
+}
+
exit 0;
#################################################################
@@ -804,7 +820,17 @@
my $fgroup = $group; $fgroup =~ /tag$/ and $fgroup = 'tag';
my $specpath = "refs/$name.$fgroup"; # Specific path
my $genpath = "refs/$name"; # Generic path (no type visible in it)
- my $refpath = -e $specpath ? $specpath : $genpath; # USE THIS FOR PATHNAME
+ my $refpath; # USE THIS FOR PATHNAME
+
+ # Delete the file from @set_unused array (so that we know the file is USED,
+ # not unused).
+ if ( -e $specpath ) {
+ $refpath = $specpath;
+ @set_unused = grep {!/^$name.$fgroup$/} @set_unused;
+ } else {
+ $refpath = $genpath;
+ @set_unused = grep {!/^$name$/} @set_unused;
+ }
# If symbol name is not unique, then explicit type must be specified.
# (That is, the 'value' symbols needs to have refs/value.tag and
@@ -937,24 +963,27 @@
# fit in .xml
if ( $sect eq 'online' ) {
# # Extract programlistings.. dude! Ok, not as bad-looking as I thought:)
- # my $tmp = $content; my $code = "";
- # while($tmp =~ s#<programlisting>(.*?)</programlisting>##s){$code .= $1}
+ my $tmp = $content; my $code = "";
+ while($tmp =~ s#<programlisting>(.*?)</programlisting>##s){$code .= $1}
- # $code or
- # die "Empty online example for $name (no <programlisting> found)\n";
+ $code or
+ die "Empty online example for $name (no <programlisting> found)\n";
# # Let's see if we'll get away this easy
- # $content .= qq{
- # <programlisting>
- # <textobject>
- # <textdata>
- # [/restrict]
- # $code
- # [restrict]
- # </textdata>
- # </textobject>
- # </programlisting>
- # };
+ $content .= qq{
+<phrase condition='online'>
+<emphasis role='bold'>Example in action:</emphasis>
+</phrase>
+<programlisting>
+<textobject>
+<phrase condition='online'>
+[/restrict]
+$code
+[restrict]
+</phrase>
+</textobject>
+</programlisting>
+};
# And rewrite section to example:
$sect = 'example';
@@ -1042,16 +1071,16 @@
#$ag{"online"}
#</refsect1>
-sub readfile {
- my $file = shift;
- open IN, $file or die "Can't open $file ($!)\n";
- my @slurp = <IN>;
- close IN;
-
- local $" = "";
- wantarray? @slurp : "@slurp"
-}
-
+#sub readfile {
+# my $file = shift;
+# open IN, $file or die "Can't open $file ($!)\n";
+# my @slurp = <IN>;
+# close IN;
+#
+# local $" = "";
+# wantarray? @slurp : "@slurp"
+#}
+#
sub load_templates {
More information about the docs
mailing list