From docs at icdevgroup.org  Sun Apr 10 16:37:22 2005
From: docs at icdevgroup.org (docs@icdevgroup.org)
Date: Sun Apr 10 16:37:27 2005
Subject: [docs] xmldocs - docelic modified 3 files
Message-ID: <200504102037.j3AKbMZn020450@icdevgroup.org>

User:      docelic
Date:      2005-04-10 20:37:21 GMT
Added:     glossary database
Added:     refs     Database NoImport
Log:
We're back on stage :)
New items, updates.

Revision  Changes    Path
1.1                  xmldocs/glossary/database


rev 1.1, prev_rev 1.0
Index: database
===================================================================
In general, databases contain some information, usually in tabular format,
where columns define the names and types of contained data, and rows
represent <emphasis>entries</emphasis> &mdash; database
<emphasis>records</emphasis>.
</para><para>
&IC; is primarily using databases to just retrieve values from specific
tables, and does not use any higher-level functions of RDBM databases
(such as views, triggers, or stored procedures in &PGSQL;).
Such things can, however, be implemented in the database independently 
of &IC;, as Interchange will properly pass any warning or error messages back
and forth.
</para><para>
We should say right away that &IC; is completely database-independent.
The choice of actual database types that can work with Interchange is large,
and &IC; can use some database-like methods automatically when you're not
explicitly interested in paying attention to databases working behind
the scenes.
</para><para>
Common features are transparently available
everywhere (with absolutely no code hacks or special cases required),
regardless of the underlying database type used. In addition, almost no
field names are hard-coded, allowing for unlimited flexibility.
</para><para>
<emphasis role='bold'>
Keep in mind that the terms <literal>database</literal> and 
<literal>database table</literal> actually mean the same thing in &IC; 
parlance - a <literal>database table</literal>.
</emphasis>
</para><para>
&IC; works with GDBM, DB_File, SQL, LDAP and in-memory types of databases. 
Regardless of the type, each database must be registered with &IC; before it's
ready to be used, and this is achieved using the &conf-Database; configuration
directive. Pay special attention to the fact that &conf-Database; is both
catalog and global directive, indicating that you can share databases 
among catalogs.
</para><para>
Three parameters needed to complete the &conf-Database; specification are
an arbitrary database name, text source file with initial content, and the
type of database.
</para>

<section>
	<title>Text Source Files</title>
<para>
Text source files are not databases themselves, of course
(for performance and other reasons); they are only used to provide
<emphasis>initial data</emphasis> for the corresponding database tables.
</para><para>
By default, all database source files are kept in the 
<filename class='directory'>products/</filename> subdirectory of your
&glos-CATROOT;. The &conf-ProductDir; directive controls the exact location.
</para>

<note>
<title>Database updates</title>
<para>
It is important to note that, when using &IC; internal database methods 
(which are some variant of DB_File or DBM, depending on what's available
on your system), changes to text files cause databases to be resynchronized
with plaintext file contents.
</para><para>
This behavior can be controlled via the &conf-NoImport; config directive,
but by default, changes in text files will trigger a 
rewrite of DBM or DB_File databases. This might lead to unexpected problems
if you edit databases from &IC; and don't sync <emphasis>files</emphasis>
with the databases first, or have a larger data sets
(say, over a few thousand records) which take noticeable time to get
re-imported.
</para>
</note>
</section>

<section>
	<title>SQL Databases</title>
<para>
As hinted above, you do not need to use an external SQL database. If you only
have a small data set, you could use Interchange's internal databases.
This is a tremendeous gain for small and quick setups, or &IC; evaluation.
However, some functions (order management, for example) will be slower
and not as robust without an SQL database. SQL is strongly recommended for
at least the <database>state</database>,
<database>country</database>,
<database>orderline</database>,
<database>transactions</database>
and <database>userdb</database> tables. Any other tables that will
have programmed updates, such as <database>inventory</database>, are
also best placed in SQL.
</para>

<note>
<title>Database performance</title>
<para>
Do not, however, fall in the jaws of <ulink url="http://c2.com/cgi/wiki?PrematureOptimization">premature optimisation</ulink>, <ulink url="http://www.flounder.com/optimization.htm">your worst enemy</ulink>.
</para>
</note>

<para>
If you plan on using Interchange Admin UI, you should make the additional 
effort of also configuring SQL databases and switching databases to it.
Admin UI provides easy import routines for text files that should
replace traditional FTP text-file uploads.
</para><para>
Using SQL also makes your data sets easily available for integration with
other applications.
</para><para>
Speaking of the source files' behavior, if a file named
<filename><replaceable>table</replaceable>.sql</filename> is present
in the same directory as
<filename><replaceable>table</replaceable>.txt</filename>, then database
table will not be imported from the ASCII text source file.
If there is no products.sql, the DBI/SQL import will happen once at
&IC; startup or catalog reconfiguration time;
Interchange will connect to the SQL database using the specified DSN
(DNS is a standard DBI parameter meaning "Database Source Name").
The table, if it already exists, will be dropped using a line similar to
<literal>DROP TABLE <replaceable>table</replaceable></literal>.
This will occur without warning, but &conf-NoImport; can be used to 
prevent it or otherwise change the default behavior.
The table will then be created again.
</para><para>
If there are any
<literal>COLUMN_DEF</literal> specifications present in &gcf;, &ccf; or
<filename>products/<replaceable>table</replaceable>.sql</filename>,
they will be used in table specification (which is recommended for clean
and correct database
layout). If there aren't any, however, then the key (first field in the text
file, by default) will be created with the type <literal>char(16)</literal>,
and all other fields will be created as <literal>char(128)</literal>. This is 
very unfortunate, but the best &IC; can do without your help.
Table creation statements will be written to the <filename>error.log</filename>
along with, of course, any errors. From my experience, the most common
mistake at this step is picking column names which happen to be reserved
keywords in &MYSQL;.
</para><para>
Once the &glos-database; (database table actually, remember we said 
"database" and "table" simply mean a "table" in &IC; parlance)
is created, the text source file will be imported into it.
For this step to succeed, data typing must be user-configured. In other words,
if <literal>none</literal> is placed in a field, and the field in question
is defined to be of numeric type, database import will not succeed;
consequently, the problematic catalog won't configure successfully 
(it will be skipped) and it won't be available when &IC; starts up.
</para><para>
For a complete discussion, please see the &conf-Database; configuration
directive.
</para>
</section>

<section>
	<title>*DB* Databases</title>
<para>
By "*DB*" databases we primarily assume Berkeley (DB_File) and GNU DBM. Those
database types usually work in a way that, on every client access, the
appropriate database text source file is checked for being newer than the
actual DB file itself.
When it happens that it is, the database table is re-imported
from the text source file.
</para><para>
For a complete discussion, please see the &conf-Database; configuration
directive.
</para>
</section>

<section>
	<title>Memory Databases</title>
