[docs] xmldocs - docelic modified 31 files
docs at icdevgroup.org
docs at icdevgroup.org
Fri Jul 23 09:32:08 EDT 2004
User: docelic
Date: 2004-07-23 13:32:08 GMT
Modified: . Makefile
Modified: bin refs-autogen stattree
Modified: cache/4.6.0 .cache.bin
Modified: cache/4.8.0 .cache.bin
Modified: cache/5.0.0 .cache.bin
Modified: cache/5.2.0 .cache.bin
Modified: cache/cvs-head .cache.bin
Modified: docbook catalog.xml xmldocs.css
Modified: docbook/item-skel control synopsis
Modified: refs/init_page control
Modified: refs/no_html_parse control
Modified: refs/post_page control
Modified: refs/pre_page control
Added: docbook/symbol-type-skel pragma
Added: refs/safe_data control description example notes synopsis
Added: refs/strip_white control description example synopsis
Added: refs/substitute_table_image control description example
Added: notes synopsis
Log:
- Makefile: added tmp/stattrees target
- bin/refs-autogen:
- moved symbol descriptions from %general_desc to separate
files in docbook/symbol-type-skel/*
- made the Source: section contain the source not from the cvs-head, but
from the last version where the symbol appears in
- added a Default: field for items
- bin/stattree:
- context filenames are prefixed with IC version now, this will allow for
auto-linking to the file (lib/Vend/x became <icver>/lib/Vend/x)
- docbook/catalog.xml: adjusted to new naming scheme
- docbook/xmldocs.css: added 10px left padding for .synopsis element
- improved descriptions in docbook/item-skel/*
Revision Changes Path
1.7 +6 -0 xmldocs/Makefile
rev 1.7, prev_rev 1.6
Index: Makefile
===================================================================
RCS file: /var/cvs/xmldocs/Makefile,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- Makefile 21 Jul 2004 20:51:57 -0000 1.6
+++ Makefile 23 Jul 2004 13:32:01 -0000 1.7
@@ -103,6 +103,12 @@
mkdir -p $(LTMPDIR)
+# STATTREE
+tmp/stattrees:
+ -for p in $(IC_VERSIONS); do \
+ ./bin/stattree sources/$$p \
+ ; done
+
#
# Cleanup
#
1.4 +70 -50 xmldocs/bin/refs-autogen
rev 1.4, prev_rev 1.3
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- refs-autogen 23 Jul 2004 11:12:15 -0000 1.3
+++ refs-autogen 23 Jul 2004 13:32:01 -0000 1.4
@@ -46,10 +46,16 @@
);
# General description of symbol types
-my %general_desc = (
- pragma => "Pragmas are.</para><para>Starting with Interchange 5.0, the \$Vend::Cfg->{Pragma}{name} syntax is abandoned in favor of \$::Pragma->{name}.",
- globvar => "Global variables are too.",
-);
+my %general_desc;
+opendir DIR, "docbook/symbol-type-skel";
+while ( my $file = readdir DIR ) {
+ next if $file =~ /^\.|^CVS$/;
+ open INF, "< docbook/symbol-type-skel/$file" or
+ die "Can't open docbook/symbol-type-skel/$file ($!)\n";
+ $general_desc{$file} = join "", <INF>;
+ close INF;
+}
+closedir DIR;
# Default fields
my %defaults = (
@@ -74,7 +80,8 @@
copyright => "2004 Interchange Development Group
</para><para>
- This documentation is free; you can redistribute it and/or modify it
+ This documentation and the source code are free; you can redistribute
+ them and/or modify them
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.",
@@ -91,9 +98,10 @@
my $dumppath;
my $dumpdir;
my @paths = @ARGV;
-my $latest = $paths[$#paths];
+my $lastpath;
while ( $path = shift @paths) {
+ $lastpath = $path;
$dumppath = $path;
$i{ver} = $dumppath;
$dumpdir = "$dumppath/";
@@ -109,78 +117,85 @@
for my $key (sort(keys(%$gval))) {
my $val = $gval->{$key};
push @{ $symbol_lists{$gkey} }, $key
- # ADDER
unless grep {/^$key$/} @{ $symbol_lists{$gkey} };
process_symbol($gkey, $key, $val);
push @{ $autogenerated{$key}{"_available in"} }, $hash{version};
$autogenerated{$key}{"available in"} =
join ", ", @{ $autogenerated{$key}{"_available in"} };
- }
- }
-
- # Final entry. That's where we add source information and examples
- # (which don't have version-specific data, they're always "latest")
- if ( $path eq $latest ) {
- while ( my($k,$v) = each %autogenerated ) {
- my %ag = %$v;
-
- $ag{name} ||= $ag{id} || $k;
-
- for my $field (@page_order) {
- if ( ! $ag{$field} ) {
- if ( grep {/$field/} @mandatory) {
- push @{ $invalid{$k} },
- "Missing field '$field', using unsuitable default";
- }
- $ag{$field} = $defaults{$field};
- }
- }
-
- # Do temporary-only modifications to %ag
- $ag{latest} = $hash{version};
# Prepare source contexts, avoiding those cases
# where a symbol appears multiple times inside the same
# context lines span, but by stattree it gets counted
# as a new context. (which is correct technically, but not
# suitable for display).
- my $ar = $hash{symbols}{ $ag{"_symbol type"} }{$k};
+ #
+ # Having this code in this loop will make all symbols
+ # end up having the last version they appear in displayed in
+ # source section.
+ my $ag = $autogenerated{$key};
+ my $ar = $hash{symbols}{ $$ag{"_symbol type"} }{$key};
+ if ( @$ar ) { $$ag{source} = "" }
for my $ctx ( @$ar ) {
my ($fi, $ln, $ctxsize, $ctxdata) = @$ctx;
my $loc = "$fi:$ln";
- for my $arr ( @{ $covered{$k}{$fi} } ) {
+ for my $arr ( @{ $covered{$key}{$fi} } ) {
goto DONELOOP if $ln > $$arr[0] and $ln < $$arr[1];
}
my $ctxsdata = join "", @$ctxdata;
- $ag{source} .= <<ENDD;
+ if ( length $ctxsdata ) {
+ $$ag{source} .= <<ENDD;
<example>
- <title>$loc ($ctxsize)</title>
-
- <programlisting><![CDATA[
+<title>$loc ($ctxsize)</title>
+
+<programlisting><![CDATA[
$ctxsdata
- ]]></programlisting>
+]]></programlisting>
</example>
ENDD
+ $$ag{"source ver"} = $hash{version};
+ }
my ($less,$more) = split /:/, $ctxsize;
- push @{ $covered{$k}{$fi} }, [ $ln-$less, $ln+$more ];
+ push @{ $covered{$key}{$fi} }, [ $ln-$less, $ln+$more ];
DONELOOP:
}
+ }
+ }
+}
- # Expand template
- my $template = join "", @template;
- { no warnings;
- # I simply hate this, I can't find out which field
- # is undefined
- while ( $template =~ s/(\$ag{.*?})/$1/eem ) {};
+# Final entry. That's where we add source information and examples
+# (which don't have version-specific data, they're always "latest")
+while ( my($k,$v) = each %autogenerated ) {
+ my %ag = %$v;
+
+ $ag{name} ||= $ag{id} || $k;
+
+ for my $field (@page_order) {
+ if ( ! $ag{$field} ) {
+ if ( grep {/$field/} @mandatory) {
+ push @{ $invalid{$k} },
+ "Missing field '$field', using unsuitable default";
}
-
- # Save
- $symbols{$k} = $template;
+ $ag{$field} = $defaults{$field};
}
}
+
+ # Do temporary-only modifications to %ag
+ $ag{latest} = $hash{version};
+
+ # Expand template
+ my $template = join "", @template;
+ { no warnings;
+ # I simply hate this, I can't find out which field
+ # is undefined
+ while ( $template =~ s/(\$ag{.*?})/$1/eem ) {};
+ }
+
+ # Save
+ $symbols{$k} = $template;
}
+
# Produce reference sets
while (my ($k,$v) = each %symbol_lists ) {
# Prepare reference page
@@ -350,6 +365,11 @@
</refsect1>
<refsect1>
+<title>DEFAULT</title>
+<para>$ag{"default"}</para>
+</refsect1>
+
+<refsect1>
<title>DESCRIPTION</title>
<para>$ag{"description"}</para>
</refsect1>
@@ -384,9 +404,9 @@
<refsect1>
<title>SOURCE</title>
-<para>A list of all the places the symbol appears in
-in the current Interchange (cvs-head = $ag{"latest"})
-development tree:</para>
+<para>The current Interchange development version (cvs-head) is $ag{"latest"}.
+The $ag{"name"} symbol last appears in Interchange $ag{"source ver"}, in the
+following contexts:</para>
$ag{source}
</refsect1>
1.6 +3 -3 xmldocs/bin/stattree
rev 1.6, prev_rev 1.5
Index: stattree
===================================================================
RCS file: /var/cvs/xmldocs/bin/stattree,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- stattree 21 Jul 2004 20:13:30 -0000 1.5
+++ stattree 23 Jul 2004 13:32:01 -0000 1.6
@@ -246,17 +246,17 @@
# TODO Here, and 2 places below: make sure if ctx is say, 5:5,
# it always shows that much (that is, workaround file beginning/
# file end problems).
- [ $file, $lnum, "$ctx_p\:$ctx_n", [@file[$lnum-$ctx_p..$lnum+$ctx_n]] ];
+ [ "$i{ver}/$file", $lnum, "$ctx_p\:$ctx_n", [@file[$lnum-$ctx_p..$lnum+$ctx_n]] ];
}
# Diskover global variables
if ( $line =~ /(()|\$())\$Global::Variable(->\2|\3){(\w+?)}/ ) {
push @{ $hash{symbols}{globvar}{$5} },
- [ $file, $lnum, "$ctx_p\:$ctx_n", [@file[$lnum-$ctx_p..$lnum+$ctx_n]] ];
+ [ "$i{ver}/$file", $lnum, "$ctx_p\:$ctx_n", [@file[$lnum-$ctx_p..$lnum+$ctx_n]] ];
}
if ( $line =~ /\$Tag->var\s*\(\s*(["'])(\S+?)\1(\s*,\s*(\d))?/ ) {
push @{ $hash{symbols}{globvar}{$5} },
- [ $file, $lnum, "$ctx_p\:$ctx_n", [@file[$lnum-$ctx_p..$lnum+$ctx_n]] ];
+ [ "$i{ver}/$file", $lnum, "$ctx_p\:$ctx_n", [@file[$lnum-$ctx_p..$lnum+$ctx_n]] ];
warn "\$Tag->var syntax never used in .pl/.pm files by now.
I'll register that, but is it a mistake? ($2, $4)\n";
}
1.2 +1377 -1379xmldocs/cache/4.6.0/.cache.bin
<<.cache.bin: data>>
1.2 +1120 -1120xmldocs/cache/4.8.0/.cache.bin
<<.cache.bin: data>>
1.2 +1468 -1468xmldocs/cache/5.0.0/.cache.bin
<<.cache.bin: data>>
1.2 +1476 -1476xmldocs/cache/5.2.0/.cache.bin
<<.cache.bin: data>>
1.6 +1202 -1202xmldocs/cache/cvs-head/.cache.bin
<<.cache.bin: data>>
1.3 +4 -4 xmldocs/docbook/catalog.xml
rev 1.3, prev_rev 1.2
Index: catalog.xml
===================================================================
RCS file: /var/cvs/xmldocs/docbook/catalog.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- catalog.xml 13 Jul 2004 11:58:59 -0000 1.2
+++ catalog.xml 23 Jul 2004 13:32:02 -0000 1.3
@@ -9,11 +9,11 @@
<public publicId="-//OASIS//DTD DocBook-Interchange XML V4.2//EN"
uri="../docbook/docbookxi.dtd"/>
- <system systemId="iccattut-nochunks-targets"
- uri="iccattut-nochunks-targets.db" />
+ <system systemId="iccattut-nc"
+ uri="../tmp/iccattut-nc.db" />
- <system systemId="iccattut-chunks-targets"
- uri="iccattut-chunks-targets.db" />
+ <system systemId="iccattut-c"
+ uri="../tmp/iccattut-c.db" />
<system systemId="xmldocs.css"
uri="xmldocs.css" />
1.3 +3 -0 xmldocs/docbook/xmldocs.css
rev 1.3, prev_rev 1.2
Index: xmldocs.css
===================================================================
RCS file: /var/cvs/xmldocs/docbook/xmldocs.css,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- xmldocs.css 21 Jul 2004 20:13:30 -0000 1.2
+++ xmldocs.css 23 Jul 2004 13:32:02 -0000 1.3
@@ -22,6 +22,9 @@
font-weight: normal;
}
+.synopsis {
+ padding-left: 10px;
+}
/* Refentry */
.refentry .refnamediv {
1.2 +2 -0 xmldocs/docbook/item-skel/control
rev 1.2, prev_rev 1.1
Index: control
===================================================================
RCS file: /var/cvs/xmldocs/docbook/item-skel/control,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- control 21 Jul 2004 20:55:52 -0000 1.1
+++ control 23 Jul 2004 13:32:02 -0000 1.2
@@ -4,6 +4,8 @@
# purpose: oneline description (MUST FILL IN)
purpose:
+# default value if applicable (make it short, just like: 0, none, ...)
+default:
# Please take time to fill in the See Also line.
# 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
1.2 +4 -1 xmldocs/docbook/item-skel/synopsis
rev 1.2, prev_rev 1.1
Index: synopsis
===================================================================
RCS file: /var/cvs/xmldocs/docbook/item-skel/synopsis,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- synopsis 21 Jul 2004 20:55:52 -0000 1.1
+++ synopsis 23 Jul 2004 13:32:02 -0000 1.2
@@ -7,7 +7,10 @@
<text> - mandatory value
[text] - optional text
- Describe various options inside 'description' file.
+ Where applicable, show syntax in a way which is opposite of the
+ default value.
+
+ Describe various options inside 'description' file, not here.
Delete those comment lines -->
<synopsis><![CDATA[
1.1 xmldocs/docbook/symbol-type-skel/pragma
rev 1.1, prev_rev 1.0
Index: pragma
===================================================================
Pragmas are used to control various aspects of page and data parsing and display.
</para><para>
Pragma values can be defined catalog-wide, page-wide and ITL-block wide.
</para><para>
To define a pragma catalog-wide, use a <filename>catalog.cfg</filename> directive: <synopsis>Pragma NAME</synopsis>
</para><para>
To define a pragma value for a particular page, use the [pragma] tag on a page: <synopsis>[pragma NAME]</synopsis> to enable, or <synopsis>[pragma NAME 0]</synopsis> to disable.
</para><para>
To define a pragma for a small ITL block, enclose the page block in [tag pragma]: <synopsis>[tag pragma NAME]1[/tag]...[tag pragma NAME]0[/tag]</synopsis>
</para><para>
Starting with Interchange 5.0, the \$Vend::Cfg->{Pragma}{name} syntax in the Interchange source is abandoned in favor of \$::Pragma->{name}.
1.2 +1 -0 xmldocs/refs/init_page/control
rev 1.2, prev_rev 1.1
Index: control
===================================================================
RCS file: /var/cvs/xmldocs/refs/init_page/control,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- control 21 Jul 2004 20:24:52 -0000 1.1
+++ control 23 Jul 2004 13:32:02 -0000 1.2
@@ -12,3 +12,4 @@
# leave empty; GPL is the default
copyright:
see also: init_page, pre_page, post_page
+default: none
1.2 +1 -0 xmldocs/refs/no_html_parse/control
rev 1.2, prev_rev 1.1
Index: control
===================================================================
RCS file: /var/cvs/xmldocs/refs/no_html_parse/control,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- control 21 Jul 2004 20:24:52 -0000 1.1
+++ control 23 Jul 2004 13:32:02 -0000 1.2
@@ -20,3 +20,4 @@
author:
# leave empty; GPL is the default
copyright:
+default: 0
1.2 +1 -0 xmldocs/refs/post_page/control
rev 1.2, prev_rev 1.1
Index: control
===================================================================
RCS file: /var/cvs/xmldocs/refs/post_page/control,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- control 21 Jul 2004 20:24:52 -0000 1.1
+++ control 23 Jul 2004 13:32:02 -0000 1.2
@@ -1,2 +1,3 @@
purpose: custom subroutine to run before Image substitution on a page
see also: init_page, pre_page, post_page
+default: none
1.2 +1 -0 xmldocs/refs/pre_page/control
rev 1.2, prev_rev 1.1
Index: control
===================================================================
RCS file: /var/cvs/xmldocs/refs/pre_page/control,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- control 21 Jul 2004 20:24:52 -0000 1.1
+++ control 23 Jul 2004 13:32:02 -0000 1.2
@@ -12,3 +12,4 @@
# leave empty; GPL is the default
copyright:
see also: init_page, pre_page, post_page
+default: none
1.1 xmldocs/refs/safe_data/control
rev 1.1, prev_rev 1.0
Index: control
===================================================================
# The usual comments can be used here.
# To override a field, supply a value
# To let it through unmodified, simply leave the fields empty
# purpose: oneline description (MUST FILL IN)
purpose: allow reparsing of database values in search for Interchange tags
# Please take time to fill in the See Also line.
# 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:
# Usually not needed to modify below
# id: name of the output file (defaults to <name>)
id:
# name: visible name in the pages
name:
# specify person(s). Defaults to icdevgroup
author:
# leave empty; GPL is the default
copyright:
default: 0
1.1 xmldocs/refs/safe_data/description
rev 1.1, prev_rev 1.0
Index: description
===================================================================
By default, Interchange does not allow data returned from databases to be reparsed for Interchange tags. Setting this pragma eliminates the restriction.
</para><para>
If for some reason you want to have tags in your database, for example, to use [page ...] for catalog-internal hyperlinks in your product descriptions, you need to enable safe_data. Some things to consider:
</para><para>
It might be better to use the safe_data attribute available to certain tags instead of setting the pragma, or perhaps to use [pragma] for a whole page or [tag pragma safe_data][/tag] for a small ITL block, instead of a catalog-wide Pragma directive.
</para><para>
In any case, it is strongly recommended that you surround the area with [restrict][/restrict] tags to allow only the specific (hopefully relatively safe) set of tags you expect to appear, such as [page] or [area]. Expect security compromises if you allow [calc] or [perl], or other extremely powerful tags.
</para><para>
Be certain that you absolutely know where the data from your databases will be used. Will it always be possible to reparse for tags? What about when it's used to create an emailed plain-text receipt -- will a literal '[page ...]' tag show up in the product description on the receipt? Would the desired output of <a href="..."> be any better in a plaintext situation? What if you access your database from applications other than Interchange? You'll then have to decide what to do with such tags; perhaps you can simply strip them, but will the missing tag output cause you any trouble?
</para><para>
In short, safe_data is disabled by default for a reason, and you should be very careful if you decide to enable it.
1.1 xmldocs/refs/safe_data/example
rev 1.1, prev_rev 1.0
Index: example
===================================================================
<example>
<title>
Enabling safe_data catalog-wide
</title>
<para>
Add the following to <filename>catalog.cfg</filename>:
</para>
<programlisting><![CDATA[
Pragma safe_data
]]></programlisting>
</example>
1.1 xmldocs/refs/safe_data/notes
rev 1.1, prev_rev 1.0
Index: notes
===================================================================
Watch out for parse order with [tag pragma] or [restrict] when used with lists that retrieve data from the database (such as [PREFIX-*] or the flypage). Loops parse before regular tags like [tag] and [restrict], and thus aren't affected by it.
1.1 xmldocs/refs/safe_data/synopsis
rev 1.1, prev_rev 1.0
Index: synopsis
===================================================================
<synopsis><![CDATA[
Pragma safe_data
]]></synopsis>
1.1 xmldocs/refs/strip_white/control
rev 1.1, prev_rev 1.0
Index: control
===================================================================
# The usual comments can be used here.
# To override a field, supply a value
# To let it through unmodified, simply leave the fields empty
# purpose: oneline description (MUST FILL IN)
purpose: strip whitespace from the top of Interchange-served HTML pages
# Please take time to fill in the See Also line.
# 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:
# Usually not needed to modify below
# id: name of the output file (defaults to <name>)
id:
# name: visible name in the pages
name:
# specify person(s). Defaults to icdevgroup
author:
# leave empty; GPL is the default
copyright:
default: 0
1.1 xmldocs/refs/strip_white/description
rev 1.1, prev_rev 1.0
Index: description
===================================================================
Set this to strip whitespace from the top of HTML pages output by Interchange. Such whitespace usually comes from Interchange tags at the top of the page. The pragma's purpose is mostly to make <emphasis>view source</emphasis> option in a browser a slightly more tolerable experience.
Default is off; whitespace is unchanged.
1.1 xmldocs/refs/strip_white/example
rev 1.1, prev_rev 1.0
Index: example
===================================================================
<example>
<title>
Strip whitespace
</title>
<para>
Simply add the following to <filename>catalog.cfg</filename>
</para>
<programlisting><![CDATA[
Pragma strip_white
]]></programlisting>
</example>
1.1 xmldocs/refs/strip_white/synopsis
rev 1.1, prev_rev 1.0
Index: synopsis
===================================================================
<synopsis><![CDATA[
Pragma strip_white
]]></synopsis>
1.1 xmldocs/refs/substitute_table_image/control
rev 1.1, prev_rev 1.0
Index: control
===================================================================
# The usual comments can be used here.
# To override a field, supply a value
# To let it through unmodified, simply leave the fields empty
# purpose: oneline description (MUST FILL IN)
purpose: substitute background image paths in HTML table elements
# Please take time to fill in the See Also line.
# 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: no_image_rewrite
# Usually not needed to modify below
# id: name of the output file (defaults to <name>)
id:
# name: visible name in the pages
name:
# specify person(s). Defaults to icdevgroup
author: Stefan Hornburg
# leave empty; GPL is the default
copyright:
default: 0
1.1 xmldocs/refs/substitute_table_image/description
rev 1.1, prev_rev 1.0
Index: description
===================================================================
<![CDATA[
Rewrite image background paths in <table>, <tr>, <td>, and <th> tags
according to ImageDir/ImageSecureDir by default.
]]>
1.1 xmldocs/refs/substitute_table_image/example
rev 1.1, prev_rev 1.0
Index: example
===================================================================
<example>
<title>
Enabling table image paths rewriting
</title>
<para>
In the <filename>catalog.cfg</filename> file, add:
</para>
<programlisting><![CDATA[
Pragma substitute_table_images
]]></programlisting>
</example>
1.1 xmldocs/refs/substitute_table_image/notes
rev 1.1, prev_rev 1.0
Index: notes
===================================================================
The substitute_table_image pragma which was added in Interchange 4.6.2
was removed in 4.7, in favor of a general image rewriting system.
1.1 xmldocs/refs/substitute_table_image/synopsis
rev 1.1, prev_rev 1.0
Index: synopsis
===================================================================
<synopsis><![CDATA[
Pragma substitute_table_image
]]></synopsis>
More information about the docs
mailing list