[docs] xmldocs - docelic modified 9 files

Mon Aug 23 13:38:42 EDT 2004

User:      docelic
Date:      2004-08-23 17:38:42 GMT
Modified:  .        TODO
Modified:  bin      refs-autogen stattree
Modified:  cache/cvs-head .cache.bin
Modified:  docbook  xmldocs.css
Modified:  refs/safe_data control notes
Added:     refs/safe_data example-blockwide example-pagewide
Log:
- bin/refs-autogen:
 - added comments
 - minor fixes

- bin/stattree:
 - added comments
 - minor fixes

- cache/cvs-head/.cache.bin:
 - new version

- docbook/xmldocs.css:
 - added body background-color definition

- refs/safe_data/*:
 - added examples
 - added seeAlso item
 - clarified notes

- TODO: items

Revision  Changes    Path
1.10      +8 -6      xmldocs/TODO


rev 1.10, prev_rev 1.9
Index: TODO
===================================================================
RCS file: /var/cvs/xmldocs/TODO,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10

--- TODO	13 Aug 2004 21:09:15 -0000	1.9
+++ TODO	23 Aug 2004 17:38:41 -0000	1.10
@@ -2,12 +2,17 @@
 DOCUMENTATION SYSTEM:
 - Make docbook/symbol-type-skel/* contents of a glossary, and display a 
   glossary entry instead of those files.
-- For tags documentation, have a field if it's a container or not
+- For tags documentation, have a field if it's a container or not (and
+  also honor other tag details found in tag files)
 - bin/stattree, in format_ctx(), see how many spacings all the lines have
-  in common, and trim that.
+  in common, and trim that from the beginning.
 - why in manpage format, comments at the top of the file are messed up (no
   linebreaks)
-- remember which tag had _ instead of - in first UserTag line (email-raw)
+- Seems like there's no CSS selector to make a difference between an Example
+  element title, and Screen element title. (This causes source contexts
+  to be prefixed with "Example: ", although they're technically not).
+- Add support to document tags which are NOT found in separate files
+  (like [restrict]).
 
  Mid-term:
 - Think about adding "online example" (role=html in combination with 
@@ -43,6 +48,3 @@
 </para>
 </epigraph>
 
-
-Old docs:
-docs/retired/icintro.sdf - history, intro, typical user session, security



1.20      +8 -15     xmldocs/bin/refs-autogen


rev 1.20, prev_rev 1.19
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- refs-autogen	14 Aug 2004 08:23:47 -0000	1.19
+++ refs-autogen	23 Aug 2004 17:38:41 -0000	1.20
@@ -43,12 +43,13 @@
 my %longname = (
 	globvar => "Global Variable",
 	pragma => "Pragma",
-	usertag => "User tag",
-	uitag => "UI tag",
-	systemtag => "System tag",
+	usertag => "User Tag",
+	uitag => "User Interface Tag",
+	systemtag => "System Tag",
 );
 
 # General description of symbol types
+# Move to docbook/docbookxi.dtd entities
 my %general_desc;
 opendir DIR, "docbook/symbol-type-skel";
 while ( my $file = readdir DIR ) {
@@ -63,25 +64,15 @@
 # Default fields
 my %defaults = (
 	synopsis => "&DEF_SYNOPSIS;",
-
 	description => "&DEF_DESCRIPTION;",
-
 	example => "&DEF_EXAMPLE;",
-
 	notes => "&DEF_NOTES;",
-	
 	bugs => "&DEF_BUGS;",
-
 	'symbol type' => "&DEF_SYMBOLTYPE;",
-
 	source => '&DEF_SOURCE;',
-
 	author => "&DEF_AUTHOR;",
-	
 	copyright => "&DEF_COPYRIGHT;",
-	
 	'see also' => "&DEF_SEEALSO;",
-
 	purpose => "&DEF_PURPOSE;",
 );
 
@@ -176,13 +167,15 @@
 	my %ag = %$v;
 
 	# Do temporary-only modifications to %ag
+	# At the end of the whole block, save completely generated XML to
+	# %symbols hash.
 
 	# Double check
 	$ag{name} ||= $ag{id} || $k;
 	$ag{name} = $hash{specific}{$ag{name}}{_name} if
 		$hash{specific}{$ag{name}}{_name};
 
-	# See Also "bidirectional" linking
+	# _See Also_ section: "bidirectional" linking
 	if ( defined @{ $ag{'_see also'} } ) {
 		my $list = $ag{'_see also'};
 		@$list = grep {$autogenerated{$_} and $_ ne $ag{name}} @$list;
@@ -256,7 +249,7 @@
 }
 
 
-# Produce reference sets
+# Produce reference sets (docbook element Reference contains RefEntries)
 while (my ($k,$v) = each %symbol_lists ) {
 	# Prepare reference page
 



1.13      +20 -24    xmldocs/bin/stattree


rev 1.13, prev_rev 1.12
Index: stattree
===================================================================
RCS file: /var/cvs/xmldocs/bin/stattree,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- stattree	13 Aug 2004 21:09:15 -0000	1.12
+++ stattree	23 Aug 2004 17:38:41 -0000	1.13
@@ -25,12 +25,13 @@
 # Vars
 my $verbose = 0;
 my $cachedir = $ENV{CACHE} || "cache";
-my %hash;
+my %hash; # Will contain data to be dumped
 my $cpath = $ENV{PWD};
+# Source contexts
 my $ctx_p = 10; # How much context lines to show before
 my $ctx_n = 4; #                                after
 
-# All types should be listed here or the stats wont. It should be
+# All file types should be listed here or the stats wont. It should be
 # reported if an unknown file is found in the archive
 # Order is important. First match wins.
 my %binary_types = (
@@ -58,12 +59,12 @@
 	variable => [qw|/vars/.+ /variables/.+|],
 );
 
+
+# A general overview: how many different contents do we have
 my $binary_types;
 my $ascii_types;
 for ( keys %binary_types ) { $binary_types += scalar @{ $binary_types{$_} } }
 for ( keys %ascii_types ) { $ascii_types += scalar @{ $ascii_types{$_} } }
-
-# A general overview: how many different contents do we have
 $hash{total}{known_types} = $binary_types + $ascii_types;
 $hash{total}{known_binary_types} = $binary_types;
 $hash{total}{known_ascii_types} = $ascii_types;
@@ -76,14 +77,12 @@
 
 @ARGV == 1 or die "Usage: $0 path[/] \n";
 
-# $path is the dir to process, $dumppath is relocated name, say
+# $path is the directory to process, $dumppath is relocated name, say
 # sources/cvs-head becomes output/cvs-head/cache
 my $path = shift;
 ( my $dumppath = $path ) =~ s#.+?/##;
 my $dumpdir = $dumppath;
-my %i = (
-	ver => $dumpdir,
-);
+my %i = ( ver => $dumpdir );
 $i{ver} =~ s/\/$//;
 `mkdir -p $cachedir/$dumpdir` unless -e "$cachedir/$dumpdir";
 $dumppath .= "/.cache.bin";
@@ -158,13 +157,17 @@
 			}
 		}
 	}
-	# Unknown // TODO pay more attention to this
+	# Unknown // TODO pay more attention to this, this should rarely happen,
+	# even if we're not interested in some files, they *should* be matched
+	# in %ascii_types/%binary_types above to provide accurate statistics.
 	print STDERR "$file UNKNOWN\n" if $verbose;
 	return; # We're not interested in handling that
 
 	EXTDONE:
 
-	# ftype, fsubtype and fext are known here
+	# file, ftype, fsubtype and fext are known here.
+	# file is filename, ftype is binary/ascii, fsubtype is key in 
+	# %ascii_types/%binary_types hash, fext is extension
 	$hash{total}{$ftype."_files"}++;
 	$hash{total}{filetypes}{$fsubtype}++;
 	$hash{total}{matches}{$fext}++;
@@ -209,7 +212,8 @@
 			unless ( $hash{version} ) {
 				warn "Wasn't able to determine " .
 					'^ICVERSION=([\'"])(\d+\.\d+\.\d+)\1 from the main ' .
-					"./configure script. Will use one from directory name.\n";
+					"./configure script. Will use one from directory name. " .
+					"(This is OK for pre-5.0 versions).\n";
 				$hash{version} = $i{ver};
 			}
 
@@ -220,6 +224,7 @@
 				$hash{tree}{$file}{comments}++ ;
 				$hash{total}{perl_comments}++;
 				# TODO check if the comment contains ::log[A-Z]\w+
+				# to discover calls to logGlobal/logDebug
 			} elsif ( $line =~ /\s+#/ ) {
 				$hash{tree}{$file}{gray}++ ;
 				$hash{total}{perl_gray}++;
@@ -260,6 +265,7 @@
 					push @{ $hash{symbols}{globvar}{$5} },
 						[ "$i{ver}/$file", $lnum, "$gfunc[0]:$gfunc[1] $ctx_p\:$ctx_n", [format_ctx(@file[$lnum-$ctx_p..$lnum+$ctx_n])] ];
 				}
+				# A little catch
 				if ( $line =~ /\$Tag->var\s*\(\s*(["'])(\S+?)\1(\s*,\s*(\d))?/ ) {
 					push @{ $hash{symbols}{globvar}{$5} },
 						[ "$i{ver}/$file", $lnum, "$gfunc[0]:$gfunc[1] $ctx_p\:$ctx_n", [format_ctx(@file[$lnum-$ctx_p..$lnum+$ctx_n])] ];
@@ -297,7 +303,10 @@
 				[ "$i{ver}/$file", scalar @file, "1:" . scalar @file, [ format_ctx(@file) ] ];
 			# Now, try to autoconstruct tag synopsis
 			my %specific;
+
 			#my $warned;
+			# This is where we parse the tag file. We should discover settings like
+			# HasEndTag, Order, and so on.
 			for my $_l (@file) {
 				next unless $_l =~ /^usertag\s/i;
 				my @lis = split /\s+/, $_l;
@@ -312,19 +321,6 @@
 				#};
 				my $tn = shift @lis;
 
-				# Unfortunately this sucks. Some files contain more tags defined
-				# in them.
-				# code/SystemTag/attr_list.coretag,
-				# code/SystemTag/counter.coretag,
-				# code/SystemTag/counter.coretag,
-				# code/SystemTag/soap.coretag,
-				# code/UI_Tag/jsq.coretag,
-				# code/UserTag/email_raw.tag, 
-				# code/UserTag/forum.tag,
-				# code/UserTag/loc.tag,
-				# We'll deal with them later even though it will cause a small
-				# incaccuracy. Either split to files, or to hack in support for this
-				# in xmldocs tools, that would require more work.
 				#if ( $specific{_name} and ( $specific{_name} ne $tn )) {
 				#	warn "HA! $file, managed to err on $specific{_name}/$tn)\n"
 				#}



1.10      +34304 -1949xmldocs/cache/cvs-head/.cache.bin


rev 1.10, prev_rev 1.9
Index: .cache.bin
===================================================================
RCS file: /var/cvs/xmldocs/cache/cvs-head/.cache.bin,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
Binary files /tmp/cvsFUChJd and /tmp/cvs3psiut differ



1.11      +1 -0      xmldocs/docbook/xmldocs.css


rev 1.11, prev_rev 1.10
Index: xmldocs.css
===================================================================
RCS file: /var/cvs/xmldocs/docbook/xmldocs.css,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- xmldocs.css	13 Aug 2004 21:09:15 -0000	1.10
+++ xmldocs.css	23 Aug 2004 17:38:41 -0000	1.11
@@ -6,6 +6,7 @@
 
 
 /* General */