<para>
Memory databases are used by default only if no database type is
explicity specified, and there is no DB_File or gdbm found on
the system. Otherwise they can be used for small but high-traffic
tables. Keep in mind, however, that since their contents are not saved back
to the text files, you'll want to either take care of the data export yourself,
or keep the tables stuffed with read-only data.
</para><para>
As with SQL databases, the import will only be performed once at 
&IC; startup or catalog reconfiguration time.
</para><para>
For a complete discussion, please see the &conf-Database; configuration
directive.
</para>
</section>



<para>



1.1                  xmldocs/refs/Database


rev 1.1, prev_rev 1.0
Index: Database
===================================================================
__NAME__ purpose
register existing database table for use with Interchange
__END__

__NAME__ synopsis
	<arg choice='plain'><replaceable>name</replaceable></arg>
	<arg choice='plain'><replaceable>source_file</replaceable></arg>
	<arg choice='plain'><replaceable>type</replaceable></arg>
__END__

__NAME__ see also
TableRestrict,data,DatabaseDefault
__END__

__NAME__ description
The directive registers a database table for use with &IC;. 
<arg choice='plain'>name</arg> specifies an arbitrary name &mdash; name
that will be used to refer to the table within &IC;. Names can be composed
of alphanumeric characters including underscore, and we recommend they're in
all lower- or upper-case.
<arg choice='plain'>source_file</arg> specifies the initial database
source file, and <arg choice='plain'>type</arg> specifies its format.
</para><para>
For more about &IC; and databases, and supported formats, see &glos-database;
glossary entry.
__END__

__NAME__ notes
In &IC;, words <literal>table</literal> and <literal>database</literal>
are used to refer to the same thing &mdash; database table.
__END__

__NAME__ example: Default, most basic products database
<programlisting>
Database products products.txt TAB
</programlisting>
__END__

__NAME__ example: Simple definition of a CSV-style database source format
<programlisting>
Database reviews reviews.txt CVS
</programlisting>
__END__




1.1                  xmldocs/refs/NoImport


rev 1.1, prev_rev 1.0
Index: NoImport
===================================================================
__NAME__ purpose
do not re-import text source files to databases unless the database disappears
__END__


__NAME__ synopsis
<group choice='req'>
	<arg choice='plain' rep='repeat'><replaceable>table_name</replaceable></arg>
</group>
__END__


__NAME__ description
The directive specifies &glos-database; tables that should not be 
re-imported from the text source files, unless the database disappears
(for example, if the <filename><replaceable>table</replaceable>.gdbm</filename>
is deleted).
__END__

__NAME__ example: Disabling 'products' table import
Put the following in &gcf;:
<programlisting>
NoImport products
</programlisting>
__END__







From docs at icdevgroup.org  Sun Apr 10 18:45:56 2005
From: docs at icdevgroup.org (docs@icdevgroup.org)
Date: Sun Apr 10 18:46:01 2005
Subject: [docs] xmldocs - docelic modified glossary/database
Message-ID: <200504102245.j3AMjuZn022850@icdevgroup.org>

User:      docelic
Date:      2005-04-10 22:45:56 GMT
Modified:  glossary database
Log:
More documentation ported from icdatabase.sdf

Revision  Changes    Path
1.2       +159 -14   xmldocs/glossary/database


rev 1.2, prev_rev 1.1
Index: database
===================================================================
RCS file: /var/cvs/xmldocs/glossary/database,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- database	10 Apr 2005 20:37:21 -0000	1.1
+++ database	10 Apr 2005 22:45:56 -0000	1.2
@@ -49,25 +49,71 @@
 By default, all database source files are kept in the 
 <filename class='directory'>products/</filename> subdirectory of your
 &glos-CATROOT;. The &conf-ProductDir; directive controls the exact location.
+</para><para>
+The ASCII files can have
+<literal>^M</literal> (carriage return) characters, but must have a
+newline character at the end of the line to work. <emphasis role='bold'>
+Mac users uploading files must use ascii mode, not binary mode</emphasis>.
+</para>
+<para>
+Interchange's default ASCII delimiter is TAB. <emphasis role='bold'>Keep in
+mind that the items must be separated by a single delimiter (that is, a single
+TAB by default)</emphasis>. Due to the nature of TABs, TAB-delimited files
+look messy and unaligned when viewed in a text editor. Do not try to fix these;
+better use the <command>te</command> utility that comes as part of the 
+&IC; distribution to edit files more conveniently.
+</para>
+Format examples:
+<itemizedlist>
+	<listitem>
+	<para>TAB-delimited file:
+Fields are separated by TAB characters. No whitespace is allowable
+at the beginning of the line.
 </para>
+<screen>
+code	description	price image
+SH543	Men's fine cotton shirt	14.95	shirts.jpg
+</screen>
+<para>
+Using the default TAB delimiter is recommended if you plan on
+searching the ASCII source file of the database.
+	</para></listitem>
 
-<note>
-<title>Database updates</title>
+	<listitem>
+	<para>PIPE-delimited file:
+Fields are separated by the pipe ("<literal>|</literal>") characters which 
+resemble vertical lines. No whitespace is allowable at the beginning of the
+line.
+</para>
+<screen>
+code|description|price|image
+SH543|Men's fine cotton shirt|14.95|shirts.jpg
+</screen>
 <para>
-It is important to note that, when using &IC; internal database methods 
-(which are some variant of DB_File or DBM, depending on what's available
-on your system), changes to text files cause databases to be resynchronized
-with plaintext file contents.
-</para><para>
-This behavior can be controlled via the &conf-NoImport; config directive,
-but by default, changes in text files will trigger a 
-rewrite of DBM or DB_File databases. This might lead to unexpected problems
-if you edit databases from &IC; and don't sync <emphasis>files</emphasis>
-with the databases first, or have a larger data sets
-(say, over a few thousand records) which take noticeable time to get
-re-imported.
+PIPE-delimited files perform fairly well with ASCII text searching routines.
+	</para></listitem>
+	<listitem>
+	<para>CVS-delimited file:
+Fields are enclosed in quotes and separated by commas. Again, no whitespace
+should be at the beginning of the line.
+</para>
+<screen>
+"code","description","price","image"
+"SH543","Men's fine cotton shirt","14.95","shirts.jpg"
+</screen>
+<para>
+CSV-delimiter schemes might cause problems with ASCII text searching routines.
+	</para></listitem>
+	</itemizedlist>
+
+<note>
+	<para>
+Field names are usually case-sensitive. Use
+consistency when naming or you might encounter problems. All lower or
+all upper case names are recommended.
 </para>
 </note>
+
 </section>
 
 <section>
@@ -155,7 +201,25 @@
 actual DB file itself.
 When it happens that it is, the database table is re-imported
 from the text source file.
