[docs] xmldocs - docelic modified 2 files

docs at icdevgroup.org docs at icdevgroup.org
Fri Nov 12 18:47:44 EST 2004


User:      docelic
Date:      2004-11-12 23:47:44 GMT
Modified:  .        Makefile
Modified:  bin      refs-autogen
Log:
Excellent stuff.

Makefile:
 - After s/autodefs/autorefs/.ent and adding auto{glossary,howtos}.ent,
   I forgot to modify Makefile which broke the build. Fixed.

bin/refs-autogen:
 - Placed sub compress_availability() out of another sub, where it was
   placed mistakenly.
 - Removed some commented code that's not going to be used any more
 - Increased Max. Context Reports from 10 to 20
 - Split the FINAL loop that produces the .xml into 2 passes (avoiding
   any kind of chicken-or-egg problem).
 - SEE ALSO sections work again, they're pure joy to look at !:)

Revision  Changes    Path
1.41      +1 -1      xmldocs/Makefile


rev 1.41, prev_rev 1.40
Index: Makefile
===================================================================
RCS file: /var/cvs/xmldocs/Makefile,v
retrieving revision 1.40
retrieving revision 1.41
diff -u -r1.40 -r1.41
--- Makefile	7 Nov 2004 14:53:07 -0000	1.40
+++ Makefile	12 Nov 2004 23:47:44 -0000	1.41
@@ -114,7 +114,7 @@
 
 #############################################################
 # STANDARD TARGETS || two-pass processing method
-$O/%.html: %.xml docbook/autodefs.ent skel
+$O/%.html: %.xml docbook/autorefs.ent docbook/autoglossary.ent docbook/autohowtos.ent skel
 	echo "C     $@"
 	$(PSR) $(PSR_FLAGS)                                                \
 	  $(PROFILE)                                                       \



1.64      +94 -104   xmldocs/bin/refs-autogen


rev 1.64, prev_rev 1.63
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.63
retrieving revision 1.64
diff -u -r1.63 -r1.64
--- refs-autogen	9 Nov 2004 23:16:16 -0000	1.63
+++ refs-autogen	12 Nov 2004 23:47:44 -0000	1.64
@@ -220,8 +220,8 @@
 
 				# 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 ( $ctxshown++ > 10 ) {
+				# see more than 10; let's say 20.
+				if ( $ctxshown++ > 20 ) {
 					print STDERR "$$ag{name} has ", scalar @$ar,
 						" contexts, limiting to $max_ctxs\n" if $verbose;
 					goto DONELOOP;
@@ -313,10 +313,10 @@
 	}
 }
 
-### THIS IS LAST RUN ###
+### THIS IS LAST RUN (Split in multiple loops to avoid chicken-and-egg problem)###
 # Final entry. That's where we add examples
 # (which don't have version-specific data, they're always "latest")
