[docs] xmldocs - docelic modified 25 files

docs at icdevgroup.org docs at icdevgroup.org
Thu Oct 20 10:09:52 EDT 2005


User:      docelic
Date:      2005-10-20 14:09:51 GMT
Modified:  .        Makefile README
Modified:  bin      refs-autogen
Modified:  docbook  literals.ent
Modified:  guides   faq.xml iccattut.xml optimization.xml xmldocs.xml
Modified:  refs     AccumulateCode AutoModifier CodeRepository XHTML
Modified:           currency.tag dbi_quote.filter debug.tag discount
Modified:           filter_sql_no_backslash name.filter sql.filter
Modified:           version.tag xfer-catalog.tag
Added:     glossary escape regexp shipping
Added:     refs     comment.tag
Log:
- guides/xmldocs.xml: guide about writing XMLDOCS (in progress)
- docbbok/*.xml and Makefile: added new documents to sitemap and build
- guides/*.xml: work on guides, reorganizing faq, adding stuff to optimization
- refs/*: some number of 1-line fixes to reduce number of build warnings
- glossary/*: placeholders
- some more docs to bin/* scripts and README

Revision  Changes    Path
1.75      +1 -1      xmldocs/Makefile


rev 1.75, prev_rev 1.74
Index: Makefile
===================================================================
RCS file: /var/cvs/xmldocs/Makefile,v
retrieving revision 1.74
retrieving revision 1.75
diff -u -r1.74 -r1.75
--- Makefile	15 Oct 2005 13:23:17 -0000	1.74
+++ Makefile	20 Oct 2005 14:09:49 -0000	1.75
@@ -13,7 +13,7 @@
 #############################################################
 # Base definitions
 SYMBOL_TYPES= pragmas vars tags confs filters orderchecks
-GUIDES      = iccattut programming-style upgrade faq index optimization search
+GUIDES      = iccattut programming-style upgrade faq index optimization search xmldocs
 HOWTOS      = howtos
 GLOSSARY    = glossary
 ALL_DOCS    = $(GLOSSARY) $(HOWTOS) $(GUIDES) $(SYMBOL_TYPES)



1.22      +3 -2      xmldocs/README


rev 1.22, prev_rev 1.21
Index: README
===================================================================
RCS file: /var/cvs/xmldocs/README,v
retrieving revision 1.21
retrieving revision 1.22
diff -u -r1.21 -r1.22
--- README	26 Aug 2005 14:56:43 -0000	1.21
+++ README	20 Oct 2005 14:09:49 -0000	1.22
@@ -69,8 +69,9 @@
   - docbook-xsl
   - xsltproc
   - exuberant-ctags (to be)
-	- db2latex-xsl
-	- tetex-extra (and actually, packages it depends on)
+  - db2latex-xsl
+  - tetex-extra (and actually, packages it depends on)
+  - XML::Twig Perl module (if you want to call bin/refs-autogen --validate)
 
 If running on Red Hat and not Debian GNU, apply this patch:
 http://icdevgroup.org/~docelic/xmldocs-rh.diff . It allows you to get



1.99      +21 -12    xmldocs/bin/refs-autogen


rev 1.99, prev_rev 1.98
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.98
retrieving revision 1.99
diff -u -r1.98 -r1.99
--- refs-autogen	15 Oct 2005 13:23:17 -0000	1.98
+++ refs-autogen	20 Oct 2005 14:09:49 -0000	1.99
@@ -66,7 +66,8 @@
 	"skip-invalid|s" => \$skip_invalid,
 )) { die "Error parsing options\n" }
 
-# Determine which stuff to output
+# Determine which stuff to output (only lists of symbols, or the real
+# XMLs files, or both unless --output is specified).
 my ( $output_list, $output_xml ) = (1,1);
 if (!$output_both and $output_spec) {
 	$output_spec =~ /\.?list$/ and ($output_list,$output_xml) = (1,0) or
@@ -74,6 +75,7 @@
 	die "Unknown output combination '$output_spec'\n";
 }
 
+# Help find XML irregularities in documentation blocks
 if ($validate) {
 	require XML::Twig;
 }
@@ -168,10 +170,10 @@
 	"please see the &glos-variable; glossary entry.",
 );
 
-my @paths = @ARGV; # Versions requested
+my @paths = @ARGV; # Versions for which documentation build is requested
 my $path; # Current path, used in loop for each version requested
-my $dumppath; # Path to cache dump file
-my $dumpdir;
+my $dumppath; # Directory containing cache dump file (corresponding to $path)
+my $dumpdir; # Full path to current version's .cache.bin
 
 load_templates();
 
@@ -182,14 +184,18 @@
 @set_unused = readdir DIR; @set_unused = grep {!/^\.|^CVS$/} @set_unused;
 closedir DIR;
 
+# We will make this file contain autogenerated entities that point to 
+# CVS. For example, &cvsfile-README; will point to icdevgroup/..viewcvs../README
 open FILE_ENTITIES, "> $fileentitiespath" or
 	die "Can't open '$fileentitiespath' ($!)\n";
 
+
+### The main part of the script begins.
 while ( $path = shift @paths) { # Now, for each IC version specified
-	$dumppath = $path;
-	$i{ver} = $dumppath;
-	$dumpdir = "$dumppath/";
-	$dumppath .= "/.cache.bin";
+	$dumppath = $path;             # say, "5.2.0"
+	$i{ver} = $dumppath;           # Version number for internal use
+	$dumpdir = "$dumppath/";       # "5.2.0/"
+	$dumppath .= "/.cache.bin";    # "5.2.0/.cache.bin"
 
 	# Load %hash with the cache for particular version (replaces previous one).
 	# (which is OK since the data was extraced and we need previous cache
@@ -209,9 +215,9 @@
 	#
 	# However, entities for last version will, in addition to above,
 	# get a default entity (like &cvsfile-README;) where no version is specified
-	# in the entity, and it will point to some particular file in CVS-HEAD.
+	# in the entity, and it will point to file in CVS-HEAD.
 
-	# First derive IC series_ (in format X_Y) and series (in format X.Y), 
+	# First derive IC series_ (in format X_Y) and series (in format X.Y) tags, 
 	# and cvs tag for non-cvs-head. (If we're in cvs-head, we don't make cvs tag
 	# since cvs-head has no special tag).
 	unless ( $i{ver} eq 'cvs-head' ) {
@@ -223,6 +229,8 @@
 		$i{series} = '';
 		$i{cvstag} = '';
 	}
+
+
 	# Now load in list of files for which to generate entities.
 	# The list is already prepared for us by bin/stattree (a MANIFEST file,
 	# basically).
@@ -264,9 +272,10 @@
 				$MANIFEST[$i] . qq{</ulink>"} . ">\n";
 		}
 	}
-	# File entities dumped....
-	#########################################################################
+	# File entities dumped.... Job done.
+
 
+	#########################################################################
 
 
 



1.27      +3 -0      xmldocs/docbook/literals.ent


rev 1.27, prev_rev 1.26
Index: literals.ent
===================================================================
RCS file: /var/cvs/xmldocs/docbook/literals.ent,v
retrieving revision 1.26
retrieving revision 1.27
diff -u -r1.26 -r1.27
--- literals.ent	12 Aug 2005 12:41:51 -0000	1.26
+++ literals.ent	20 Oct 2005 14:09:49 -0000	1.27
@@ -12,6 +12,7 @@
 <!ENTITY ICDL "<ulink url='http://www.icdevgroup.org/i/dev/download.html'>download</ulink>">
 <!ENTITY ICCVS "<ulink url='http://www.icdevgroup.org/i/dev/cvs.html'>CVS</ulink>">
 <!ENTITY APACHE "<ulink url='http://www.apache.org/'>Apache</ulink>">
+<!ENTITY MATHOPD "<ulink url='http://www.mathopd.org/'>Mathopd</ulink>">
 <!ENTITY W3 "<ulink url='http://www.w3c.org/'>W3C</ulink>">
 <!ENTITY W3C "<ulink url='http://www.w3c.org/'>W3C</ulink>">
 <!ENTITY PERL "<ulink url='http://www.perl.org/'>Perl</ulink>">
@@ -23,6 +24,8 @@
 <!ENTITY GDBM "<ulink url='http://www.delorie.com/gnu/docs/gdbm/'>GNU DBM</ulink>">
 <!ENTITY NFS "<ulink url='http://nfs.sourceforge.net/'>NFS</ulink>">
 <!ENTITY IMAGEMAGICK "<ulink url='http://www.imagemagick.org/'>ImageMagick</ulink>">
+<!ENTITY DOCBOOK "<ulink url='http://www.docbook.org/'>DocBook</ulink>">
+<!ENTITY ECHO "<ulink url='http://www.echo-inc.com/'>ECHO</ulink>">
 
 
 



1.1                  xmldocs/glossary/escape


<<escape: empty>>


1.1                  xmldocs/glossary/regexp


<<regexp: empty>>


1.1                  xmldocs/glossary/shipping


<<shipping: empty>>


1.8       +77 -58    xmldocs/guides/faq.xml


rev 1.8, prev_rev 1.7
Index: faq.xml
===================================================================
RCS file: /var/cvs/xmldocs/guides/faq.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- faq.xml	3 Sep 2005 14:01:23 -0000	1.7
+++ faq.xml	20 Oct 2005 14:09:49 -0000	1.8
@@ -59,68 +59,26 @@
 
 <qandaset>
 
+<qandadiv><title>Interchange Installation</title>
 
-<qandadiv><title>How does Interchange work</title>
-
-<qandaentry>
+<qandaentry id="install-howto">
 <question><para>
-Where are the pages?
+How do I install Interchange?
 </para></question>
 <answer><para>
-&IC; pages are not kept in normal HTML space. Look in the catalog subdirectory pages. The pages are always filtered through the &IC; daemon before being delivered.
-</para>
-</answer></qandaentry>
-
-<qandaentry>
-<question><para>
-Where are the images?
-</para></question>
-<answer><para>
-&IC; is a &glos-CGI;; program, and if relative image paths were used, erroneous 
-&glos-img; output like the following would have occured:
-
-<programlisting><![CDATA[
-<img src="/cgi-bin/simple/../whatever.jpg">
-]]></programlisting>
-
-For that reason, by default, &IC; uses &conf-ImageDir; or
-&conf-ImageDirSecure; for a prefix used to rewrite image URLs.
-In the demo, image
-specs that have no absolute path information are prefixed with
-<literal>/simple/images/</literal>.
+&ICDEVGROUP; distributes &IC; in the basic format of &glos-tarball;s.
+To install &IC; this way, obtain the tarball from the &ICDL; page
+and read file &cvsfile-README;.
+</para><para>
+Besides tarballs, there are also "precompiled" packages available 
+for specific platforms. For &DEBGNU;, see file &cvsfile-README.debian;.
+For &RH; and derivatives, see file &cvsfile-README.rpm-dist;.
 </para><para>
-In an &IC; page, this tag:
-
-<programlisting><![CDATA[
-<img src="ordernow.gif">
-]]></programlisting>
-
-will become this:
-
-<programlisting><![CDATA[
-<img src="/simple/images/ordernow.gif">
-]]></programlisting>
-
-This tag:
-
-<programlisting><![CDATA[
-<img src="items/00-0011.jpg">
-]]></programlisting>
-
-will become this:
-
-<programlisting><![CDATA[
-<img src="/simple/images/items/00-0011.jpg">
-]]></programlisting>
-
-Absolute image paths are not affected. An image such as
-<literal>/other/images/whatever.gif</literal> will not be changed.
+Finally, you can install &IC; directly out of CVS to get a copy
+of the latest code. To do so, see file &cvsfile-README.cvs;.
 </para>
-</answer></qandaentry>
-
-</qandadiv>
-
-<qandadiv><title>Installation</title>
+</answer>
+</qandaentry>
 
 <qandaentry>
 <question><para>
@@ -200,8 +158,8 @@
 </para><para>
 
 The best way to set permissions on a multi-user system is to make all
-files group readable and writable (<literal>660</literal> or
-<literal>664</literal> &glos-mode;). If you have a
+files group readable and writable (&glos-mode; <literal>660</literal> or
+<literal>664</literal>). If you have a
 system setup that places each user in their own group, make
 <systemitem class='username'>interch</systemitem> a member of each user's
 group and set ownership and permissions with:
@@ -544,6 +502,67 @@
 </para>
 </answer></qandaentry>
 </qandadiv>
+
+<qandadiv><title>How does Interchange work</title>
+
+<qandaentry>
+<question><para>
+Where are the pages?
+</para></question>
+<answer><para>
+&IC; pages are not kept in normal HTML space. Look in the catalog subdirectory pages. The pages are always filtered through the &IC; daemon before being delivered.
+</para>
+</answer></qandaentry>
+
+<qandaentry>
+<question><para>
+Where are the images?
+</para></question>
+<answer><para>
+&IC; is a &glos-CGI;; program, and if relative image paths were used, erroneous 
+&glos-img; output like the following would have occured:
+
+<programlisting><![CDATA[
+<img src="/cgi-bin/simple/../whatever.jpg">
+]]></programlisting>
+
+For that reason, by default, &IC; uses &conf-ImageDir; or
+&conf-ImageDirSecure; for a prefix used to rewrite image URLs.
+In the demo, image
+specs that have no absolute path information are prefixed with
+<literal>/simple/images/</literal>.
+</para><para>
+In an &IC; page, this tag:
+
+<programlisting><![CDATA[
+<img src="ordernow.gif">
+]]></programlisting>
+
+will become this:
+
+<programlisting><![CDATA[
+<img src="/simple/images/ordernow.gif">
+]]></programlisting>
+
+This tag:
+
+<programlisting><![CDATA[
+<img src="items/00-0011.jpg">
+]]></programlisting>
+
+will become this:
+
+<programlisting><![CDATA[
+<img src="/simple/images/items/00-0011.jpg">
+]]></programlisting>
+
+Absolute image paths are not affected. An image such as
+<literal>/other/images/whatever.gif</literal> will not be changed.
+</para>
+</answer></qandaentry>
+
+</qandadiv>
+
 
 
 <qandadiv><title>SSL problems</title>



1.34      +2 -13     xmldocs/guides/iccattut.xml


rev 1.34, prev_rev 1.33
Index: iccattut.xml
===================================================================
RCS file: /var/cvs/xmldocs/guides/iccattut.xml,v
retrieving revision 1.33
retrieving revision 1.34
diff -u -r1.33 -r1.34
--- iccattut.xml	24 May 2005 21:42:18 -0000	1.33
+++ iccattut.xml	20 Oct 2005 14:09:49 -0000	1.34
@@ -126,19 +126,8 @@
 	<sect2 id='InterchangeandtheStandardDemoCatalogInstallation'>
 		<title>Interchange and the Standard Demo Catalog Installation</title>
 		<para>
-		The easiest way to prepare the environment (that is, install Interchange and the standard catalog) is to use installable packages prepared for you in the <firstterm>RPM</firstterm> (&RH;, SuSE or Mandrake Linux systems) or <firstterm>DEB</firstterm> (&DEBGNU;) formats. On Debian systems, run <userinput>apt-get install interchange interchange-ui interchange-cat-&std-catalog; interchange-doc</userinput>. For other formats, see the Interchange &ICDL; page.
-		</para>
-		<!--
-		<note><para>
-		Interchange version 5.2.0 is the last one to ship with the <emphasis>Foundation</emphasis> demo catalog. If you suspect you only have the old packages, install interchange-cat-foundation instead of interchange-cat-standard.
-		</para></note>
-		-->
-		<para>
-		You can also get Interchange by downloading and unpacking the basic Interchange tarball or checking out a copy of the &ICCVS; repository, and performing manual installation yourself. These installations can be done either as a regular user, or as root installing for a special Interchange user, but are out of scope of this tutorial.
-		</para> <para>
-		During the Debian package installation, you will be asked to select the Interchange username. To eliminate basic security issues, the Interchange daemon will not run as root, and it should not run as the web server user either. Therefore, a new system account to run the Interchange daemon will be created (<systemitem class='username'>interchange</systemitem> by default). With RPM packages, the default Interchange username will be <systemitem class='username'>interch</systemitem><footnote><para>There are a lot of packaging differences between Debian and Red Hat packages. Some are mandated by system policies (which is especially the case with Debian GNU), while others (such as the default username) reflect preferences of the package maintainers and the corresponding user groups.</para></footnote>.
-		</para> <para>
-		You must access the demo catalog to verify that your Interchange installation was successful. The interchange-cat-&std-catalog; package, containing catalog "&std-catalog;", was supposed to install itself and register with Interchange by modifying the main <filename moreinfo='refentry'>interchange.cfg</filename> config file (or some other file, such as <filename>/etc/interchange/catalogs.cfg</filename>, which logically puts all catalog definitions in a separate file and is read by <filename>interchange.cfg</filename>). The catalog should have also placed the <firstterm>link program</firstterm> in your <filename class='directory'>cgi-bin</filename> directory - the link program connects the web server software with the Interchange daemon. The demo catalog should be accessible by visiting the <ulink url="http://localhost/cgi-bin/ic/&std-catalog;/index.html">&Std-catalog;</ulink> (or <ulink url="http://localhost/cgi-bin/ic/&prev-catalog;/index.html">&Prev-catalog;</ulink>) Demo index page on your local host. (This also means you need to have a web server running, such as <application>Apache</application> or <application>mathopd</application>.)
+		For installation instructions, see
+		<olink targetdoc='faq' targetptr='install-howto'/> FAQ entry.
 		</para>
 	</sect2>
 		



1.2       +1 -1      xmldocs/guides/optimization.xml


rev 1.2, prev_rev 1.1
Index: optimization.xml
===================================================================
RCS file: /var/cvs/xmldocs/guides/optimization.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- optimization.xml	3 Sep 2005 17:09:47 -0000	1.1
+++ optimization.xml	20 Oct 2005 14:09:50 -0000	1.2
@@ -280,7 +280,7 @@
 				<para>
 				For repetitive routines, you can achieve a considerable savings
 				in CPU by pre-compiling your embedded &PERL; code. The precompilation
-				can occur either once at &conf-catalog; configuration time,
+				can occur either once at &glos-catalog; configuration time,
 				or once at time of list execution.
 				</para><para>
 				When you compile routines at the time of the list execution



1.13      +429 -374  xmldocs/guides/xmldocs.xml


rev 1.13, prev_rev 1.12
Index: xmldocs.xml
===================================================================
RCS file: /var/cvs/xmldocs/guides/xmldocs.xml,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- xmldocs.xml	3 Feb 2005 15:30:36 -0000	1.12
+++ xmldocs.xml	20 Oct 2005 14:09:50 -0000	1.13
@@ -1,409 +1,464 @@
-<sect1 id='XMLGuidelines'>
-	<title>XML Guidelines</title>
+<?xml version="1.0" standalone="no"?>
 
-	<sect2 id='XMLConventions'>
-		<title>XML Conventions</title>
-		<para>
-		Although you will be writing valid XML, there are few conventions
-		on top of XML that would be very good to follow:
-		</para>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook-Interchange XML V4.2//EN"
+	"../docbook/docbookxi.dtd">
 
-		<itemizedlist>
-			<listitem><para>
-			Always provide <literal>id=''</literal> parameter to sections that
-			get built to separate files in chunked HTML mode (this includes
-			the top-level elements like &lt;book&gt;s and &lt;article&gt;s, 
-			and first-level subelements, like &lt;chapter&gt;s and &lt;sect1&gt;s).
-			</para></listitem>
-			<listitem><para>
-			All <literal>id=''</literal>s you provide must be named after the
-			actual section title, with spaces condensed and first characters
-			capitalized. For example, "Introduction to Interchange" would become
-			<literal>id='IntroductiontoInterchange'</literal>.
-			</para></listitem>
-			<listitem><para>
-			Use built-in XML commands to link between sections and documents
-			where ever appropriate. If you're mentioning a resource for which
-			either a separate section or refentry exists in XMLDOCS (or is
-			completely external, such as a different website), please properly
-			mark that with XML.
-			</para></listitem>
-			<listitem><para>
-			If you have a longer phrase that keeps repeating every now and then
-			(and especially if it's also wrapped in some kind of a link element),
-			consider adding it as an XML entity to
-			<filename>docbook/literals.ent</filename> and then just refer to it
-			using the entity name; like you can write &amp;IC; to produce &IC;.
-			</para></listitem>
-			<listitem><para>
-			When ever you are documenting a particular item and you think you need
-			to mention some other item's properties there, you're running into a 
-			possible problem of spreading the documentation for a particular item
-			in many places which can go out of date.<sbr/>
-			So please avoid that, make all the details appear only once, and that
-			in the most appropriate place (which is, obviously, the original item
-			page).<sbr/>
-			Therefore, in such cases simply provide a link to the appropriate item
-			and describe its behavior or nuances there, on its own page (usually in
-			the general "Description" or "Notes" sections).
-			</para></listitem>
-			<listitem><para>
-			Always use spaces instead of TABs (2 spaces for 1 TAB) to indent
-			the text that will appear in the
-			generated output files (that includes sample external files and/or
-			code blocks that you directly include in the document). XML tolerates
-			TABs more or less, but doesn't like them. And it also causes problems
-			in fixed width outputs, like manpages.
-			</para></listitem>
-			<listitem><para>
-			For XML, you must write tags in all lowercase because there's no
-			other way, but please use only lowecase in HTML examples too, and
-			make the HTML code xhtml-compatible (in essence, the compatibility 
-			comes down to using all lowercase, quoting all option arguments, 
-			and closing all tags; i.e.: &lt;img src="..path.."/&gt;)
-			</para></listitem>
-		</itemizedlist>
-	</sect2>
+<article id='xmldocs'>
 
-	<sect2>
-		<title>Useful XML Tags</title>
+<articleinfo>
+	<title>Interchange Guides: XMLDOCS Authoring</title>
+	<titleabbrev>xmldocs</titleabbrev>
+
+	<copyright>
+		<year>2005</year>
+		<holder>Davor Ocelic</holder>
+	</copyright>
+	<copyright>
+		<year>2005</year>
+		<holder>Interchange Development Group</holder>
+	</copyright>
+
+	<authorgroup>
+		<author>
+			<firstname>Davor</firstname><surname>Ocelic</surname>
+			<email>docelic at icdevgroup.org</email>
+		</author>
+	</authorgroup>
+
+	<legalnotice>
+		<para>
+		This documentation is free; you can redistribute it and/or modify
+		it 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.
+		</para>
 		<para>
-		I have identified some of the most useful tags that we'll be using 
-		in XMLDOCS:
+		It is distributed in the hope that it will be useful,
+		but WITHOUT ANY WARRANTY; without even the implied warranty of
+		MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+		GNU General Public License for more details.
 		</para>
+	</legalnotice>
 
+	<abstract>
 		<para>
-		<ulink url="http://www.docbook.org/tdg/en/html/acronym.html">acronym</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/application.html">application</ulink> - software program name, such as <application>QuickBooks</application><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/arg.html">arg</ulink> - part of the cmdsynopsis element, such as <arg>value</arg> (it renders differently depnding on the type of argument - plain, required, or optional*)<sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/blockquote.html">blockquote</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/classname.html">classname</ulink> - Perl module name, such as <classname>Image::Size</classname><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/cmdsynopsis.html">cmdsynopsis</ulink> - the parent element for all synopsis lines<sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/code.html">code</ulink> - chunks of actual code. Use to display ITL/Perl/any-other code examples inline, suc as <code>[scratch tempvar]</code><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/command.html">command</ulink> - computer command name (usually Unix command), such as <command>ls</command><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/computeroutput.html">computeroutput</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/constant.html">constant</ulink>, such as <constant>MAXPATHLEN</constant><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/database.html">database</ulink> - everything related to a database. See class='' option to it; such as field <database class='field'>sku</database><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/emphasis.html">emphasis</ulink> - renders as <emphasis>italic</emphasis> or <emphasis role='bold'>bold with role='bold'</emphasis><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/envar.html">envar</ulink> - environment variable, usually as seen by the web server or IC, such as <envar>REMOTE_PORT</envar><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/errorcode.html">errorcode</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/errorname.html">errorname</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/errortext.html">errortext</ulink> - such as <errortext>Page not found</errortext><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/errortype.html">errortype</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/example.html">example</ulink> - parent element for all examples<sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/filename.html">filename</ulink> - file and directory (class='directory') names, such as <filename>/etc/syslog.conf</filename><sbr/>
-		filter - Interchange filter name (XMLDOCS extension to DocBook XML), such as <filter>entities</filter><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/firstterm.html">firstterm</ulink> - first occurence of a term. Renders as italic<sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/footnote.html">footnote</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/function.html">function</ulink> - function name, such as <function>syscall64()</function><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/group.html">group</ulink> - grouping of args inside cmdsynopsis<sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/guibutton.html">guibutton</ulink> - identify buttons in the (web) gui, such as <guibutton>Finalize!</guibutton><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/guiicon.html">guiicon</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/guilabel.html">guilabel</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/guimenu.html">guimenu</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/guimenuitem.html">guimenu</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/guisubmenu.html">guisubmenu</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/hardware.html">hardware</ulink> - piece of hardware, such as <hardware>motherboard</hardware><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/important.html">important</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/itemizedlist.html">itemizedlist</ulink> - most commonly used type of list<sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/keysym.html">keysym</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/keyword.html">keyword</ulink> - identifies a word as important for the document categorization/search<sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/link.html">link</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/listitem.html">listitem</ulink> - element inside itemizedlist<sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/literal.html">literal</ulink> - literal (verbatim) value, such as <literal>standard keep</literal><sbr/>
-		mv - identify form variable, such as <mv>mv_return_all</mv> (XMLDOCS extension to DocBook XML)<sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/note.html">note</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/olink.html">olink</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/option.html">option</ulink> - use it to mark Interchange config directives (like say, <option>MailOrderTo</option> or <option>Variable</option>)<sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/para.html">para</ulink> - the standard paragraph element<sbr/>
-		pragma - Interchange pragma name (XMLDOCS extension to DocBook XML), such as <pragma>no_html_comment_embed</pragma><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/productname.html">productname</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/programlisting.html">programlisting</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/prompt.html">prompt</ulink> - computer prompt, such as <prompt>Login:</prompt><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/replaceable.html">replaceable</ulink> - identified the replaceable part in the cmdsynopsis element<sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/returnvalue.html">returnvalue</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/sbr.html">sbr</ulink> - starts a newline. Useful in cmdsynopsis or if you don't want to split the paragraph in two, which then generates a wide spacing<sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/screen.html">screen</ulink> - used as element in which you display existing interchange source (this is mostly in autogenerated pages but can be used manually)<sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/subscript.html">subscript</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/superscript.html">superscript</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/systemitem.html">systemitem</ulink> - various system items, see possible class='' values<sbr/>
-		tag - Interchange tag name (XMLDOCS extension to DocBook XML), such as <tag>include</tag> or <tag>data</tag><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/term.html">term</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/tip.html">tip</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/ulink.html">ulink</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/userinput.html">userinput</ulink> - similar to &lt;command&gt; but here you can also include parameters, actually the complete command line the user would run, such as <userinput>ls /etc</userinput><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/varname.html">varname</ulink> - global or catalog Interchange variable, such as <varname>MV_PAGE</varname> or <varname>UI_IMAGE_DIR</varname><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/warning.html">warning</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/wordasword.html">wordasword</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/xref.html">xref</ulink><sbr/>
 		</para>
+	</abstract>
 
-	</sect2>
-</sect1>
+</articleinfo>
 
-<sect1 id="Conclusion">
-	<title>Conclusion</title>
-	<para>
-	I believe I have succeeded in making XMLDOCS fairly convenient to author
-	new documents and keep them current with time.
-	</para>
+
+<sect1>
+	<title>XMLDocs Basics</title>
 	<para>
-	If we want to make &IC; recognized globally (for which it definitely
-	has the perspective, but it's not there just yet), then having a complete,
-	up to date, clear and verbose documentation set is something that's
-	almost implied.
+	Since XMLDOCS is based on &DOCBOOK; XML, the usual DocBook XML rules apply:
+	XML markup consists of XML "tags" (same style as &glos-HTML; tags), but
+	all of which must be opened (and closed &mdash; you cannot omit the
+	closing tag) respecting the hierarchy of tags within a document.
+	In addition, attributes must always be quoted. These two rules
+	are non-negotiable with DocBook XML. Here's an example:
+<screen><![CDATA[
+<?xml version="1.0" standalone="no"?>
+
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook-Interchange XML V4.2//EN"
+	"../docbook/docbookxi.dtd">
+
+<article id='xmldocs'>
+
+<sect1>
+	<title>Test title</title>
+
+  <para> <!-- COMMENT: Beginning of a paragraph -->
+  
+  It is <emphasis>very</emphasis> important to read this line.
+  Some lines are <emphasis role='bold'>boldly bolder</emphasis> than others.
+  The <database>products</database> database contains products.
+  </para>
+</sect1>
+
+</article>
+]]></screen>
+	As you can see, XML can look structured and all, but there's so much overhead
+	involved in writing XML documentation. For example, I wouldn't know offhand
+	how to define DOCTYPE properly &mdash; I just took the effort of learning it
+	once, and I kept copy/pasting it ever since.
+	</para><para>
+	XMLDOCS aims to be as overhead-free and efficient as possible to write.
+	This, however, leads us to mention <emphasis>four</emphasis> main differences
+	between DocBook XML and XMLDOCS:
+	<itemizedlist>
+	<listitem><para>
+	A lot of XMLDOCS markup <emphasis role='bold'>and</emphasis> content is
+	autogenerated. For example, all &IC; source code shown is taken
+	out of CVS, and is therefore always up to date. The same goes for
+	information such as say, file version numbers and modification times.
+	</para></listitem>
+	<listitem><para>
+	Instead of writing complete XML documents (those that contain XML
+	"head and tail" and would be valid if taken standalone), you only need to
+	provide short blocks of input to predefined "slots". These slots
+	already provide all needed XML wrapping, so you can get onto writing
+	actual text right away. For example, the opening
+	<literal>&lt;para&gt;</literal> and the closing
+	<literal>&lt;/para&gt;</literal> are always part of the template, so
+	you can (and infact, must) simply omit them when filling in the
+	documentation slots.
+	</para></listitem>
+	<listitem><para>
+	DocBook XML supports "entities". Entities are something like variables
+	and are inserted using
+	<literal><replaceable>&amp;NAME;</replaceable></literal> syntax.
+	XMLDOCS contain a ton of predefined &IC;-suitable entities, to both
+	reduce typing
+	and "formalize" the look and feel. Compare the clarity and convenience
+	of the below examples:
+<screen><![CDATA[
+<!-- Generic DocBook XML way: -->
+Please see the <olink targetdoc='confs' targetptr='Catalog'><option>Catalog</option></olink> configuration directive.
+
+<!-- XMLDOCS way: -->
+Please see the &conf-Catalog; configuration directive.
+
+
+<!-- Or, another example: -->
+
+Add the following to your <filename>catalog.cfg</filename>:
+
+Add the following to your &ccf;:
+]]></screen>
+	</para></listitem>
+	<listitem><para>
+	In XMLDOCS, we use a controlled set of XML tags, plus few &IC;-specific
+	ones. For example, all &PERL; functions are marked up using 
+	DocBook XML's &lt;function&gt;, while all "mv" variables are marked up using
+	our custom &lt;mv&gt; tag.
+	</para></listitem>
+	</itemizedlist>
 	</para>
+</sect1>
+
+<sect1>
+	<title>XMLDOCS Set of Tags</title>
 	<para>
-	It would be best if all developers would write both the pieces of
-	software and the accompanying documentation. However,
-	from the past I have somehow seen that you are not too willing
-	to write the documentation (or that was because of all the problems with
-	the old documentation system).
+	Here's the reduced set of DocBook XML tags (and our custom ones) at your
+	disposal in XMLDOCS (in alphabetical order):
 	</para>
+
 	<para>
-	So, the bottom line is that I really want you to write the documentation,
-	but I will not impose any requirements on the structure. That means
-	you can:
+	<ulink url="http://www.docbook.org/tdg/en/html/application.html">application</ulink> - software program name, such as <application>QuickBooks</application><sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/arg.html">arg</ulink> - part of the Synopsis line, can be used with choice = <literal>plain</literal>, <literal>opt</literal> (default) or <literal>required</literal> to decorate argument with nothing, [], or {} appropriately <sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/blockquote.html">blockquote - quotes, citations</ulink><sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/classname.html">classname</ulink> - Perl module name, such as <classname>Image::Size</classname><sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/code.html">code</ulink> - chunks of actual code. Use to display ITL/Perl/any-other code examples inline, such as <code>[scratch tempvar]</code><sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/command.html">command</ulink> - computer command name (usually Unix command), such as <command>ls</command><sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/computeroutput.html">computeroutput</ulink> - output as you would get from a computer, such as the output of <command>ls</command><sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/constant.html">constant</ulink>, such as <constant>MAXPATHLEN</constant><sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/database.html">database</ulink> - everything related to a database. Used to mark up tables or table fields (use class='field' attribute for fields), such as <database>products</database> or <database class='field'>sku</database><sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/emphasis.html">emphasis</ulink> - renders as <emphasis>italic</emphasis> or <emphasis role='bold'>bold with role='bold'</emphasis><sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/envar.html">envar</ulink> - environment variable, usually as seen by the web server or IC, such as <envar>REMOTE_PORT</envar><sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/errorcode.html">errorcode</ulink> - some error code, such as <errorcode>6</errorcode><sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/errorname.html">errorname</ulink> - error name, such as <errorname>ENOENT</errorname><sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/errortext.html">errortext</ulink> - such as <errortext>Page not found</errortext><sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/filename.html">filename</ulink> - file and directory (class='directory') names, such as <filename>/etc/syslog.conf</filename> or <filename class='directory'>/etc/init.d/</filename><sbr/>
+	filter - Interchange filter name (XMLDOCS extension to DocBook XML), such as <filter>entities</filter><sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/function.html">function</ulink> - function name, such as <function>syscall64()</function><sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/group.html">group</ulink> - grouping of arguments inside Synopsis line<sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/guibutton.html">guibutton</ulink> - identify buttons in the web gui, such as <guibutton>Finalize!</guibutton><sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/guiicon.html">guiicon</ulink> - icon in the web gui<sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/guilabel.html">guilabel</ulink> - label in the web GUI<sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/guimenu.html">guimenu</ulink> - menu in the web GUI<sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/guisubmenu.html">guisubmenu</ulink> - submenu in the web gui<sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/hardware.html">hardware</ulink> - piece of hardware, such as <hardware>motherboard</hardware><sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/important.html">important</ulink> - important block, stands out<sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/itemizedlist.html">itemizedlist</ulink> - wrapper for a bulleted list<sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/keysym.html">keysym</ulink> - Key sym, such as <keysym>Ctrl+c</keysym><sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/listitem.html">listitem</ulink> - element inside itemizedlist<sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/literal.html">literal</ulink> - every literal (verbatim) value, such as <literal>standard keep</literal><sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/note.html">note</ulink> - note block, stands out<sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/olink.html">olink</ulink> - linking between separate documents<sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/para.html">para</ulink> - the standard paragraph element, used all over the place<sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/programlisting.html">programlisting</ulink> - example of code or text that the user is supposed to enter<sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/replaceable.html">replaceable</ulink> - identify replaceable parts everywhere, such as <replaceable>PID</replaceable> in <command>kill -9 <replaceable>PID</replaceable></command><sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/returnvalue.html">returnvalue</ulink> - command return value<sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/sbr.html">sbr</ulink> - starts a newline. Useful in Synopsis, or if you don't want to split the paragraph in two, which then generates a wide spacing<sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/screen.html">screen</ulink> - used as element in which you display existing interchange source (this is mostly in autogenerated pages but can be used manually)<sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/subscript.html">subscript</ulink><sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/superscript.html">superscript</ulink><sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/systemitem.html">systemitem</ulink> - various system items, see possible class="" values<sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/tip.html">tip</ulink> - tip block, stands out<sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/ulink.html">ulink</ulink> - link to external resources<sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/warning.html">warning</ulink> - warning block, stands out<sbr/>
+	<ulink url="http://www.docbook.org/tdg/en/html/xref.html">xref</ulink> - link within the same document<sbr/>
 	</para>
 
-	<itemizedlist>
-		<listitem><para>
-		Update the existing files with proper XML formatting, or
-		</para></listitem>
-		<listitem><para>
-		Update the existing files <emphasis>without</emphasis> properly tagging
-		everything. I will be monitoring all commits and I am willing to fix
-		all the formatting if you're willing to write the docs in the first
-		place. Or, 
-		</para></listitem>
-		<listitem><para>
-		Provide verbose commit messages <emphasis>and state that you will
-		not</emphasis> update the documentation, so me or Racke will reformat
-		it properly and commit it to XMLDOCS, or
-		</para></listitem>
-		<listitem><para>
-		You can write completely unformated text without even using XML and
-		commit it somewhere in the
-		<filename class='directory'>pending/</filename> directory. Me or Racke
-		would pick it up and properly update the docs. Just please include 
-		enough information (be as verbose as possible), so that we have enough
-		words we can rephrase and enough information to work on.
-		</para></listitem>
-	</itemizedlist>
+</sect1>
+</article>
 
-	<para>
-	Also, commit any goodies you might have to
-	<filename class='directory'>pending/</filename>.
-	</para>
+<!--
+
+<sect1 id="Conclusion">
+<title>Conclusion</title>
+<para>
+I believe I have succeeded in making XMLDOCS fairly convenient to author
+new documents and keep them current with time.
+</para>
+<para>
+If we want to make &IC; recognized globally (for which it definitely
+has the perspective, but it's not there just yet), then having a complete,
+up to date, clear and verbose documentation set is something that's
+almost implied.
+</para>
+<para>
+It would be best if all developers would write both the pieces of
+software and the accompanying documentation. However,
+from the past I have somehow seen that you are not too willing
+to write the documentation (or that was because of all the problems with
+the old documentation system).
+</para>
+<para>
+So, the bottom line is that I really want you to write the documentation,
+but I will not impose any requirements on the structure. That means
+you can:
+</para>
+
+<itemizedlist>
+	<listitem><para>
+	Update the existing files with proper XML formatting, or
+	</para></listitem>
+	<listitem><para>
+	Update the existing files <emphasis>without</emphasis> properly tagging
+	everything. I will be monitoring all commits and I am willing to fix
+	all the formatting if you're willing to write the docs in the first
+	place. Or, 
+	</para></listitem>
+	<listitem><para>
+	Provide verbose commit messages <emphasis>and state that you will
+	not</emphasis> update the documentation, so me or Racke will reformat
+	it properly and commit it to XMLDOCS, or
+	</para></listitem>
+	<listitem><para>
+	You can write completely unformated text without even using XML and
+	commit it somewhere in the
+	<filename class='directory'>pending/</filename> directory. Me or Racke
+	would pick it up and properly update the docs. Just please include 
+	enough information (be as verbose as possible), so that we have enough
+	words we can rephrase and enough information to work on.
+	</para></listitem>
+</itemizedlist>
+
+<para>
+Also, commit any goodies you might have to
+<filename class='directory'>pending/</filename>.
+</para>
 
 </sect1>
 
 
 <sect1 id='FileFormats'>
-	<title>File Formats</title>
+<title>File Formats</title>
 
+<para>
+<emphasis role='bold'>
+This is an irrelevant section. Read it only if the examples from the
+already written documentation are not enough, and you need some more 
+hints.
+</emphasis>
+</para>
+
+<para>
+There are few different file types whose structure needs to be specified:
+</para>
+
+<sect2>
+	<title>Guides</title>
+	<para>
+	Guides use no pre-processing and are written in pure XML. There
+	is a simple "preprocessor" script I wrote in <filename>bin/pp</filename>,
+	but it's up to you to put the source through it and commit valid XML
+	to the CVS. For the usage examples and features, see script header.
+	(It comes handy when you're writing large portions of XML from scratch).
+	What you can use are, of course - just like in any other XML chunk,
+	the XML entities defined in <filename>docbook/literals.ent</filename> and
+	<filename>docbook/autodefs.ent</filename>. For manual entity definitions,
+	always use the former file; the latter is autogenerated and automaintained.
+	</para>
+</sect2>
+
+<sect2>
+	<title>HOW-TOs</title>
 	<para>
-	<emphasis role='bold'>
-	This is an irrelevant section. Read it only if the examples from the
-	already written documentation are not enough, and you need some more 
-	hints.
-	</emphasis>
+	HOW-TOs do not use any preprocessing/autogenerating layer either, but 
+	are included in the main <filename>howtos/howtos.xml</filename> file, so
+	the chunks you write must not be standalone. The parent element you need
+	to use is the XML's &lt;chapter&gt; tag, without any XML document type.
+	Existing HOW-TOs provide excellent quickstarts.
 	</para>
+</sect2>
 
+<sect2>
+	<title>Symbols</title>
+	<para>
+	Symbols are a little different. In general, the symbol refentry pages
+	already contain all the fields, you only need to provide contents for
+	them. To minimize overhead, fields have some default headers and footers
+	which you then can (and, infact, must) omit from your chunks.
+	</para>
 	<para>
-	There are few different file types whose structure needs to be specified:
+	You can also create more sections that begin with the same name, and
+	are then appended one after another. This is most suitable
+	for examples, so see <xref linkend='Example'/>.
 	</para>
+	<para>
+	In general, all files are handled generically and will be included
+	if you name them after the appropriate refentry page section that you want
+	to modify. Keep in mind that all files (other than the "strong" 
+	<filename>control</filename> one, which is available with multi-file
+	method only) append instead of overriding existing
+	information.
+	</para>
+
+	<sect3>
+		<title>control</title>
+		<para>
+		The <filename>control</filename> file contains "key: value" pairs
+		on each line. Comments (#....) can be used at the beginning of the line.
+		Otherwise, 'value's are left-trimmed and then recorded <literal>verbatim
+		</literal>.
+		</para>
+		<para>
+		Note that the values in this file override (do not append!)
+		information already known to the generator script (if any).
+		</para>
+		<para>
+		"Keys" can be anything, but some of them have a special meaning (and
+		defining any others makes no sense except for future functionality),
+		and some of them must be specified because they have no useful
+		defaults:
+
+		<itemizedlist>
+			<listitem><para>
+				purpose: one-line description. No default, must be specified.
+			</para></listitem>
+			<listitem><para>
+				default: default value. This is symbol-dependent (it makes sense
+				with, for example, pragmas or global variables). For other symbols
+				(say, tags), this is unused.
+			</para></listitem>
+			<listitem><para>
+				missing: A free-form text that is appended to <filename>tmp/missing</filename> entry for a particular item. Good for a per-item TODO list and important notes. While <filename>tmp/missing</filename> is not empty, you must not feel bored :)
+			</para></listitem>
+			<listitem><para>
+				author: specific symbol's/feature's author.
+				ICDEVGROUP members are specified like "&amp;docelic;amp;,
+				&amp;ICDEVGROUP;", where the username and ICDEVGROUP entities expand
+				to a suitable
+				strings (full name, and full team name with link currently - this
+				is defined in <filename>docbook/literals.ent</filename>).
+				If no author is
+				specified, the default shows the team name, not mentioning any
+				individual specifically.<sbr/>
+				3rd party people need to be specified in the same way (
+				name and email with optional group name), such as in a silly 
+				example of "Mirko Star &lt;mstar at aol.com&gt;". If the person
+				is expected to contribute more often, adding an entity in
+				the <filename>literals</filename> for him/her is okay.
+			</para></listitem>
+			<listitem><para>
+				ignore: Usually you specify it only if you want to ignore an item
+				(cause it not to be autogenerated and visible). "ignore: yes" works
+				fine.
+			</para></listitem>
+			<listitem><para>
+				see also: very powerful feature. List related symbol names, system
+				commands or other arbitrary items. Non-IC symbols listed get passed
+				as-is, IC symbols get rendered with a clickable link to the item
+				and the connection is automatically 2-way (if you mention "B" in 
+				"A"'s See Also list, the B's list will automatically get A in its
+				see also list).<sbr/>
+				On items that begin with "&lt;" (that is, on those that seem to be
+				formatted already), no special processing is done and are included
+				verbatim.
+			</para></listitem>
+		</itemizedlist>
+		</para>
+	</sect3>
 
-	<sect2>
-		<title>Guides</title>
+	<sect3>
+		<title>synopsis</title>
 		<para>
-		Guides use no pre-processing and are written in pure XML. There
-		is a simple "preprocessor" script I wrote in <filename>bin/pp</filename>,
-		but it's up to you to put the source through it and commit valid XML
-		to the CVS. For the usage examples and features, see script header.
-		(It comes handy when you're writing large portions of XML from scratch).
-		What you can use are, of course - just like in any other XML chunk,
-		the XML entities defined in <filename>docbook/literals.ent</filename> and
-		<filename>docbook/autodefs.ent</filename>. For manual entity definitions,
-		always use the former file; the latter is autogenerated and automaintained.
-		</para>
-	</sect2>
-
-	<sect2>
-		<title>HOW-TOs</title>
-		<para>
-		HOW-TOs do not use any preprocessing/autogenerating layer either, but 
-		are included in the main <filename>howtos/howtos.xml</filename> file, so
-		the chunks you write must not be standalone. The parent element you need
-		to use is the XML's &lt;chapter&gt; tag, without any XML document type.
-		Existing HOW-TOs provide excellent quickstarts.
-		</para>
-	</sect2>
-
-	<sect2>
-		<title>Symbols</title>
-		<para>
-		Symbols are a little different. In general, the symbol refentry pages
-		already contain all the fields, you only need to provide contents for
-		them. To minimize overhead, fields have some default headers and footers
-		which you then can (and, infact, must) omit from your chunks.
-		</para>
-		<para>
-		You can also create more sections that begin with the same name, and
-		are then appended one after another. This is most suitable
-		for examples, so see <xref linkend='Example'/>.
-		</para>
-		<para>
-		In general, all files are handled generically and will be included
-		if you name them after the appropriate refentry page section that you want
-		to modify. Keep in mind that all files (other than the "strong" 
-		<filename>control</filename> one, which is available with multi-file
-		method only) append instead of overriding existing
-		information.
-		</para>
-
-		<sect3>
-			<title>control</title>
-			<para>
-			The <filename>control</filename> file contains "key: value" pairs
-			on each line. Comments (#....) can be used at the beginning of the line.
-			Otherwise, 'value's are left-trimmed and then recorded <literal>verbatim
-			</literal>.
-			</para>
-			<para>
-			Note that the values in this file override (do not append!)
-			information already known to the generator script (if any).
-			</para>
-			<para>
-			"Keys" can be anything, but some of them have a special meaning (and
-			defining any others makes no sense except for future functionality),
-			and some of them must be specified because they have no useful
-			defaults:
-
-			<itemizedlist>
-				<listitem><para>
-					purpose: one-line description. No default, must be specified.
-				</para></listitem>
-				<listitem><para>
-					default: default value. This is symbol-dependent (it makes sense
-					with, for example, pragmas or global variables). For other symbols
-					(say, tags), this is unused.
-				</para></listitem>
-				<listitem><para>
-					missing: A free-form text that is appended to <filename>tmp/missing</filename> entry for a particular item. Good for a per-item TODO list and important notes. While <filename>tmp/missing</filename> is not empty, you must not feel bored :)
-				</para></listitem>
-				<listitem><para>
-					author: specific symbol's/feature's author.
-					ICDEVGROUP members are specified like "&amp;docelic;amp;,
-					&amp;ICDEVGROUP;", where the username and ICDEVGROUP entities expand
-					to a suitable
-					strings (full name, and full team name with link currently - this
-					is defined in <filename>docbook/literals.ent</filename>).
-					If no author is
-					specified, the default shows the team name, not mentioning any
-					individual specifically.<sbr/>
-					3rd party people need to be specified in the same way (
-					name and email with optional group name), such as in a silly 
-					example of "Mirko Star &lt;mstar at aol.com&gt;". If the person
-					is expected to contribute more often, adding an entity in
-					the <filename>literals</filename> for him/her is okay.
-				</para></listitem>
-				<listitem><para>
-					ignore: Usually you specify it only if you want to ignore an item
-					(cause it not to be autogenerated and visible). "ignore: yes" works
-					fine.
-				</para></listitem>
-				<listitem><para>
-					see also: very powerful feature. List related symbol names, system
-					commands or other arbitrary items. Non-IC symbols listed get passed
-					as-is, IC symbols get rendered with a clickable link to the item
-					and the connection is automatically 2-way (if you mention "B" in 
-					"A"'s See Also list, the B's list will automatically get A in its
-					see also list).<sbr/>
-					On items that begin with "&lt;" (that is, on those that seem to be
-					formatted already), no special processing is done and are included
-					verbatim.
-				</para></listitem>
-			</itemizedlist>
-			</para>
-		</sect3>
-
-		<sect3>
-			<title>synopsis</title>
-			<para>
-			The <filename>synopsis</filename> file needs to contain a block
-			that depends on the symbol type being documented. Just copy an 
-			existing one from the same symbol group.
-			</para>
-			<para>
-			The synopsis must be provided, or the appropriate "missing"
-			entry appears in <filename>tmp/missing</filename>.
-			</para>
-		</sect3>
-
-		<sect3 id='Description'>
-			<title>description</title>
-			<para>
-			This file is meant to contain prose and is pre-wrapped in 
-			the &lt;para&gt; tag. If, for the purpose of your description, you
-			need new paragraphs, simply use &lt;/para&gt;&lt;para&gt; to 
-			separate them, but always omit the starting &lt;para&gt; and 
-			ending &lt;/para&gt;.
-			</para>
-			<para>
-			Note that this is only possible because our Perl scripts do the 
-			merging before the source XML is passed to the XML tools; if XML
-			tools had to deal with this directly, you'd get a "chunk not balanced"
-			error and it wouldn't be possible (well, at least not without
-			entities).
-			</para>
-			<para>
-			The description must be provided, or the appropriate "missing"
-			entry appears in <filename>tmp/missing</filename>.
-			</para>
-		</sect3>
-
-		<sect3>
-			<title>notes</title>
-			<para>
-			Same as <xref linkend='Description'/>. May be left empty.
-			</para>
-		</sect3>
-
-		<sect3 id='Example'>
-			<title>example*</title>
-			<para>
-			The example files must contain an &lt;example&gt; element (which 
-			usually contains the &lt;title&gt;, short &lt;para&gt; with description
-			and &lt;programlisting&gt; with the actual code or syntax to be shown).
-			</para>
-			<para>
-			It is possible (and welcomed) to have multiple example files. They will
-			all be added as separate examples, and their order in the documentation
-			will be dictated by their alphabetical order on the filesystem
-			(the order in which readdir() reads them). Simply name additional files
-			following the regex: /example[\-\.\+_:\d].*/.
-			</para>
-			<para>
-			At least one example must be provided, or the appropriate "missing"
-			entry appears in <filename>tmp/missing</filename>.
-			</para>
-		</sect3>
-			
-	</sect2>
-
-	<sect2>
-		<title>Glossary</title>
-		<para>
-		The glossary skeleton is autogenerated. All you need to do is place
-		items in the <filename class='directory'>glossary/</filename>
-		directory. Each file there (filename is irrelevant) must contain a
-		valid &lt;glossentry&gt; element. See <filename>glossary/pragma</filename>
-		for an example.
+		The <filename>synopsis</filename> file needs to contain a block
+		that depends on the symbol type being documented. Just copy an 
+		existing one from the same symbol group.
 		</para>