+</para>
+<note>
+<title>Database updates</title>
+<para>
+It is important to note that, when using &IC; internal database methods 
+(which are some variant of DB_File or DBM, depending on what's available
+on your system), changes to text files cause databases to be resynchronized
+with plaintext file contents.
 </para><para>
+This behavior can be controlled via the &conf-NoImport; config directive,
+but by default, changes in text files will trigger a 
+rewrite of DBM or DB_File databases. This might lead to unexpected problems
+if you edit databases from &IC; and don't sync <emphasis>files</emphasis>
+with the databases first, or have a larger data sets
+(say, over a few thousand records) which take noticeable time to get
+re-imported.
+</para>
+</note>
+<para>
 For a complete discussion, please see the &conf-Database; configuration
 directive.
 </para>
@@ -180,5 +244,86 @@
 </section>
 
 
+<section>
+	<title>Interchange Database Conventions</title>
+<para>
+This section describes naming and file usage conventions used with
+&IC;. This is very important for both understanding &IC; and developing
+your own custom solutions which build upon officially recommended practices.
+</para><para>
+Term definitions:
+</para>
+<itemizedlist>
+<listitem>
+	<para><emphasis>key</emphasis> or <emphasis>code</emphasis></para>
+	<para>
+	The words reference the database key. In &IC;, the key is usually the
+	product <emphasis>code</emphasis> or &glos-SKU;, which is the product
+	part number. Otherwise, key values may be used to generate relationships
+	to other database tables.
+	</para><para>
+	It is recommended that the key be the first column of the database
+	text source file, since Interchange's import, export, and search
+	facilities rely on this practice.
+	</para>
+</listitem>
+<listitem>
+	<para><emphasis>field</emphasis> or <emphasis>column</emphasis></para>
+	<para>
+	The vertical row of a database. One of the columns is always the key
+	and it is usually the first one, as explained above.
+	</para>
+</listitem>
+<listitem>
+	<para><emphasis>table</emphasis> or <emphasis>database</emphasis></para>
+	<para>
+	A table in the database. Because &IC; has evolved from a
+	single-table database to an access method for an unlimited number of
+	tables (and databases, for that matter), a table will occasionally be
+	referred to as a database. The only time the term database refers to
+	something different is when describing the concept as it relates to
+	SQL, where a database contains a series of tables. While &IC;
+	cannot create SQL databases, it can drop and create tables with that
+	database if given the proper permissions.
+	</para>
+</listitem>
+</itemizedlist>
+
+
+<para>
+	&IC; uses one mandatory database, which is referred to as the
+	<database>products</database> database. In the supplied catalog, the
+	database is directly called <literal>products</literal> 
+	and the ASCII source is kept in the file <filename>products.txt</filename>
+	This is also the default file for searching contents with
+	the search engine, such as Glimpse or HTDig.
+</para><para>
+	Interchange also has a two of standard, but optional, databases that
+	are <emphasis role='bold'>in fixed formats</emphasis>:
+	</para>
+	<itemizedlist>
+<listitem>
+<para>
+	<database>shipping.asc</database> database contains shipping options that are
+	accessed if the	&conf-CustomShipping; directive is in use.
+	This is a fixed-format database, and must be created as specified.
+	For more information, see &glos-shipping; glossary entry and the 
+	&tag-shipping; tag.
+</para>
+</listitem>
+<listitem><para>
+	<database>salestax.asc</database> database contains 
+	sales tax information if the &tag-salestax; tag is to
+	be used. A default is supplied.
+	<emphasis role='bold'>Caution, these things change and need 
+	periodic updating!</emphasis> See &glos-tax; glossary entry for more
+	information.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+	The two above tables are never stored in SQL or DBM.
+</para>
+</section>
 
 <para>






From docs at icdevgroup.org  Thu Apr 21 20:09:39 2005
From: docs at icdevgroup.org (docs@icdevgroup.org)
Date: Thu Apr 21 20:09:44 2005
Subject: [docs] xmldocs - docelic modified 3 files
Message-ID: <200504220009.j3M09dZn008757@icdevgroup.org>

User:      docelic
Date:      2005-04-22 00:09:39 GMT
Modified:  glossary SKU database
Modified:  refs     TAXSHIPPING
Log:
- Some more stuff ported from old docs, and few minor fixes

Revision  Changes    Path
1.3       +1 -0      xmldocs/glossary/SKU


rev 1.3, prev_rev 1.2
Index: SKU
===================================================================
RCS file: /var/cvs/xmldocs/glossary/SKU,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- SKU	15 Dec 2004 14:24:00 -0000	1.2
+++ SKU	22 Apr 2005 00:09:39 -0000	1.3
@@ -0,0 +1 @@
+Stock Keeping Unit.



1.3       +127 -14   xmldocs/glossary/database


rev 1.3, prev_rev 1.2
Index: database
===================================================================
RCS file: /var/cvs/xmldocs/glossary/database,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- database	10 Apr 2005 22:45:56 -0000	1.2
+++ database	22 Apr 2005 00:09:39 -0000	1.3
@@ -27,7 +27,7 @@
 parlance - a <literal>database table</literal>.
 </emphasis>
 </para><para>
-&IC; works with GDBM, DB_File, SQL, LDAP and in-memory types of databases. 
+&IC; works with &GDBM;, DB_File, SQL, LDAP and in-memory types of databases. 
 Regardless of the type, each database must be registered with &IC; before it's
 ready to be used, and this is achieved using the &conf-Database; configuration
 directive. Pay special attention to the fact that &conf-Database; is both
@@ -57,8 +57,8 @@
 </para>
 <para>
 Interchange's default ASCII delimiter is TAB. <emphasis role='bold'>Keep in
-mind that the items must be separated by a single delimiter (that is, a single
-TAB by default)</emphasis>. Due to the nature of TABs, TAB-delimited files
+mind that the items must be separated by a single delimiter (that is, by a
+single TAB only)</emphasis>. Due to the nature of TABs, TAB-delimited files
 look messy and unaligned when viewed in a text editor. Do not try to fix these;
 better use the <command>te</command> utility that comes as part of the 
 &IC; distribution to edit files more conveniently.
@@ -108,8 +108,9 @@
 
 <note>
 	<para>
-Field names are usually case-sensitive. Use
-consistency when naming or you might encounter problems. All lower or
+Field names are usually case-sensitive (in fact, that depends on the
+underlying database type). Always be consistent when
+naming or referencing fields and you'll avoid the trouble. All lower or
 all upper case names are recommended.
 </para>
 </note>
@@ -136,7 +137,8 @@
 <note>
 <title>Database performance</title>
 <para>
-Do not, however, fall in the jaws of <ulink url="http://c2.com/cgi/wiki?PrematureOptimization">premature optimisation</ulink>, <ulink url="http://www.flounder.com/optimization.htm">your worst enemy</ulink>.
+Do not, however, try to optimize too soon and for no measureable difference.
+Do not fall in the jaws of <ulink url="http://c2.com/cgi/wiki?PrematureOptimization">premature optimisation</ulink>, <ulink url="http://www.flounder.com/optimization.htm">your worst enemy</ulink>.
 </para>
 </note>
 