-
+# FINAL / PASS 1
 for my $group ( keys %autogenerated ) {
 while ( my($k,$v) = each %{ $autogenerated{$group} } ) {
 	my %ag = %$v;
@@ -335,46 +335,62 @@
 	# jump out to symbol-specific-subroutine that will handle that.
 	################################################################
 
-	## _See Also_ section: "bidirectional" linking
-	#if ( defined @{ $ag{'_see also'} } ) {
-	#	my $list = $ag{'_see also'};
-	#	@$list = grep {$autogenerated{$group}{$_} and $_ ne $ag{name}} @$list;
-	#	
-	#	for my $sym ( @$list ) {
-	#		my $list2 = $autogenerated{$group}{$sym}{'_see also'};
-	#		push @$list2, @$list, $k;
-	#		{ my %h; @$list2 = grep {!$h{$_}++ and $sym ne $_} @$list2 }
-	#		@{ $autogenerated{$group}{$sym}{'_see also'} } = @$list2;
-	#	}
-	#}
-#
-#	# Turn 'See Also' items to refentries
-#	my @see_items = @{ $ag{'_see also'} };
-#	# XXX only if it's the symbol from same category, otherwise use
-#	# olink to link between documents
-#	for my $itm ( @see_items ) {
-#		next if $itm =~ /^</;
-#		if ( $autogenerated{$group}{$itm} ) {
-#			my $linktype = "link"; # the default, linking inside the same document
-#			my $linkarg = "linkend";
-#			if ( $autogenerated{$group}{$itm}{'_symbol type'} eq
-#				$ag{'_symbol type'} ) {
-#				# Nothing, just use link linkend= if the targets are inside the same
-#				# document.
-#			} else {
-#				# If they're not, find appropriate external document to link to
-#				for my $sect ( keys %symbol_lists ) {
-#					if ( grep {/^$itm$/} @{ $symbol_lists{$sect} } ) {
-#						$linktype = "olink";
-#						$linkarg = "targetdoc='${sect}s' targetptr";
-#					}
-#				}
-#			}
-#			# Now that $linktype and $linkarg are set, make the link/citerefentry
-#			$itm =~ s/^(.+)$/<$linktype $linkarg='$1'><citerefentry><refentrytitle>$1<\/refentrytitle><manvolnum>7ic<\/manvolnum><\/citerefentry><\/$linktype>/;
-#		}
-#	}
-#	$ag{'_see also'} = @see_items;
+	# _See Also_ section: "bidirectional" linking
+	# Interesting how I actually had this very good idea in the beginning, then I commented
+	# it thinking it's crap, and now I'm back to just modifying it a little so it works 
+	# as expected again.
+	if ( defined @{ $ag{'_see also'} } ) {
+		my $list = $ag{'_see also'};
+		my %tmp;
+
+		# This loop is now needed since we added the concept of groups in %autogenerated.
+		for my $gr ( keys %autogenerated ) {
+			$tmp{$_} = $gr for (grep {$autogenerated{$gr}{$_} and $_ ne $ag{name}} @$list);
+		}
+		@$list =keys %tmp;
+		
+		for my $sym ( @$list ) {
+			my $list2 = $autogenerated{$tmp{$sym}}{$sym}{'_see also'};
+			push @$list2, @$list, $k;
+			{ my %h; @$list2 = grep {!$h{$_}++ and $sym ne $_} @$list2 }
+			@{ $autogenerated{$tmp{$sym}}{$sym}{'_see also'} } = @$list2;
+		}
+	}
+}
+}
+# FINAL / PASS 2
+for my $group ( keys %autogenerated ) {
+while ( my($k,$v) = each %{ $autogenerated{$group} } ) {
+	my %ag = %$v;
+
+	# Turn 'See Also' items to refentries
+	goto END_SEEALSO unless $ag{'_see also'};
+	my @see_items = @{ $ag{'_see also'} };
+	# XXX only if it's the symbol from same category, otherwise use
+	# olink to link between documents
+	for my $itm ( @see_items ) {
+		next if $itm =~ /^</;
+		my $linktype = "link";
+		my $linkarg = "linkend";
+		if ( $autogenerated{$group}{$itm} ) {
+			# This means our item and the target it links to are of same type. So, 
+			# nothing, just use default link/linkend=
+		} else {
+			# If they're not, find appropriate external document to link to
+			for my $sect ( keys %symbol_lists ) {
+				if ( grep {/^$itm$/} @{ $symbol_lists{$sect} } ) {
+					$linktype = "olink";
+					$linkarg = "targetdoc='${sect}s' targetptr";
+				}
+			}
+		}
+		## Now that $linktype and $linkarg are set, make the link/citerefentry
+		$itm or warn "NO ITM???\n";
+		$itm =~ s/^(.+)$/<$linktype $linkarg='$1'><citerefentry><refentrytitle>$1<\/refentrytitle><manvolnum>7ic<\/manvolnum><\/citerefentry><\/$linktype>/;
+	}
+	$ag{'_see also'} = @see_items;
+	$ag{'see also'} = join ", ", @see_items;
+	END_SEEALSO:
 
 	# Finally, set default values if they weren't overriden by real information
 	for my $field (@page_order) {
@@ -452,41 +468,6 @@
 }
 }
 
-sub compress_availability {
-	my @avails = my @orig = @{ (shift) };
-	@avails or die "compress_availability(): Shouldn't happen";
-
-	# XXX this needs work, but at the moment it serves us well
-	# (it can't handle like x-y, z, a-b. It only handles start-end)
-
-	my $start = shift @avails;
-	my $si; # starting index
-	my $cl = 0; # compress level
-	for (my $i=0; $i<@parsed_versions;$i++) {
-		if ( $parsed_versions[$i] eq $start ) {
-			$si = $i;
-		}
-	}
-	my $end;
-	while ( $_ = shift @avails ) {
-		if ( $parsed_versions[++$si] eq $_ ) {
-			$end = $_;
-			$cl++;
-		} else {
-			unshift @avails, $_;
-			last
-		}
-	}
-	local $" = ", ";
-	if ( $cl > 1 ) {
-		unshift @avails, "$start-$end";
-		return "@avails"
-	} else {
-		return "@orig"
-	}
-}
-
-
 # Produce reference sets (docbook element Reference contains RefEntries)
 for my $group ( keys %symbols ) {
 	# Prepare reference page
@@ -741,21 +722,12 @@
 			( my $list = $content ) =~ s/,/ /g;
 			my @list = split /\s+/, $list;
 			@{ $$sref{'_see also'} } = @list;
-			#push @{ $$sref{'_see also'} }, @list;
-			#$$sref{'see also'} = join ", ", @{$$sref{'_see also'}};
 		}
 
 	} else { # "Missing" section
 		my @missing_list = split /\n/, $content;
 		push @{ $invalid{$name} }, $_ for @missing_list
 	}