+body { background-color: #fff; }
 a { text-decoration: none; }
 
 



1.2       +1 -1      xmldocs/refs/safe_data/control


rev 1.2, prev_rev 1.1
Index: control
===================================================================
RCS file: /var/cvs/xmldocs/refs/safe_data/control,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- control	23 Jul 2004 13:32:02 -0000	1.1
+++ control	23 Aug 2004 17:38:42 -0000	1.2
@@ -8,7 +8,7 @@
 #  Just name the related symbols. The system will work everything out.
 #  (Note that if you link some item from here, that item will auto-point
 #  back here (under "indirect links" section))
-see also:
+see also: restrict
 
 # Usually not needed to modify below
 



1.3       +1 -1      xmldocs/refs/safe_data/notes


rev 1.3, prev_rev 1.2
Index: notes
===================================================================
RCS file: /var/cvs/xmldocs/refs/safe_data/notes,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- notes	8 Aug 2004 20:05:25 -0000	1.2
+++ notes	23 Aug 2004 17:38:42 -0000	1.3
@@ -1 +1 @@
-Watch out for parse order with <tag>tag pragma</tag> or <tag>restrict</tag> when used with lists that retrieve data from the database (such as <tag>PREFIX-*</tag> or the flypage). Loops parse before regular tags like <tag>tag</tag> or <tag>restrict</tag>, and are thus not affected by it.
+Watch out for parse order with <tag>tag pragma</tag> or <tag>restrict</tag> when used with lists that retrieve data from the database (such as <tag>PREFIX-*</tag>, <tag>loop</tag>, or the flypage). Loops parse before regular tags like <tag>tag</tag>, and are thus not affected by them (so you must include the whole loop code in the "critical section").



1.1                  xmldocs/refs/safe_data/example-blockwide


rev 1.1, prev_rev 1.0
Index: example-blockwide
===================================================================
<example>

<title>
Enabling safe_data block-wide
</title>

<para>
We'll restrict the available tags to <tag>area</tag> and <tag>page</tag>, and
enclose the critical section in <code>[tag pragma ...]</code>:
</para>

<programlisting><![CDATA[
[tag pragma safe_data]1[/tag]
  ...critical section...
	[restrict area page]
  ...critical section...
	[/restrict]
  ...critical section...
[tag pragma safe_data]0[/tag]
]]></programlisting>

</example>



1.1                  xmldocs/refs/safe_data/example-pagewide


rev 1.1, prev_rev 1.0
Index: example-pagewide
===================================================================
<example>

<title>
Enabling safe_data page-wide
</title>

<para>
Add the following <emphasis>anywhere</emphasis> on an Interchange page:
</para>

<programlisting><![CDATA[
[pragma safe_data]
]]></programlisting>

</example>