@@ -154,7 +156,8 @@
 in the same directory as
 <filename><replaceable>table</replaceable>.txt</filename>, then database
 table will not be imported from the ASCII text source file.
-If there is no products.sql, the DBI/SQL import will happen once at
+If there is no <filename><replaceable>table</replaceable>.sql</filename>,
+the DBI/SQL import will happen once at
 &IC; startup or catalog reconfiguration time;
 Interchange will connect to the SQL database using the specified DSN
 (DNS is a standard DBI parameter meaning "Database Source Name").
@@ -193,10 +196,10 @@
 </section>
 
 <section>
-	<title>*DB* Databases</title>
+	<title>File-based Databases</title>
 <para>
-By "*DB*" databases we primarily assume Berkeley (DB_File) and GNU DBM. Those
-database types usually work in a way that, on every client access, the
+By file-based databases we primarily assume Berkeley (DB_File) and GNU DBM.
+Those database types usually work in a way that, on every client access, the
 appropriate database text source file is checked for being newer than the
 actual DB file itself.
 When it happens that it is, the database table is re-imported
@@ -220,6 +223,21 @@
 </para>
 </note>
 <para>
+To check if you have &GDBM; and GDBM &PERL; support available, run 
+<command>perl -le'require GDBM_File and print "I have GDBM."'</command>.
+To check if you have &BDBM; and DBM &PERL; support available, run 
+<command>perl -le'require DB_File and print "I have Berkeley DB."'</command>.
+Sometimes you want to use &BDBM; even if &GDBM; is installed and would 
+naturally take precedence; in such cases, set the 
+<envar>MINIVEND_DBFILE</envar> environment variable to a true value
+(<command>setenv MINIVEND_DBFILE 1</command> in <application>csh</application>,
+<command>MINIVEND_DBFILE=1 ; export MINIVEND_DBFILE</command> in 
+<application>sh</application>,
+<application>b(a)sh</application> or 
+<application>ksh</application>).
+It is also possible to use &BDBM; for just specific databases.
+</para>
+<para>
 For a complete discussion, please see the &conf-Database; configuration
 directive.
 </para>
@@ -228,15 +246,28 @@
 <section>
 	<title>Memory Databases</title>
 <para>
+Memory &IC; databases 
+use &PERL; hashes to store the data directly in memory. Every time
+the &IC; server is restarted, it will re-import all in-memory
+databases for every catalog.
+</para>
+<para>
 Memory databases are used by default only if no database type is
 explicity specified, and there is no DB_File or gdbm found on
 the system. Otherwise they can be used for small but high-traffic
 tables. Keep in mind, however, that since their contents are not saved back
 to the text files, you'll want to either take care of the data export yourself,
 or keep the tables stuffed with read-only data.
-</para><para>
-As with SQL databases, the import will only be performed once at 
-&IC; startup or catalog reconfiguration time.
+</para>
+<para>
+if you want to force memory databases despite of GDBM_File or DB_File
+being present, set the <envar>MINIVEND_NODBM</envar> environment variable
+to a true value (look above for hints).
+It is also possible to use memory type for just specific databases.
+</para>
+<para>
+Memory databases import will be performed once at 
+every &IC; startup or catalog reconfiguration time.
 </para><para>
 For a complete discussion, please see the &conf-Database; configuration
 directive.
@@ -297,7 +328,10 @@
 	and the ASCII source is kept in the file <filename>products.txt</filename>
 	This is also the default file for searching contents with
 	the search engine, such as Glimpse or HTDig.
-</para><para>
+</para>
+
+<note>
+<para>
 	Interchange also has a two of standard, but optional, databases that
 	are <emphasis role='bold'>in fixed formats</emphasis>:
 	</para>
@@ -324,6 +358,85 @@
 <para>
 	The two above tables are never stored in SQL or DBM.
 </para>