-
-	# Older code
-	#if ( $mode eq 'override' ) {
-	#	$$sref{$sect} = $content;
-	#} elsif ( $mode eq 'append' ) {
-	#	$$sref{$sect} .= $content;
-	#}
 }
 
 sub loaddb {
@@ -774,6 +746,40 @@
 	%hash = %{ $refcache{$dbpath} };
 }
 
+sub compress_availability {
+	my @avails = my @orig = @{ (shift) };
+	@avails or die "compress_availability(): Shouldn't happen";
+
+	# XXX this needs work, but at the moment it serves us well
+	# (it can't handle like x-y, z, a-b. It only handles start-end)
+
+	my $start = shift @avails;
+	my $si; # starting index
+	my $cl = 0; # compress level
+	for (my $i=0; $i<@parsed_versions;$i++) {
+		if ( $parsed_versions[$i] eq $start ) {
+			$si = $i;
+		}
+	}
+	my $end;
+	while ( $_ = shift @avails ) {
+		if ( $parsed_versions[++$si] eq $_ ) {
+			$end = $_;
+			$cl++;
+		} else {
+			unshift @avails, $_;
+			last
+		}
+	}
+	local $" = ", ";
+	if ( $cl > 1 ) {
+		unshift @avails, "$start-$end";
+		return "@avails"
+	} else {
+		return "@orig"
+	}
+}
+
 sub O { print "@_\n"; print STDOUT "@_\n" if $verbose }
 
 
@@ -848,14 +854,6 @@
 <para>$ag{"author"}</para>
 </refsect1>
 
-<!-- Removed because copyright is seen in Source (first few lines),
-     and the generated document starts with copyright notice
-<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>
@@ -1011,14 +1009,6 @@
 <title>AUTHORS</title>
 <para>$ag{"author"}</para>
 </refsect1>
-
-<!-- Removed because copyright is seen in Source (first few lines),
-     and the generated document starts with copyright notice
-<refsect1 id='$ag{"name"}_copyright'>
-<title>COPYRIGHT</title>
-$ag{"copyright"}
-</refsect1>
--->
 
 <refsect1 id='$ag{"name"}_seeAlso'>
 <title>SEE ALSO</title>








More information about the docs mailing list