[docs] xmldocs - docelic modified 3 files

[docs at icdevgroup.org]

User:      docelic
Date:      2004-09-24 12:05:09 GMT
Modified:  .        TODO
Modified:  bin      refs-autogen
Added:     refs     var
Log:
- bin/refs-autogen: don't warn about missing 'refs/NAME/control' file if
  refs/NAME itself is a file and all documentation is in there.

- refs/var: documented [var]

- TODO: items

Revision  Changes    Path
1.22      +5 -0      xmldocs/TODO


rev 1.22, prev_rev 1.21
Index: TODO
===================================================================
RCS file: /var/cvs/xmldocs/TODO,v
retrieving revision 1.21
retrieving revision 1.22
diff -u -r1.21 -r1.22
--- TODO	22 Sep 2004 09:02:47 -0000	1.21
+++ TODO	24 Sep 2004 12:05:09 -0000	1.22
@@ -17,6 +17,11 @@
   - at the top where describing IC, mention it's built on Perl and ITL
   - replace <tag> with <code> where putting tag alone in the source would work.
   - explain syntax accepted in profile files
+  - Fix ImageDir and include one picture for example
+
+- refresh docbook/item-skel/* and provide support for one-file docs in
+  bin/editem
+- in source contexts, wrap runaway lines
 
 DOCUMENTATION SYSTEM:
 - copy the definition for <example> to a



1.32      +29 -22    xmldocs/bin/refs-autogen


rev 1.32, prev_rev 1.31
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.31
retrieving revision 1.32
diff -u -r1.31 -r1.32
--- refs-autogen	22 Sep 2004 09:02:47 -0000	1.31
+++ refs-autogen	24 Sep 2004 12:05:09 -0000	1.32
@@ -455,7 +455,8 @@
 	# From one specific file (control file usually)
 	if ( $file ) {
 		open IN, "< refs/$name/$file" or do {
-			push @{ $invalid{$name} }, "Requested file '$file' ($!)";
+			push @{ $invalid{$name} }, "Requested file '$file' ($!)"
+				unless -f "refs/$name";
 			return;
 		};
 		if ( $file eq 'control' ) {
@@ -464,23 +465,8 @@
 				chomp $line;
 				$line =~ s/^\s+//;
 				my ($sect,$text) = split /\s*:\s*/, $line, 2;
-				goto SDONE if (!( defined $text and length $text ));
-				if ( $sect ne 'missing' ) {
-					if ( $mode eq 'override' ) {
-						$$ref{lc $sect} = $text;
-					} else {
-						$$ref{lc $sect} .= '</para><para>' . $text;
-					}
-					if ( $sect =~ /^see also$/i ) {
-						( my $list = $text ) =~ s/,/ /g;
-						my @list = split /\s+/, $list;
-						push @{ $$ref{'_see also'} }, @list;
-						$$ref{'see also'} = join ", ", @{$$ref{'_see also'}};
-					}
-				} else {
-					push @{ $invalid{$name} }, $text;
-				}
-				SDONE:
+				update_field($mode, $name, $ref, $file, $sect, $text)
+					if ( defined $text and length $text );
 			}
 		}
 		close IN;
@@ -517,6 +503,7 @@
 			close IN;
 
 			my ( $section, $content );
+			# XXX check if it's empty, then don't update
 			for my $line (@c) {
 				if ( $line =~ /^__NAME__ (.+)\s*$/ ) { $section = $1; next }
 				if ( $line =~ /^__END__/ ) {
@@ -524,6 +511,8 @@
 					$section = "";
 					$content = "";
 				}
+
+				# Update record
 				$content .= $line if $section;
 			}
 
@@ -547,11 +536,29 @@
 		push @{ $invalid{$name} }, "Section '$sect' from file '$fn' won't be used (name not recognized)";
 	}
 
-	if ( $mode eq 'override' ) {
-		$$sref{$sect} = $content;
-	} elsif ( $mode eq 'append' ) {
-		$$sref{$sect} .= $content;
+	if ( $sect ne 'missing' ) {
+		if ( $mode eq 'override' ) {
+			$$sref{lc $sect} = $content;
+		} else {
+			# Causes problems
+			#$$sref{lc $sect} .= $$sref{lc $sect} ?
+			#	'</para><para>' . $content : $content;
+			$$sref{lc $sect} .= $content;
+		}
+		if ( $sect =~ /^see also$/i ) {
+			( my $list = $content ) =~ s/,/ /g;
+			my @list = split /\s+/, $list;
+			push @{ $$sref{'_see also'} }, @list;
+			$$sref{'see also'} = join ", ", @{$$sref{'_see also'}};
+		}
 	}
+
+	# Older code
+	#if ( $mode eq 'override' ) {
+	#	$$sref{$sect} = $content;
+	#} elsif ( $mode eq 'append' ) {
+	#	$$sref{$sect} .= $content;
+	#}
 }
 
 sub loaddb {



1.1                  xmldocs/refs/var


rev 1.1, prev_rev 1.0
Index: var
===================================================================
__NAME__ purpose
access global and catalog variables
__END__


__NAME__ synopsis
name=<replaceable>variable name</replaceable>
global=<group choice='opt'>
	<arg choice='plain'>1</arg>
	<arg choice='plain'>2</arg>
	</group>
filter=<replaceable>filter name</replaceable>
__END__


__NAME__ see also
env
__END__


__NAME__ description
This tag gives access to Interchange global or catalog variables.
Direct access to variables (using the <code>__VAR__</code> syntax) is
faster, so you should only use this tag where the direct access is
impossible.
</para><para>
Here's the equivalency list:
</para><para>
<code>[var <replaceable>VAR</replaceable>]</code> == 
<code>__<replaceable>VAR</replaceable>__</code>
<sbr/>
<code>[var <replaceable>VAR</replaceable> 1]</code> == 
<code>@@<replaceable>VAR</replaceable>@@</code>
<sbr/>
<code>[var <replaceable>VAR</replaceable> 2]</code> == 
<code>@_<replaceable>VAR</replaceable>_@</code>
__END__


__NAME__ example
<example>
	<title>Direct access equivalency example</title>
	<para>
	Note that the following two lines are identical in effect:
	</para>
	<programlisting>
[image  src="[var IMAGE_DIR]/items/[cgi item_id]" extra="border=0 id=item_img"]
[image  src="__IMAGE_DIR__/items/[cgi item_id]" extra="border=0 id=item_img"]
	</programlisting>
</example>
__END__