+</note>
+
+	<section>
+	<title>"Products" Database</title>
+	<para>
+		The <database>products</database> databases contain items that
+		you're selling.
+		Each product listed should be given a product code, usually
+		referred to as &glos-SKU; &mdash; a short code that identifies the
+		product on the
+		ordering page and in the catalog. The <filename>products.txt</filename>
+		file is an ASCII-delimited text source file. It should contain
+		product SKUs, along with an arbitrary
+		number of fields which must contain at least the fields
+		<database class='field'>description</database> and 
+		<database class='field'>price</database> (or however the
+		&conf-PriceField; and &conf-DescriptionField;
+		directives have been set). Any additional information needed in the
+		catalog can be placed in any arbitrary field.
+	</para>
+	<para>
+		The field names must be defined on the first line of the
+		<filename>products.txt</filename> file. These field names must match
+		exactly the field
+		names of the <tag>item-field</tag> tags in the catalog pages, or the
+		&IC; server will not access them properly. Field names can
+		contain the characters <literal>A-Za-z0-9</literal> and underscore
+		(<literal>_</literal>).
+	</para>
+	<para>
+		It is important to adjust the &conf-PriceField; and &conf-DescriptionField;
+		directives appropriately if you change the default field names, or 
+		&IC; tags such as <tag>item-price</tag> or <tag>item-description</tag>
+		won't work.
+	</para>
+	<para>
+		For each product entry in the text source file, the product code must
+		be the first field in the line, and
+		must be unique. Product codes can contain the characters
+		<literal>A-Za-z0-9</literal>,
+		along with hyphens (<literal>-</literal>), underscores
+		(<literal>_</literal>), pound signs/hash marks
+		(<literal>#</literal>), slashes (<literal>/</literal>) and periods
+		(<literal>.</literal>). Note that slashes will
+		interfere with on-the-fly page references; avoid them if at all possible.
+	</para>
+	<para>
+		The columns in text source files should be separated by one of the
+		approved delimiting
+		schemes (TAB, PIPE, or CSV), and are case-sensitive in some cases. If
+		the case of the "description" or "price" fields have been modified,
+		the &conf-PriceField; and &conf-DescriptionField; directives must be
+		adjusted appropriately.
+	</para>
+	<note>
+		<para>
+		CSV format is not recommended as the scheme for the products
+		database. It is much slower than TAB- or PIPE-delimited files, and
+		dramatically reduces search engine functionality. No field-specific
+		searches are possible. Using CSV for any small database that will not
+		be searched is fine.
+		</para>
+	</note>
+	<para>
+		More than one database may be used as a products database. If the
+		&conf-ProductFiles; directive is set to a space-separated list of
+		valid &IC; database identifiers, all listed databases will be
+		searched (in the order specified) for any items that are ordered, or
+		for product information (such as with <code>price code</code> or
+		<code>field code</code>
+		tags).
+	</para>
+	<para>
+		If you are modifying the database on-the-fly, it is recommended that
+		the file
+		be locked while it is being modified. Interchange's supplied import
+		routines do this.
+	</para>
+	</section>
 </section>
 
 <para>



1.2       +1 -1      xmldocs/refs/TAXSHIPPING


rev 1.2, prev_rev 1.1
Index: TAXSHIPPING
===================================================================
RCS file: /var/cvs/xmldocs/refs/TAXSHIPPING,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- TAXSHIPPING	3 Jan 2005 20:42:16 -0000	1.1
+++ TAXSHIPPING	22 Apr 2005 00:09:39 -0000	1.2
@@ -25,7 +25,7 @@
 
 __NAME__ example: 
 <programlisting>
-NV, IL
+Variable TAXSHIPPING NV, IL
 </programlisting>
 __END__
 






From docs at icdevgroup.org  Fri Apr 22 07:37:05 2005
From: docs at icdevgroup.org (docs@icdevgroup.org)
Date: Fri Apr 22 07:37:10 2005
Subject: [docs] xmldocs - docelic modified refs/init_page/example2
Message-ID: <200504221137.j3MBb5Zn022930@icdevgroup.org>

User:      docelic
Date:      2005-04-22 11:37:04 GMT
Added:     refs/init_page example2
Log:
Little fixes, more examples

Revision  Changes    Path
1.1                  xmldocs/refs/init_page/example2


rev 1.1, prev_rev 1.0
Index: example2
===================================================================
<example>

<title>
Auto-wrapping pages in templates, deciding about a template depending on page path
</title>

<para>
In this real-life example, we want to automatically attach header and 
footer to every served page. We also have four different templates, and
want to include them depending on the path of the page being served.
</para>

<programlisting><![CDATA[
Pragma  init_page=wrap_page
Sub <<EOS
sub wrap_page {
  my $pref = shift;
  my $tmpl;

  if ( $Session->{last_url} =~ m#^/www(/|$)# ) {
    $tmpl = "www"
  } elsif ( $Session->{last_url} =~ m#^/plus(/|$)# ) {
    $tmpl = "plus"
  } elsif ( $Session->{last_url} =~ m#^/hp(/|$)# ) {
    $tmpl = "hp"
  } elsif ( $Session->{last_url} =~ m#^/adm(/|$)# ) {
    $tmpl = "adm"
  }

  $Scratch->{subsite} = $tmpl || $Scratch->{subsite} || "plus";

  $$pref = "[include templates/$Scratch->{subsite}-top]" .
    $$pref .
    "[include templates/$Scratch->{subsite}-bottom]";

  return;
}
EOS
]]></programlisting>
<para>
Note that we explicitly check for supported template types 
(<literal>www</literal>, <literal>plus</literal>, <literal>hp</literal>
or <literal>adm</literal>) to minimize the chance of abuse.
Invalid or unmatched templates default to the previously used template, or
<literal>plus</literal> as a bottom line and
the files <filename>templates/plus-top</filename> and 
<filename>templates/plus-bottom</filename> are included then.
</para>
<para>
You might wonder in what cases would the code fail to match the template?
Well, obviously, users could simply try to access non-existent pages. 
The other common issue are &glos-form-action;s such as 
<literal>/scan</literal> or <literal>/process</literal>.
</para>
</example>






From docs at icdevgroup.org  Sun Apr 24 06:54:39 2005
From: docs at icdevgroup.org (docs@icdevgroup.org)
Date: Sun Apr 24 06:54:43 2005
Subject: [docs] xmldocs - docelic modified refs/form-session-id
Message-ID: <200504241054.j3OAsdZn024434@icdevgroup.org>

User:      docelic
Date:      2005-04-24 10:54:39 GMT
Added:     refs     form-session-id
Log:
- Document form-session-id

Revision  Changes    Path
1.1                  xmldocs/refs/form-session-id


rev 1.1, prev_rev 1.0
Index: form-session-id
===================================================================
__NAME__ purpose
insert hidden form field containing the session ID
__END__


__NAME__ synopsis
<group choice='req'>
	<arg choice='plain'></arg>
</group>
__END__


__NAME__ description
It is necessary to include the &IC; session ID on &glos-HTML; forms when 
users are not accepting cookies, or they might lose the session information.
The <tag>form-session-id</tag> tag inserts the appropriate hidden form field
containing session ID on a page, but only when necessary.
</para><para>
In most cases, the tag <emphasis role='bold'>will</emphasis> insert the
hidden form field (that is, when users are not accepting cookies or public
display of session IDs &mdash; <mv>no_session_id</mv> &mdash; is not disabled).
It will <emphasis role='bold'>not</emphasis>, however, insert the field if
the user <emphasis role='bold'>is</emphasis> accepting browser cookies
and <mv>no_session_id</mv> is enabled.
__END__


__NAME__ example: Simple form with an optional session ID form field
Here's a very simple login form. As you can see, all you have to do to
include the session ID on the form is to include <tag>form-session-id</tag>
somewhere in it.
<programlisting><![CDATA[
<form action="[process secure=1]" method="POST">
  <input type="hidden" name="mv_todo"  value="return">
  <input type="hidden" name="mv_click" value="Login">
  <input type="hidden" name="mv_failpage" value="login">
  <input type="hidden" name="mv_successpage" value="[either][scratchd mv_successpage][or]member/service[/either]">
  <input type="hidden" name="mv_nextpage" value="index">
  [form-session-id]

  [L]Username[/L]: <input name="mv_username" value="[scratch cookie_username]"><br/>
  [L]Password[/L]: <input type="password" name="mv_password" VALUE=""><br/>
  <input class="button3" type=submit value="[L]Log In[/L]">
</form>
]]></programlisting>
__END__







From docs at icdevgroup.org  Sat Apr 30 18:56:53 2005
From: docs at icdevgroup.org (docs@icdevgroup.org)
Date: Sat Apr 30 18:56:59 2005
Subject: [docs] xmldocs - docelic modified 11 files
Message-ID: <200504302256.j3UMurZn029886@icdevgroup.org>

User:      docelic
Date:      2005-04-30 22:56:53 GMT
Modified:  glossary ITL
Modified:  refs     bar-button base-url.tag button capture_page cart
Modified:           catch.tag cgi.tag convert-date.tag counter.tag
Added:     refs     br.tag
Log:
Little fixes, some more docs, nice series altogether.

Revision  Changes    Path
1.10      +4 -2      xmldocs/glossary/ITL


rev 1.10, prev_rev 1.9
Index: ITL
===================================================================
RCS file: /var/cvs/xmldocs/glossary/ITL,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- ITL	6 Mar 2005 11:51:28 -0000	1.9
+++ ITL	30 Apr 2005 22:56:52 -0000	1.10
@@ -341,7 +341,9 @@
 <arg choice='plain'>reparse</arg> attributes here. <emphasis role='bold'>
 It is very important to remember that the behavior of the
 <arg choice='plain'>interpolate</arg> attribute (unfortunately) differs,
-depending on whether a tag is stand-alone or a container. In addition,
+depending on whether a tag is <emphasis>stand-alone</emphasis> or a
+<emphasis>container</emphasis>.
+In addition,
 the <arg choice='plain'>reparse</arg> attribute is only used with
 container tags (because its function is performed by
 <arg choice='plain'>interpolate</arg> in stand-alone tags).
@@ -352,7 +354,7 @@
 specifies whether the <emphasis>tag body</emphasis> will be
 &glos-interpolate;d before being passed to the tag. 
 <!-- </para><para> -->
-With stand-alone tags, the <arg choice='plain'>interpolate</arg> attribute
+With non-container tags, the <arg choice='plain'>interpolate</arg> attribute
 specifies whether the <emphasis>output</emphasis> of the tag will be
 &glos-interpolate;d. This is very confusing because it's not intuitive, but
 once you get to remember it a few times in practice, it will stop being a 



1.6       +2 -1      xmldocs/refs/bar-button


rev 1.6, prev_rev 1.5
Index: bar-button
===================================================================
RCS file: /var/cvs/xmldocs/refs/bar-button,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- bar-button	14 Dec 2004 19:15:43 -0000	1.5
+++ bar-button	30 Apr 2005 22:56:53 -0000	1.6
@@ -23,7 +23,8 @@
 	Name of the current page. Usually you do not want to override the default.
 	</entry>
 </row>
-
+&ROW_INTERPOLATE_0;
+&ROW_REPARSE_1;
 __END__
 
 



1.3       +0 -1      xmldocs/refs/base-url.tag


rev 1.3, prev_rev 1.2
Index: base-url.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/base-url.tag,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- base-url.tag	8 Mar 2005 11:43:13 -0000	1.2
+++ base-url.tag	30 Apr 2005 22:56:53 -0000	1.3
@@ -9,7 +9,6 @@
 
 __NAME__ synopsis
 &ROW_INTERPOLATE_0;
-&ROW_REPARSE_1;
 __END__
 
 



1.10      +7 -0      xmldocs/refs/button


rev 1.10, prev_rev 1.9
Index: button
===================================================================
RCS file: /var/cvs/xmldocs/refs/button,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- button	14 Dec 2004 19:15:43 -0000	1.9
+++ button	30 Apr 2005 22:56:53 -0000	1.10
@@ -91,11 +91,18 @@
 &ROW_EXTRA_none;
 &ROW_HTML_std;
 &ROW_CSS_std;
+&ROW_INTERPOLATE_0;
+&ROW_REPARSE_1;
 __END__
 
 
 __NAME__ see also
 env
+__END__
+
+
+__NAME__ notes
+The &tag-button; tag can work with unnamed forms.
 __END__
 
 



1.9       +1 -0      xmldocs/refs/capture_page


rev 1.9, prev_rev 1.8
Index: capture_page
===================================================================
RCS file: /var/cvs/xmldocs/refs/capture_page,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- capture_page	14 Dec 2004 19:15:43 -0000	1.8
+++ capture_page	30 Apr 2005 22:56:53 -0000	1.9
@@ -62,6 +62,7 @@
 </row>
 &ROW_UMASK_none;
 &ROW_HIDE_0;
+&ROW_INTERPOLATE_0;
 __END__
 
 __NAME__ description



1.3       +6 -0      xmldocs/refs/cart


rev 1.3, prev_rev 1.2
Index: cart
===================================================================
RCS file: /var/cvs/xmldocs/refs/cart,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- cart	14 Dec 2004 19:15:43 -0000	1.2
+++ cart	30 Apr 2005 22:56:53 -0000	1.3
@@ -34,6 +34,10 @@
 <tag>nitems</tag>).
 __END__
 