-	</sect2>
-	
+		<para>
+		The synopsis must be provided, or the appropriate "missing"
+		entry appears in <filename>tmp/missing</filename>.
+		</para>
+	</sect3>
+
+	<sect3 id='Description'>
+		<title>description</title>
+		<para>
+		This file is meant to contain prose and is pre-wrapped in 
+		the &lt;para&gt; tag. If, for the purpose of your description, you
+		need new paragraphs, simply use &lt;/para&gt;&lt;para&gt; to 
+		separate them, but always omit the starting &lt;para&gt; and 
+		ending &lt;/para&gt;.
+		</para>
+		<para>
+		Note that this is only possible because our Perl scripts do the 
+		merging before the source XML is passed to the XML tools; if XML
+		tools had to deal with this directly, you'd get a "chunk not balanced"
+		error and it wouldn't be possible (well, at least not without
+		entities).
+		</para>
+		<para>
+		The description must be provided, or the appropriate "missing"
+		entry appears in <filename>tmp/missing</filename>.
+		</para>
+	</sect3>
+
+	<sect3>
+		<title>notes</title>
+		<para>
+		Same as <xref linkend='Description'/>. May be left empty.
+		</para>
+	</sect3>
+
+	<sect3 id='Example'>
+		<title>example*</title>
+		<para>
+		The example files must contain an &lt;example&gt; element (which 
+		usually contains the &lt;title&gt;, short &lt;para&gt; with description
+		and &lt;programlisting&gt; with the actual code or syntax to be shown).
+		</para>
+		<para>
+		It is possible (and welcomed) to have multiple example files. They will
+		all be added as separate examples, and their order in the documentation
+		will be dictated by their alphabetical order on the filesystem
+		(the order in which readdir() reads them). Simply name additional files
+		following the regex: /example[\-\.\+_:\d].*/.
+		</para>
+		<para>
+		At least one example must be provided, or the appropriate "missing"
+		entry appears in <filename>tmp/missing</filename>.
+		</para>
+	</sect3>
+		
+</sect2>
+
+<sect2>
+	<title>Glossary</title>
+	<para>
+	The glossary skeleton is autogenerated. All you need to do is place
+	items in the <filename class='directory'>glossary/</filename>
+	directory. Each file there (filename is irrelevant) must contain a
+	valid &lt;glossentry&gt; element. See <filename>glossary/pragma</filename>
+	for an example.
+	</para>
+</sect2>
+
 </sect1>
 
 </article>
