[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