+__NAME__ notes
+See the &glos-cart; glossary entry.
+__END__
+
 __NAME__ example: Set new default cart name
 Place the following on an Interchange page:
 <programlisting>
@@ -41,3 +45,5 @@
 </programlisting>
 __END__
 
+__NAME__ see also
+__END__



1.3       +6 -19     xmldocs/refs/catch.tag


rev 1.3, prev_rev 1.2
Index: catch.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/catch.tag,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- catch.tag	8 Mar 2005 18:15:51 -0000	1.2
+++ catch.tag	30 Apr 2005 22:56:53 -0000	1.3
@@ -100,25 +100,7 @@
 	</entry>
 
 </row> 
-<row>
-
-	<entry>
-	hide
-	</entry>
-	<entry>
-	<!-- POS -->
-	</entry>
-	<entry>
-	<!-- REQ -->
-	</entry>
-	<entry>
-	<!-- DFL -->
-	</entry>
-	<entry>
-	<!-- DSC -->
-	</entry>
-
-</row> 
+&ROW_HIDE_0;
 &ROW_INTERPOLATE_0;
 &ROW_REPARSE_1;
 __END__
@@ -190,3 +172,8 @@
 </programlisting>
 __END__
 
+
+
+__NAME__ missing
+description for exact, joiner, error_set, error_scratch options
+__END__



1.5       +1 -0      xmldocs/refs/cgi.tag


rev 1.5, prev_rev 1.4
Index: cgi.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/cgi.tag,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- cgi.tag	14 Dec 2004 19:15:43 -0000	1.4
+++ cgi.tag	30 Apr 2005 22:56:53 -0000	1.5
@@ -60,6 +60,7 @@
 </row>
 &ROW_FILTER_none;
 &ROW_HIDE_0;
+&ROW_INTERPOLATE_0;
 __END__
 
 



1.2       +33 -2     xmldocs/refs/convert-date.tag


rev 1.2, prev_rev 1.1
Index: convert-date.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/convert-date.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- convert-date.tag	17 Feb 2005 23:25:39 -0000	1.1
+++ convert-date.tag	30 Apr 2005 22:56:53 -0000	1.2
@@ -2,6 +2,28 @@
 <row>
 
 	<entry>
+	<group choice='opt'>
+	<arg choice='plain'>adjust</arg>
+	<arg choice='plain'>days</arg>
+	</group>
+	</entry>
+	<entry>
+	Yes
+	</entry>
+	<entry>
+	<!-- REQ -->
+	</entry>
+	<entry>
+	<!-- DFL -->
+	</entry>
+	<entry>
+	<!-- DSC -->
+	</entry>
+
+</row> 
+<row>
+
+	<entry>
 	raw
 	</entry>
 	<entry>
@@ -21,7 +43,10 @@
 <row>
 
 	<entry>
-	format
+	<group choice='opt'>
+	<arg choice='plain'>format</arg>
+	<arg choice='plain'>fmt</arg>
+	</group>
 	</entry>
 	<entry>
 	<!-- POS -->