-
+-->



1.2       +1 -1      xmldocs/refs/AccumulateCode


rev 1.2, prev_rev 1.1
Index: AccumulateCode
===================================================================
RCS file: /var/cvs/xmldocs/refs/AccumulateCode,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- AccumulateCode	12 Aug 2005 12:41:51 -0000	1.1
+++ AccumulateCode	20 Oct 2005 14:09:50 -0000	1.2
@@ -24,7 +24,7 @@
 </para><para>
 Over time, as you access pages and routines, a full set of tags
 will be developed and you can then disable &conf-AccumulateCode;.
-(Infact, &code-AccumulateCode; is recommended for development and should 
+(Infact, &conf-AccumulateCode; is recommended for development and should 
 really be turned off in production systems).
 __END__
 



1.3       +5 -4      xmldocs/refs/AutoModifier


rev 1.3, prev_rev 1.2
Index: AutoModifier
===================================================================
RCS file: /var/cvs/xmldocs/refs/AutoModifier,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- AutoModifier	22 Sep 2005 20:05:57 -0000	1.2
+++ AutoModifier	20 Oct 2005 14:09:50 -0000	1.3
@@ -25,12 +25,12 @@
 In other words, 
 when an item is added to the shopping cart using &IC;'s routines, the
 attributes declared in &conf-AutoModifier; will be set to the values of the
-fields in the <database>products database</database>.
+fields in the <database>products</database> database.
 </para><para>
 This facility will often be used in determining pricing, shipping,
-or other custom product attributes. These attributes are usually used
-in custom embedded Perl code which will scan the items in the shopping
-cart and make decisions.
+or other custom product attributes. These attributes will probably
+be used in a custom &PERL; code which will scan the items in the electronic
+&glos-cart; and make decisions.
 __END__
 
 __NAME__ notes
@@ -84,3 +84,4 @@
 
 __END__
 
+TODO Fix example section



1.3       +1 -1      xmldocs/refs/CodeRepository


rev 1.3, prev_rev 1.2
Index: CodeRepository
===================================================================
RCS file: /var/cvs/xmldocs/refs/CodeRepository,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- CodeRepository	12 Aug 2005 12:41:51 -0000	1.2
+++ CodeRepository	20 Oct 2005 14:09:50 -0000	1.3
@@ -48,7 +48,7 @@
 </para><para>
 Over time, as you access pages and routines, a full set of tags
 will be developed and you can then disable &conf-AccumulateCode;.
-(Infact, &code-AccumulateCode; is recommended for development and should 
+(Infact, &conf-AccumulateCode; is recommended for development and should 
 really be turned off in production systems).
 __END__
 



1.3       +0 -3      xmldocs/refs/XHTML


rev 1.3, prev_rev 1.2
Index: XHTML
===================================================================
RCS file: /var/cvs/xmldocs/refs/XHTML,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- XHTML	21 May 2005 11:09:24 -0000	1.2
+++ XHTML	20 Oct 2005 14:09:50 -0000	1.3
@@ -20,9 +20,6 @@
 in standalone tag endings, since argument name lowercasing and argument
 option quoting (the other two "things" that make XHTML XHTML)
 have been already adopted practices for all HTML output.
-</para><para>
-To illustrate with an example, tere's say, &tag-br; tag that will, by default,
-output &lt;br&gt;, or &lt;br/&gt; if &conf-XHTML; is in effect.
 __END__
 
 __NAME__ notes



1.2       +54 -0     xmldocs/refs/currency.tag


rev 1.2, prev_rev 1.1
Index: currency.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/currency.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- currency.tag	17 Feb 2005 23:25:39 -0000	1.1
+++ currency.tag	20 Oct 2005 14:09:50 -0000	1.2
@@ -0,0 +1,54 @@
+__NAME__ purpose
+format number (usually a price) according to currency settings
+__END__
+
+
+__NAME__ see also
+price,Locale,PriceCommas,PriceDivide
+__END__
+
+
+__NAME__ synopsis
+<row>
+	<entry>
+	convert
+	</entry>
+	<entry>Yes</entry>
+	<entry></entry>
+	<entry>0</entry>
+	<entry>Convert the value according to the &conf-PriceDivide; value
+	for the current locale?</entry>
+</row>
+<row>
+	<entry>
+	noformat
+	</entry>
+	<entry>Yes</entry>
+	<entry></entry>
+	<entry>0</entry>
+	<entry>Do not format the price?</entry>
+</row>
+&ROW_INTERPOLATE_0;
+&ROW_REPARSE_1;
+__END__
+
+__NAME__ description
+The tag returns the price for a specified product.
+__END__
+
+
+__NAME__ online: Basic example
+<programlisting>
+[currency]4[/currency]
+</programlisting>
+__END__
+
+__NAME__ online: Displaying currency according to PriceDivide
+Provided that the &conf-PriceDivide; configuration directive is set
+to <literal>0.167</literal>, the following example would display 
+<literal>8.982,04</literal>:
+<programlisting>
+[currency convert=1] [calc] 500.00 + 1000.00 [/calc] [/currency]
+</programlisting>
+__END__
+



1.2       +34 -42    xmldocs/refs/dbi_quote.filter


rev 1.2, prev_rev 1.1
Index: dbi_quote.filter
===================================================================
RCS file: /var/cvs/xmldocs/refs/dbi_quote.filter,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- dbi_quote.filter	4 Oct 2005 19:59:43 -0000	1.1
+++ dbi_quote.filter	20 Oct 2005 14:09:50 -0000	1.2
@@ -3,64 +3,56 @@
 __END__
 
 __NAME__ see also
-the sql filter
-the query tag and [PREFIX-quote] sub-tag
+sql,query
 __END__
 
 
 __NAME__ description
-
-This filter uses DBI's quote method (or the DBD's, if it overrides)
-to make a string safe to use in SQL. It takes into account any
-database-specific quoting needs, such as <literal>\</literal> for
-PostgreSQL or MySQL, truncating at the first ASCII NUL for PostgreSQL,
-turning a newline into a literal two-character <literal>\n</literal> for
-MySQL, etc.
-
-The default database handle is used (the first ProductFiles database),
-unless another is specified. (See the example.)
-
-
-
-Note the containing quotes, which is different than Interchange's native
-"sql" filter. See also the DBI man page details about the quote method.
-
-Since this uses database handles, Safe must be considered if it's being
-used via the $Tag object in a Perl block.
+This filter uses the &PERL; DBI quoting method (or actually the DBD, if
+it redefines it) to make strings safe for use in &glos-SQL; commands.
+</para><para>
+All database-specific needs are honored, including (but not limited
+to) <literal>\</literal> &glos-escape;s for &PGSQL; or &MYSQL;,
+truncating at the first ASCII NUL for &PGSQL;, and turning a newline into a
+literal two-character <literal>\n</literal> for &MYSQL;.
+</para><para>
+The default database handle is used (the first &conf-ProductFiles; database),
+unless a different one is specified.
 __END__
 
 
 __NAME__ notes
+DBI quoting is different from &IC;'s native &filter-sql; filter.
+See the DBI man page details about the DBI quoting method.
+</para><para>
+Since the filter uses database handles, &glos-safe; must be considered if
+it is being used via the <varname>$Tag</varname> object in a &PERL; block.
+</para><para>
 For more information see
 <citerefentry><refentrytitle>DBI</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 and the DBD documentation for your database.
 __END__
 
 
-_NAME__ online: Filter example
-To use the filter to safely quote the example CGI variable "code",
-with the value "that's all":
-
-<programlisting>
-    [cgi name=code filter=dbi_quote keep=1]
-</programlisting>
-
-If the default products database is a typical SQL database, that returns:
-
-<literal>'that''s all'</literal>
-
-To quote a literal string, specifying the desired database handle's quote method:
+_NAME__ example: Filter example
+<programlisting><![CDATA[
+[cgi name=code set="That's all" hide=1]
+
+[cgi name=code filter=dbi_quote keep=1]
+]]></programlisting>
+
+If the default &conf-ProductFiles; database is a typical &glos-SQL; database,
+the filter would return <literal>'that''s all'</literal>, including all the 
+quotes.
+__END__
 
+__NAME__ example: Quoting a literal string, specifying DBI quote method
 <programlisting>
-    [filter dbi_quote.inventory]some string \ or other[/filter]
+[filter dbi_quote.DATABASE_NAME]some string \ or other[/filter]
 </programlisting>
 
-If "inventory" is a MySQL database, this returns:
-
-<literal>'some string \\ or other'</literal>
-
-Whereas if it were an Oracle database, it would return:
-
-<literal>'some string \ or other'</literal>
-_END__
+The above would produce <literal>'some string \\ or other'</literal>
+for &MYSQL; or &PGSQL;, and
+<literal>'some string \ or other'</literal> for &ORACLE;.
+__END__
 



1.3       +1 -1      xmldocs/refs/debug.tag


rev 1.3, prev_rev 1.2
Index: debug.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/debug.tag,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- debug.tag	14 Sep 2005 23:10:30 -0000	1.2
+++ debug.tag	20 Oct 2005 14:09:50 -0000	1.3
@@ -18,7 +18,7 @@
 __END__
 
 __NAME__ description
-The tags sends a message to &IC; debug log.
+The tag sends a message to &IC; debug log.
 __END__
 
 



1.2       +1 -1      xmldocs/refs/discount


rev 1.2, prev_rev 1.1
Index: discount
===================================================================
RCS file: /var/cvs/xmldocs/refs/discount,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- discount	2 Feb 2005 11:35:59 -0000	1.1
+++ discount	20 Oct 2005 14:09:50 -0000	1.2
@@ -99,7 +99,7 @@
 
 __NAME__ example: Displaying the discount ammount received
 If you want to display the discount amount to the user, simply use the
-&glos-item-discount; tag:
+&tag-item-discount; tag:
 <!-- TODO move this to refpage for item-discount -->
 
 <programlisting>



1.2       +10 -5     xmldocs/refs/filter_sql_no_backslash


rev 1.2, prev_rev 1.1
Index: filter_sql_no_backslash
===================================================================
RCS file: /var/cvs/xmldocs/refs/filter_sql_no_backslash,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- filter_sql_no_backslash	4 Oct 2005 19:59:43 -0000	1.1
+++ filter_sql_no_backslash	20 Oct 2005 14:09:50 -0000	1.2
@@ -17,15 +17,20 @@
 
 
 __NAME__ description
-This &glos-pragma; disables default doubling of backslashes by the "sql" filter.
-You may want to set this pragma if using a database other than PostgreSQL and MySQL.
-(SQL standard strings do not treat <literal>\</literal> specially, so it normally
-doesn't need to be escaped.)
+This &glos-pragma; disables default backslash &glos-escape;s performed by
+the &filter-sql; filter.
+</para><para>
+For databases like &MYSQL; or &PGSQL; which treat <literal>\</literal> in 
+a special way, the default behavior of escaping backslashes is the right choice.
+</para><para>
+The &glos-SQL; standard, however, does not treat <literal>\</literal>
+specially, so you would want to enable this &glos-pragma; (effectively
+disabling escaping) for conforming databases, such as &ORACLE;.
 __END__
 
 
 __NAME__ example: Enable filter_sql_no_backslash pragma catalog-wide
-Put the following in catalog.cfg:
+Put the following in &ccf;:
 <programlisting>
 Pragma filter_sql_no_backslash
 </programlisting>



1.2       +6 -0      xmldocs/refs/name.filter


rev 1.2, prev_rev 1.1
Index: name.filter
===================================================================
RCS file: /var/cvs/xmldocs/refs/name.filter,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- name.filter	29 May 2005 11:19:33 -0000	1.1
+++ name.filter	20 Oct 2005 14:09:50 -0000	1.2
@@ -19,3 +19,9 @@
 </programlisting>
 __END__
 
+__NAME__ online: Filter example for name and namecase correction
+<programlisting>
+[filter op="name namecase"]OCELIC, Davor[/filter]
+</programlisting>
+__END__
+



1.3       +9 -5      xmldocs/refs/sql.filter


rev 1.3, prev_rev 1.2
Index: sql.filter
===================================================================
RCS file: /var/cvs/xmldocs/refs/sql.filter,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- sql.filter	4 Oct 2005 19:59:43 -0000	1.2
+++ sql.filter	20 Oct 2005 14:09:50 -0000	1.3
@@ -1,21 +1,25 @@
 __NAME__ purpose
-quote strings for use in SQL statements, without reference to a specific database
+quote strings for use in SQL statements, without referencing a specific database
 __END__
 
 __NAME__ see also
+dbi_quote
 __END__
 
 
 __NAME__ description
 The filter replaces single quotes (<literal>'</literal>) with 
-"double" single quotes (<literal>''</literal>). By default it will also
-replace a backslash (<literal>\</literal>) with two backslashes
-(<literal>\\</literal>) (as is needed to escape PostgreSQL and MySQL
-strings) but that can be disabled by setting the filter_sql_no_backslash pragma.
+two single quotes (<literal>''</literal>). In addition, it
+replaces each backslash (<literal>\</literal>) with two backslashes
+(<literal>\\</literal>) to properly &glos-escape; all content, but
+backslash escaping can be turned off by setting the
+&pragma-filter_sql_no_backslash; pragma.
 __END__
 
 
 __NAME__ notes
+The filter is intended to be used on &glos-SQL; strings.
+</para><para>
 For more information on &PERL; Regular Expressions, pattern matching and
 character classes, see
 <citerefentry><refentrytitle>perlre</refentrytitle><manvolnum>1</manvolnum></citerefentry>.



1.3       +1 -1      xmldocs/refs/version.tag


rev 1.3, prev_rev 1.2
Index: version.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/version.tag,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- version.tag	14 Sep 2005 23:10:30 -0000	1.2
+++ version.tag	20 Oct 2005 14:09:50 -0000	1.3
@@ -153,7 +153,7 @@
 	<!-- DFL -->
 	</entry>
 	<entry>
-	Test for availability of the specified &glos-PERL; module.
+	Test for availability of the specified &PERL; module.
 	</entry>
 
 </row> 



1.3       +1 -1      xmldocs/refs/xfer-catalog.tag


rev 1.3, prev_rev 1.2
Index: xfer-catalog.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/xfer-catalog.tag,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- xfer-catalog.tag	14 Sep 2005 23:10:30 -0000	1.2
+++ xfer-catalog.tag	20 Oct 2005 14:09:50 -0000	1.3
@@ -191,7 +191,7 @@
 		Exporting non-&MYSQL; and non-&PGSQL; databases to text files
 	</para></listitem>
 	<listitem><para>
-		Dumping MySQL and PostgreSQL &glos-databases; with their native tools
+		Dumping MySQL and PostgreSQL &glos-database;s with their native tools
 		(usually <command>mysqldump</command> and <command>pg_dump</command>
 	</para></listitem>
 	<listitem><para>



1.1                  xmldocs/refs/comment.tag


rev 1.1, prev_rev 1.0
Index: comment.tag
===================================================================
__NAME__ purpose
comment parts of code or HTML pages
__END__

__NAME__ see also
debug
__END__

__NAME__ synopsis
__END__

__NAME__ description
The tag comments parts of &glos-ITL; or &glos-HTML; code.
Content enclosed in the &tag-comment; block will not be processed
in any way, and will be stripped out of the pages.
</para><para>
You can use comment sections to provide code commentary, or
effectively disable parts of code.
</para><para>
Interchange's &tag-comment; tag is often preferred over &glos-HTML;
comments (<code>&lt;!--<replaceable>...</replaceable>--&gt;</code> blocks),
because unlike &tag-comment; blocks, HTML comments do get
passed through to the clients.
__END__


__NAME__ notes
&tag-comment; blocks can be nested.
__END__

__NAME__ example: Sending a message to debug log
<programlisting>
[comment]
  Have no fear, for this is the one comment area!
[/comment]
</programlisting>
__END__









More information about the docs mailing list