[docs] xmldocs - docelic modified 4 files

docs at icdevgroup.org docs at icdevgroup.org
Thu Feb 17 18:11:31 EST 2005


User:      docelic
Date:      2005-02-17 23:11:31 GMT
Modified:  bin      refs-autogen
Modified:  docbook  literals.ent
Added:     bin      findtagopts
Added:     refs     xml-generator
Log:
Small fixes/additions before the big commit

Revision  Changes    Path
1.83      +2 -2      xmldocs/bin/refs-autogen


rev 1.83, prev_rev 1.82
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.82
retrieving revision 1.83
diff -u -r1.82 -r1.83
--- refs-autogen	2 Feb 2005 11:35:58 -0000	1.82
+++ refs-autogen	17 Feb 2005 23:11:31 -0000	1.83
@@ -677,7 +677,7 @@
 
   <partintro>
   <para>
-	<phrase condition='online'>[restrict log='none']</phrase>
+	<phrase condition='online'>[restrict log=none]</phrase>
   $preamble{$group}
   </para>
   </partintro>
@@ -920,7 +920,7 @@
 				# __NAME__ section name: section title
 				# The 'title' part will be automatically wrapped in a 
 				# <title> element.
-				if ( $line =~ /^__NAME__\s+(.+)\s*$/ ) {
+				if ( $line =~ /^__NAME__\s+(.+?)\s*$/ ) {
 					# Support for this exists only in this format, it's not
 					# supported in control files or name/*. And fortunately, since
 					# we didn't modify the templates to do this trick, those old files



1.1                  xmldocs/bin/findtagopts


rev 1.1, prev_rev 1.0
Index: findtagopts
===================================================================
#! /usr/bin/perl

# docelic at icdevgroup.org

# The script parses cache files made by bin/stattree, and generates
# the refs/*.xml files.

use warnings;
use strict;
use File::Find;
use Data::Dumper;
use Getopt::Long;
use Storable qw/nstore_fd fd_retrieve/;
use Fcntl qw/:DEFAULT :flock/;

{ no warnings;
$Data::Dumper::Indent = 1;
$Data::Dumper::Terse++;
$Data::Dumper::Sortkeys++;
$ENV{XMLDOCS_CUR_DEVEL} ||= "";
}

my $dumpdb = 0;
my $verbose = 0;
my $OUTPUT = "OUTPUT";
my %refcache; # memory cache of Storable files. Not really needed but I 
              # copied old code which had it, so ...
my %hash; # complete tree data for each IC version we parse
my $cachedir = $ENV{CACHE} || "cache";

unless ( GetOptions ( 
	"verbosedb|dumpdb|d!" => \$dumpdb,
	"verbose|v!" => \$verbose,
)) { die "Error parsing options\n" }

@ARGV or die "Usage: $0 <tagname>\n";

loaddb("$cachedir/cvs-head/.cache.bin");

my $tagname = shift;

my $true_head= "__NAME__ synopsis";
my $true_foot = "\n&ROW_INTERPOLATE_0;\n&ROW_REPARSE_1;\n__END__";
 
my $head = "
<row>
";
my $foot = "
</row>";

my $itm = '"
	<entry>
	$option
	</entry>
	<entry>
	<!-- POS -->
	</entry>
	<entry>
	<!-- REQ -->
	</entry>
	<entry>
	<!-- DFL -->
	</entry>
	<entry>
	<!-- DSC -->
	</entry>
"';

my @options;
my %seen;

for my $p (qw/systemtag usertag uitag/) {
	my $ref = $hash{symbols}{$p};
	#if ( $$ref{$tagname} ) {
	#	@{$$ref{$tagname}} == 1 or do {
	#		warn "Multiple contexts for $tagname\n";
	#		print Dumper $$ref{$tagname};
	#		exit 1;
	#	}
	#}


	next unless $$ref{$tagname};

	my $at_least_one_opt = 0;
	for (@{$$ref{$tagname}}) {
		my @source = @{ $$_{ctx} };
		for (@source) {
			$at_least_one_opt++ if /\$opt/;
			while ( s/\$opt->\{(.+?)\}// ) {
				my $option = $1;
				push @options, $head . eval($itm) . $foot
					unless ( $option =~ /^\$/ or $seen{$option}++ )
			}
			while ( s/\$\$opt\{(.+?)\}// ) {
				my $option = $1;
				push @options, $head . eval($itm) . $foot
					unless ( $option =~ /^\$/ or $seen{$option}++ )
			}
		}
	}
	unless ($at_least_one_opt) {
		print STDERR "$tagname doesn't use \$opt ?\n";
	}
}

@options and do { unshift @options, $true_head; push @options, $true_foot };


print "@options";


exit 0;

#################################################################
# Helpers below

sub loaddb {
	my $dbpath = shift;

	unless ( exists $refcache{$dbpath} ) {
		open( IN, "< $dbpath") or
			die "Can't open database ($dbpath) ($!).\n";
		flock( IN, LOCK_SH ) or
			die "Can't shared-lock database ($dbpath) ($!).\n";
		$refcache{$dbpath} = fd_retrieve( \*IN );
		close IN or
			die "Can't properly close database ($dbpath) ($!).\n";
	}

	%hash = %{ $refcache{$dbpath} };
}


sub O { print "@_\n"; print STDOUT "@_\n" if $verbose }





1.25      +4 -12     xmldocs/docbook/literals.ent


rev 1.25, prev_rev 1.24
Index: literals.ent
===================================================================
RCS file: /var/cvs/xmldocs/docbook/literals.ent,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -r1.24 -r1.25
--- literals.ent	2 Feb 2005 11:35:58 -0000	1.24
+++ literals.ent	17 Feb 2005 23:11:31 -0000	1.25
@@ -96,9 +96,7 @@
 <!ENTITY ROW_INTERPOLATE_0 "
 <row>
 	<entry>
-		<group choice='opt'>
-			<arg choice='plain'>interpolate</arg>
-		</group>
+		<arg choice='plain'>interpolate</arg>
 	</entry>
 	<entry></entry><entry></entry>
 	<entry>0</entry>
@@ -108,9 +106,7 @@
 <!ENTITY ROW_INTERPOLATE_1 "
 <row>
 	<entry>
-		<group choice='opt'>
-			<arg choice='plain'>interpolate</arg>
-		</group>
+		<arg choice='plain'>interpolate</arg>
 	</entry>
 	<entry></entry><entry></entry>
 	<entry>1</entry>
@@ -120,9 +116,7 @@
 <!ENTITY ROW_REPARSE_0 "
 <row>
 	<entry>
-		<group choice='opt'>
-			<arg choice='plain'>reparse</arg>
-		</group>
+		<arg choice='plain'>reparse</arg>
 	</entry>
 	<entry></entry><entry></entry>
 	<entry>0</entry>
@@ -132,9 +126,7 @@
 <!ENTITY ROW_REPARSE_1 "
 <row>
 	<entry>
-		<group choice='opt'>
-			<arg choice='plain'>reparse</arg>
-		</group>
+		<arg choice='plain'>reparse</arg>
 	</entry>
 	<entry></entry><entry></entry>
 	<entry>1</entry>



1.1                  xmldocs/refs/xml-generator


rev 1.1, prev_rev 1.0
Index: xml-generator
===================================================================

__NAME__ purpose
export selected Interchange session information as XML data
__END__

__NAME__ notes
It appears that the <literal>type=delimited</literal> and
<literal>field_names=</literal> do not function properly. This is,
however, not a problem because &tag-xml-generator; is obsolete. If you
use it, you can you can still achieve the same functionality by using
<literal>type=<replaceable>field_name</replaceable></literal>.
</para><para>
In any case, if you verify the problem and supply a patch, we'd be
glad to accept it.
<!-- TODO ^^^ if anyone wants to play with this -->
__END__

__NAME__ synopsis
<row>
<entry>type</entry>
<entry>Yes</entry>
<entry></entry>
<entry><literal>delimited</literal></entry>
<entry>
If set to <literal>delimited</literal>, then
<arg choice='plain'>field_names</arg> specifies the list of values to extract
from the session.
If <emphasis role='bold'>not</emphasis>
<literal>delimited</literal>, acts as a hash reference into the
user's session.
Examples are good known session elements, such as &glos-value;s or
&glos-scratch; variables, <literal>errors</literal>, or any other session
key, such as <literal>source</literal>
</entry>
</row>

<row>
<entry>field_names</entry>
<entry></entry>
<entry></entry>
<entry>none</entry>
<entry>
Field names from the users' session to extract and display as XML
</entry>
</row>

<row>
<entry>
toplevel_tag
</entry>
<entry></entry>
<entry></entry>
<entry>
<literal>table</literal> for the type <literal>delimited</literal>,
<literal>session</literal> otherwise
</entry>
<entry>
The toplevel tag name to create
</entry>
</row>

<row>
<entry>table_name</entry>
<entry></entry>
<entry></entry>
<entry>none</entry>
<entry>
A <literal>name=</literal> attribute (if any) to append to the generated
&glos-HTML; &lt;table&gt; element. This is only used with type
<literal>delimited</literal>. Example output is
<literal>&lt;table name="<replaceable>name</replaceable>"&gt;</literal>
</entry>
</row>

<row>
<entry>attributes</entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry>
Attributes, if any, to pass on to the top level XML tag. See 
<xref linkend="xml-generator_examples"/> for clarification
</entry>
</row>

<row>
<entry>no_second</entry>
<entry></entry>
<entry></entry>
<entry>false</entry>
<entry>
Prevents the second-level of XML tags from being generated
</entry>
</row>


<row>
<entry>separator</entry>
<entry></entry>
<entry></entry>
<entry>
</entry>
</row>

<row>
<entry>delimiter</entry>
<entry></entry>
<entry></entry>
<entry>
</entry>
</row>

<row>
<entry>joiner</entry>
<entry></entry>
<entry></entry>
<entry>
</entry>
</row>

<row>
<entry>spacer</entry>
<entry></entry>
<entry></entry>
<entry>
</entry>
</row>




<row>
<entry>dbdump</entry>
<entry></entry>
<entry></entry>
<entry>false</entry>
<entry>
</entry>
</row>
<row>
<entry>field_tag</entry>
<entry></entry>
<entry></entry>
<entry><literal>field</literal></entry>
<entry>
</entry>
</row>
<row>
<entry>record_tag</entry>
<entry></entry>
<entry></entry>
<entry><literal>record</literal></entry>
<entry>
</entry>
</row>
<row>
<entry>skip_empty</entry>
<entry></entry>
<entry></entry>
<entry>false</entry>
<entry>
</entry>
</row>
<row>
<entry>key_name</entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry>
</entry>
</row>


&ROW_INTERPOLATE_0;
&ROW_REPARSE_1;
__END__

__NAME__ description
This tag converts &IC; session information (stored inside &PERL; structures)
to XML output.
</para><para>
It accepts a list of records (delimited by TAB, separated by newline, by
default), for example those generated by &tag-item-list;, &tag-sql; or
&tag-loop; tags.
</para><para>
If the value passed to the <arg choice='plain'>session</arg> argument
is a hash reference, it will be XML-ified having <literal>session</literal>
as top element, and the actual value just beneath it at second level.
</para><para>
It is possible to show only subsets of complete hashes. To dump only 
first and last name from the &glos-value;s space, use the following 
snippet in the actual call to &tag-xml-generator;:
<code>type=values values="fname lname"</code>.
__END__

__NAME__ example: Dump first and last name to XML
<programlisting>
[comment]
  The following two fields are set manually only to complete the example,
  users are expected to define those values themselves.
[/comment]

[value name=fname set=Ivan  hide=1]
[value name=lname set=Novak hide=1]

[xml-generator type=values values="fname lname" /]
</programlisting>

would generate:

<programlisting><![CDATA[
<session>
  <values>
    <fname>Ivan</fname>
    <lname>Novak</lname>
  </values>
</session>
]]></programlisting>
__END__

__NAME__ example: Dump a single value to XML
<programlisting>
[comment]
	The following field is set manually only to complete the example,
	users are expected to define those values themselves.
[/comment]

[value name=cybercash_id set=12345  hide=1]

[xml-generator type=cybercash_id /]
</programlisting>

would generate:

<programlisting><![CDATA[
<session>
  <cybercash_id>[data session cybercash_id]</cybercash_id>
</session>
]]></programlisting>
__END__



__NAME__ example: Change the toplevel element name, and suppress creation of the second-level one
In this example, the top level element <literal>session</literal> is 
replaced with <literal>dataset</literal>, and the 3rd level appears
as second level, because the 2nd level tags will be suppressed.
<programlisting>
  [xml-generator
    toplevel_tag=dataset
    no_second=1

    type="values scratch"
          values="fname lname"
                 scratch=downloads /]
</programlisting>

would, depending on the exact values in the users' session, generate:

<programlisting><![CDATA[
<dataset>
  <fname>Ivan</fname>
  <lname>Novak</lname>
  <downloads>0</downloads>
</dataset>
]]></programlisting>
__END__





__NAME__ example: A complete example, combination of all features
<programlisting>
[xml-generator

  attributes="date_orig date_update"
  date_orig="05-Mar-2000"
  date_update="[tag time]%d-%b-%Y[/tag]"

  type="values scratch source"
	      values="fname lname"
               scratch=downloads /]
</programlisting>

would, depending on the exact values in the users' session, generate:

<programlisting><![CDATA[
<session date_orig="05-Mar-2000" date_update="05-Feb-2005">
  <values>
    <fname>Ivan</fname>
    <lname>Novak</lname>
  </values>
  <scratch>
    <downloads>0</downloads>
  </scratch>
  <source>Partner1</source>
</session>
]]></programlisting>
__END__



**** Notice the missing _ at the beginning, this is effectively a comment.
_NAME__ example: Display an individual field
We rely on the default setting of <literal>type=delimitea</literal>d here:
<programlisting>
[comment]
	The following field is set manually only to complete the example,
	users are expected to define those values themselves.
[/comment]

[value name=source set=Partner1  hide=1]


  [xml-generator
    toplevel_tag=dataset
    no_second=1

    field_names=source /]
</programlisting>

would, depending on the exact values in the users' session, generate:

<programlisting><![CDATA[
<dataset>
  <source>Partner1</source>
</dataset>
]]></programlisting>
_END__








More information about the docs mailing list