@@ -77,4 +102,10 @@
 </row> 
 &ROW_INTERPOLATE_0;
 &ROW_REPARSE_1;
-__END__
\ No newline at end of file
+__END__
+
+
+__NAME__ missing
+option descriptions
+__END__
+



1.2       +352 -225  xmldocs/refs/counter.tag


rev 1.2, prev_rev 1.1
Index: counter.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/counter.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- counter.tag	17 Feb 2005 23:25:39 -0000	1.1
+++ counter.tag	30 Apr 2005 22:56:53 -0000	1.2
@@ -1,232 +1,359 @@
 __NAME__ synopsis 
 <row>
 
-	<entry>
-	start
-	</entry>
-	<entry>
-	<!-- POS -->
-	</entry>
-	<entry>
-	<!-- REQ -->
-	</entry>
-	<entry>
-	<!-- DFL -->
-	</entry>
-	<entry>
-	<!-- DSC -->
-	</entry>
-
-</row> 
-<row>
-
-	<entry>
-	sql
-	</entry>
-	<entry>
-	<!-- POS -->
-	</entry>
-	<entry>
-	<!-- REQ -->
-	</entry>
-	<entry>
-	<!-- DFL -->
-	</entry>
-	<entry>
-	<!-- DSC -->
-	</entry>
-
-</row> 
-<row>
-
-	<entry>
-	inc_routine
-	</entry>
-	<entry>
-	<!-- POS -->
-	</entry>
-	<entry>
-	<!-- REQ -->
-	</entry>
-	<entry>
-	<!-- DFL -->
-	</entry>
-	<entry>
-	<!-- DSC -->
-	</entry>
-
-</row> 
-<row>
-
-	<entry>
-	bypass
-	</entry>
-	<entry>
-	<!-- POS -->
-	</entry>
-	<entry>
-	<!-- REQ -->
-	</entry>
-	<entry>
-	<!-- DFL -->
-	</entry>
-	<entry>
-	<!-- DSC -->
-	</entry>
-
-</row> 
-<row>
-
-	<entry>
-	dsn
-	</entry>
-	<entry>
-	<!-- POS -->
-	</entry>
-	<entry>
-	<!-- REQ -->
-	</entry>
-	<entry>
-	<!-- DFL -->
-	</entry>
-	<entry>
-	<!-- DSC -->
-	</entry>
-
-</row> 
-<row>
-
-	<entry>
-	user
-	</entry>
-	<entry>
-	<!-- POS -->
-	</entry>
-	<entry>
-	<!-- REQ -->
-	</entry>
-	<entry>
-	<!-- DFL -->
-	</entry>
-	<entry>
-	<!-- DSC -->
-	</entry>
-
-</row> 
-<row>
-
-	<entry>
-	pass
-	</entry>
-	<entry>
-	<!-- POS -->
-	</entry>
-	<entry>
-	<!-- REQ -->
-	</entry>
-	<entry>
-	<!-- DFL -->
-	</entry>
-	<entry>
-	<!-- DSC -->
-	</entry>
-
-</row> 
-<row>
-
-	<entry>
-	attr
-	</entry>
-	<entry>
-	<!-- POS -->
-	</entry>
-	<entry>
-	<!-- REQ -->
-	</entry>
-	<entry>
-	<!-- DFL -->
-	</entry>
-	<entry>
-	<!-- DSC -->
-	</entry>
-
-</row> 
-<row>
-
-	<entry>
-	date
-	</entry>
-	<entry>
-	<!-- POS -->
-	</entry>
-	<entry>
-	<!-- REQ -->
-	</entry>
-	<entry>
-	<!-- DFL -->
-	</entry>
-	<entry>
-	<!-- DSC -->
-	</entry>
-
-</row> 
-<row>
-
-	<entry>
-	dec_routine
-	</entry>
-	<entry>
-	<!-- POS -->
-	</entry>
-	<entry>
-	<!-- REQ -->
-	</entry>
-	<entry>
-	<!-- DFL -->
-	</entry>
-	<entry>
-	<!-- DSC -->
-	</entry>
-
-</row> 
-<row>
-
-	<entry>
-	value
-	</entry>
-	<entry>
-	<!-- POS -->
-	</entry>
-	<entry>
-	<!-- REQ -->
-	</entry>
-	<entry>
-	<!-- DFL -->
-	</entry>
-	<entry>
-	<!-- DSC -->
-	</entry>
-
-</row> 
-<row>
-
-	<entry>
-	decrement
-	</entry>
-	<entry>
-	<!-- POS -->
-	</entry>
-	<entry>
-	<!-- REQ -->
-	</entry>
-	<entry>
-	<!-- DFL -->
-	</entry>
-	<entry>
-	<!-- DSC -->
-	</entry>
+  <entry>
+  <group choice='opt'>
+  <arg choice='plain'>name</arg>
+  <arg choice='plain'>file</arg>
+  </group>
+  </entry>
+  <entry>
+  Yes
+  </entry>
+  <entry>
+  <!-- REQ -->
+  </entry>
+  <entry>
+  <filename>&glos-CATROOT;/etc/counter</filename>
+  </entry>
+  <entry>
+  Counter file to use. Taken relatively to &glos-CATROOT; unless absolute
+  pathname is specified.
+  </entry>
+
+</row> 
+<row>
+
+  <entry>
+  start
+  </entry>
+  <entry>
+  <!-- POS -->
+  </entry>
+  <entry>
+  <!-- REQ -->
+  </entry>
+  <entry>
+  <!-- DFL -->
+  </entry>
+  <entry>
+  Counter start value
+  </entry>
+
+</row> 
+<row>
+
+  <entry>
+  sql
+  </entry>
+  <entry>
+  <!-- POS -->
+  </entry>
+  <entry>
+  <!-- REQ -->
+  </entry>
+  <entry>
+  <!-- DFL -->
+  </entry>
+  <entry>
+  A <literal><replaceable>table</replaceable>:<replaceable>field</replaceable></literal> specification, if &tag-counter; is to increment a field in an SQL database.
+  </entry>
+
+</row> 
+<row>
+
+  <entry>
+  inc_routine
+  </entry>
+  <entry>
+  <!-- POS -->
+  </entry>
+  <entry>
+  <!-- REQ -->
+  </entry>
+  <entry>
+  <!-- DFL -->
+  </entry>
+  <entry>
+  Routine to use to increase the counter.
+  The routine should be an
+  existing &PERL; function, catalog subroutine, or global subroutine
+  </entry>
+
+</row> 
+<row>
+
+  <entry>
+  bypass
+  </entry>
+  <entry>
+  <!-- POS -->
+  </entry>
+  <entry>
+  <!-- REQ -->
+  </entry>
+  <entry>
+  0
+  </entry>
+  <entry>
+  Bypass the existing database connection, and instead connect to the database 
+  anew, if <arg choice='plain'>sql</arg> attribute is used.
+  </entry>
+
+</row> 
+<row>
+
+  <entry>
+  dsn
+  </entry>
+  <entry>
+  <!-- POS -->
+  </entry>
+  <entry>
+  <!-- REQ -->
+  </entry>
+  <entry>
+  <varname>DBI_DSN</varname>
+  </entry>
+  <entry>
+  DSN information to connect to the SQL database, if
+  <arg choice='plain'>sql</arg> attribute is used
+  </entry>
+
+</row> 
+<row>
+
+  <entry>
+  user
+  </entry>
+  <entry>
+  <!-- POS -->
+  </entry>
+  <entry>
+  <!-- REQ -->
+  </entry>
+  <entry>
+  <!-- DFL -->
+  </entry>
+  <entry>
+  User to connect to the database as, if 
+  <arg choice='plain'>sql</arg> attribute is used
+  </entry>
+
+</row> 
+<row>
+
+  <entry>
+  pass
+  </entry>
+  <entry>
+  <!-- POS -->
+  </entry>
+  <entry>
+  <!-- REQ -->
+  </entry>
+  <entry>
+  <!-- DFL -->
+  </entry>
+  <entry>
+  Password to provide during connection to the database, if 
+  <arg choice='plain'>sql</arg> attribute is used
+  </entry>
+
+</row> 
+<row>
+
+  <entry>
+  attr
+  </entry>
+  <entry>
+  <!-- POS -->
+  </entry>
+  <entry>
+  <!-- REQ -->
+  </entry>
+  <entry>
+  <!-- DFL -->
+  </entry>
+  <entry>
+  Extra content for the <function>DBI->connect</function> call
+  </entry>
+
+</row> 
+<row>
+
+  <entry>
+  date
+  </entry>
+  <entry>
+  <!-- POS -->
+  </entry>
+  <entry>
+  <!-- REQ -->
+  </entry>
+  <entry>
+  </entry>
+  <entry>
+  Date-based counter? Set to any true value, or <literal>gmt</literal> to 
+  also signify GMT date
+  </entry>
+
+</row> 
+<row>
+
+  <entry>
+  dec_routine
+  </entry>
+  <entry>
+  <!-- POS -->
+  </entry>
+  <entry>
+  <!-- REQ -->
+  </entry>
+  <entry>
+  <!-- DFL -->
+  </entry>
+  <entry>
+  Routine to use to decrease the counter
+  The routine should be an
+  existing &PERL; function, catalog subroutine, or global subroutine
+  </entry>
+
+</row> 
+<row>
+
+  <entry>
+  value
+  </entry>
+  <entry>
+  <!-- POS -->
+  </entry>
+  <entry>
+  <!-- REQ -->
+  </entry>
+  <entry>
+  <!-- DFL -->
+  </entry>
+  <entry>
+  Literal value to set counter to
+  </entry>
+
+</row> 
+<row>
+
+  <entry>
+  decrement
+  </entry>
+  <entry>
+  <!-- POS -->
+  </entry>
+  <entry>
+  <!-- REQ -->
+  </entry>
+  <entry>
+  0
+  </entry>
+  <entry>
+  Decrement instead of incrementing the counter?
+  </entry>
 
 </row> 
 &ROW_INTERPOLATE_0;
 &ROW_REPARSE_1;
-__END__
\ No newline at end of file
+__END__
+
+
+__NAME__ description
+The tag provides an interface to the counter functionality within &IC;.
+The counters are usually kept as text files, but can also be sequences in
+&glos-SQL; tables.
+</para><para>
+&tag-counter; can increase and decrease counters, or set them to specific
+values. In addition, custom increment or decrement functions can be
+used.
+__END__
+
+
+__NAME__ notes
+The SQL field-updating routine is database-dependent; please see the tag
+source for details.
+</para><para>
+Date-based counters cannot be decremented.
+__END__
+
+__NAME__ example: Basic counter file
+The following creates a counter file,
+<filename>counter.basic</filename> in your catalog root directory.
+The counter starts at <literal>10</literal>.
+<programlisting>
+[counter file=counter.basic start=10]
+</programlisting>
+__END__
+
+
+__NAME__ example: Basic date-based counter file
+The following creates two date-based counter files,
+<filename>counter.loc</filename> and
+<filename>counter.gmt</filename> in your catalog root directory.
+<programlisting>
+[counter file=counter.loc date=1]
+[counter file=counter.gmt date=gmt]
+</programlisting>
+__END__
+
+
+
+__NAME__ example: Counter using steps of +2 and -2, with in-place subroutine specification
+The following creates two counter files,
+<filename>counter.p2</filename> and
+<filename>counter.m2</filename> in your catalog root directory.
+Counters initially start at <literal>20</literal>; one adds
+<literal>2</literal> and one subtracts <literal>2</literal> each time
+they're called.
+<programlisting>
+[counter
+  file=counter.p2
+  start=20
+  inc-routine=`sub { shift(@_) + 2 }`
+]
+[counter
+  file=counter.m2
+  start=20
+  decrement=1
+  dec-routine=`sub { shift(@_) - 2 }`
+]
+</programlisting>
+__END__
+
+
+
+__NAME__ example: Counter using steps of +3 and -3, with Sub or GlobalSub routine specification
+The following creates two counter files,
+<filename>counter.p3g</filename> and
+<filename>counter.m3g</filename> in your catalog root directory.
+Counters initially start at <literal>20</literal>; one adds
+<literal>3</literal> and one subtracts <literal>3</literal> each time
+they're called.
+</para><para>
+You need the following in &ccf; or &gcf;:
+<programlisting><![CDATA[
+Sub three_steps_forward <<EOR
+sub {
+  my $val = shift; $val += 3; return $val;
+}
+EOR
+
+Sub three_steps_back <<EOR
+sub {
+  my $val = shift; $val -= 3; return $val;
+}
+EOR
+]]></programlisting>
+</para><para>
+And the following on an &IC; page:
+<programlisting>
+[counter file=counter.p3 start=20 inc-routine=three_steps_forward ]
+[counter file=counter.m3 start=20 decrement=1 dec-routine=three_steps_back]
+</programlisting>
+__END__
+



1.1                  xmldocs/refs/br.tag


rev 1.1, prev_rev 1.0
Index: br.tag
===================================================================
__NAME__ purpose
insert HTML BR (break) element
__END__

__NAME__ see also
__END__


__NAME__ synopsis
&ROW_INTERPOLATE_0;
__END__


__NAME__ description
The tag simply inserts the &glos-HTML; BR (break) element.
The tag is lowercased and, if the <varname>Vend::Xtrailer</varname>
variable is set, terminated with <literal>/</literal> to satisfy 
XHTML convention.
__END__

__NAME__ example: Inserting HTML BR
<programlisting>
Line 1[br]
Line 2[br]
</programlisting>
__END__