[interchange-docs] xmldocs - docelic modified 16 files

docs at icdevgroup.org docs at icdevgroup.org
Thu Sep 28 12:34:56 EDT 2006


User:      docelic
Date:      2006-09-28 16:34:56 GMT
Modified:  .        TODO
Modified:  bin      refs-autogen
Modified:  glossary ITL SDBM attribute discount rotated-banner tax
Modified:           variable
Modified:  guides   programming-style.xml search.xml
Modified:  howtos   override-admin-UI-page
Modified:  refs     DatabaseAuto UserTag counter.tag dump.tag
Log:
- TODO: remove some resolved tasks
- bin/refs-autogen: resolve some of linking errors (will result in less
  errors in build phase)
- glossary/*: updated entries, bits and pieces here and there
- guides/search.xml: started documenting mv_ variables
- refs/DatabaseAuto: fixed small error, thanks Peter Ajamian @pajamian.dhs.org
- refs/counter.tag: fixed description error, thanks Rob Aldred @webmaint.net

Revision  Changes    Path
1.96      +3 -6      xmldocs/TODO


rev 1.96, prev_rev 1.95
Index: TODO
===================================================================
RCS file: /var/cvs/xmldocs/TODO,v
retrieving revision 1.95
retrieving revision 1.96
diff -u -r1.95 -r1.96
--- TODO	3 Sep 2006 10:53:50 -0000	1.95
+++ TODO	28 Sep 2006 16:34:55 -0000	1.96
@@ -8,6 +8,9 @@
 - In tags, make XSLT code print position number besides "Yes" word in 
   positional parameters for tags
 - add search box to guides/index.xml
+- make See Also only go two or three levels recursively. Currently we do it
+  until the "chain" ends, which results in having many unrelated options
+  listed under See Also.
 
 Outstanding:
 =======
@@ -15,19 +18,13 @@
 - See that if 'crypt' is put in see also, all symbols of that name appear
   in see also line and their type is distinguished visually.
 - TAXAREA is not discovered in source by bin/stattree
-- toc in glossary
 - Make MapRoutined source contexts have Line: x-y instead of Lines: z header.
-- make glossary,howto items also appear as symbols, so that you can put
-  their names in See Also and get generated links
 - recognize situations where contexts overlap, but in a special way that
   first example does not see the other, but the other sees the first becase
   of 10 lines of pre-context. (example is IMAGE_MOGRIFY refentry). In those
   cases, resize area of the context report so that it appears as one
 - With confs, also include source context where it is being used
-- Enhance stuff with acronyms
-- Under AUTHORS, include cvs line where appropriate (guides, howtos, gloss... )
 - In vars.html, include line if it appears in variable.txt
-- why email, email-raw, SendMailProgram produce errors about usertags olink ID
 - match style (no starting verb or all starting verbs) in all Example titles
 - check if all Default fields are properly formated (<literal> or none)
 - make regexp matching better, to properly scan parse_subroutine(); (gets



1.113     +5 -2      xmldocs/bin/refs-autogen


rev 1.113, prev_rev 1.112
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.112
retrieving revision 1.113
diff -u -r1.112 -r1.113
--- refs-autogen	12 Aug 2006 22:43:11 -0000	1.112
+++ refs-autogen	28 Sep 2006 16:34:55 -0000	1.113
@@ -641,7 +641,8 @@
 	my @see_items = @{ $ag{'_see also'} };
 
 	for my $itm ( @see_items ) {
-		next if $itm =~ /^</; # Don't touch if it's a manually written XML link
+		next if $itm =~ /^[<&]/; # Don't touch if it's a manually written XML link
+                              # or a link to a symbol
 		my $linktype = "link"; # Assume link to symbol of same type
 		my $linkarg = "linkend";
 		if ( $autogenerated{$group}{$itm} ) {
@@ -661,8 +662,10 @@
 					} else {
 						# Documents won't end up in the same file even with $compounds
 						# enabled.
+						my $linkdoc = $compounds ?
+							( $compounds{ substr($sect, -3, 3) } || $sect ) : $sect;
 						$linktype = "olink";
-						$linkarg = "targetdoc='${sect}s' targetptr";
+						$linkarg = "targetdoc='${linkdoc}s' targetptr";
 					}
 
 				}



1.19      +2 -1      xmldocs/glossary/ITL


rev 1.19, prev_rev 1.18
Index: ITL
===================================================================
RCS file: /var/cvs/xmldocs/glossary/ITL,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -r1.18 -r1.19
--- ITL	27 Jul 2006 20:48:15 -0000	1.18
+++ ITL	28 Sep 2006 16:34:55 -0000	1.19
@@ -6,7 +6,8 @@
 These ITL tags perform various display and modification operations for
 the user session. There's more than 200 standard predefined tags, and the
 &conf-UserTag; facility allows you to create custom tags that perform your own
-functions and can be just as powerful as the built-in tags.
+functions and can be just as powerful as the built-in tags. To get started
+with custom tags, see &glos-usertag; glossary entry.
 </para>
 
 <section>



1.2       +4 -1      xmldocs/glossary/SDBM


rev 1.2, prev_rev 1.1
Index: SDBM
===================================================================
RCS file: /var/cvs/xmldocs/glossary/SDBM,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- SDBM	4 Jul 2006 22:24:42 -0000	1.1
+++ SDBM	28 Sep 2006 16:34:55 -0000	1.2
@@ -1,4 +1,7 @@
-SDBM is an of in-file, non-&glos-SQL; database (similar to GDBM).
+SDBM is an in-file, non-&glos-SQL; database (similar to GDBM). Interchange will,
+however, add an SQL layer on top of every supported non-SQL database
+so SQL calls <emphasis role='bold'>can</emphasis> be used, as long as they are
+made through &IC;.
 </para><para>
 &IC; must work with some kind of a database. When no SQL database is 
 specified, database source files (text) are still stored in a database,



1.4       +25 -7     xmldocs/glossary/attribute


rev 1.4, prev_rev 1.3
Index: attribute
===================================================================
RCS file: /var/cvs/xmldocs/glossary/attribute,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- attribute	9 Aug 2005 00:00:17 -0000	1.3
+++ attribute	28 Sep 2006 16:34:55 -0000	1.4
@@ -1,9 +1,11 @@
 
-Attributes are various "sub-features" of a product. If you are selling
-t-shirts in different colors and sizes, you are an ideal candidate for
-item attributes.
-&IC; allows item <emphasis>attributes</emphasis> (also called
-<emphasis>modifiers</emphasis> or <emphasis>options</emphasis>)
+Attributes (sometimes also called
+<emphasis>modifiers</emphasis>, <emphasis>options</emphasis> or
+<emphasis>params</emphasis>)
+are various "sub-features" of a product. If you are selling
+t-shirts in different colors and sizes, color and size are ideal candidates
+for item attributes.
+&IC; allows attributes
 to be set for each ordered item. This allows a varying size, color, or
 any other modifier to be attached to an otherwise common part number.
 </para>
@@ -20,7 +22,8 @@
 
 
 <para>
-Besides setting modifier names in the config files, you can also set them as
+Besides setting modifier names in the config files (via the above
+&conf-UseModifier;), you can also set them as
 &glos-scratch; variables with <mv>mv_UseModifier</mv>. For example,
 the above modifiers would be set with
 <code>[set mv_UseModifier]size color[/set]</code>.
@@ -28,7 +31,22 @@
 or even same product &glos-SKU;s. Those specified in <mv>mv_UseModifier</mv> at
 the time of order will be used (just be careful, because you cannot set it
 more than once on the same page).
+</para>
+
+<note><para>
+When choosing modifier names, do not use anything that begins with
+<literal>mv_</literal> nor words like <literal>code</literal>,
+<literal>quantity</literal> or <literal>group</literal>; those variables
+have already been used up by &IC; itself.
 </para><para>
+You also need to make sure that no fields in your &glos-HTML;
+forms have digits appended to their names, if their non-digit name part
+is equal to any used attribute. (This is because &IC; treats 
+say, <literal>size0</literal> and <literal>size1</literal> as multiple
+<literal>size</literal> modifier values.)
+</para></note>
+
+<para>
 In addition, setting &conf-SeparateItems; or <mv>mv_separate_items</mv>
 places each ordered item on a separate line even if they have the same
 &glos-SKU;, simplifying attribute handling.
@@ -67,7 +85,7 @@
 
 <para>
 It could just as easily be done with a radio button group as well
-(when you combine them with the &lt;checked&gt; &glos-HTML; tag.
+(when you combine them with the &lt;checked&gt; &glos-HTML; tag).
 </para><para>
 In addition, &IC; would automatically generate the above select box
 if you called <code>[accessories <replaceable>code</replaceable> size]</code>



1.4       +4 -3      xmldocs/glossary/discount


rev 1.4, prev_rev 1.3
Index: discount
===================================================================
RCS file: /var/cvs/xmldocs/glossary/discount,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- discount	15 Jun 2006 22:35:42 -0000	1.3
+++ discount	28 Sep 2006 16:34:55 -0000	1.4
@@ -3,7 +3,8 @@
 apply only to the customer receiving them, so you can gate the          
 discounts based on membership in a club or other arbitrary means.
 </para><para>
-Discounts are are of the following types:
+Discounts are defined using the &tag-discount; tag, 
+and are of the following types:
 
 <itemizedlist>
 
@@ -21,8 +22,8 @@
 	attribute is set (usually with embedded &PERL;)
 	</para></listitem>
 	<listitem><para>
-	Order discount - a discount applied not on individual products, but on a
-	total order.
+	Order discount - a discount applied not to individual products, but to the
+	total order amount.
 	Key to use with the &tag-discount; tag is <literal>ENTIRE_ORDER</literal>
 	</para></listitem>
 



1.5       +3 -0      xmldocs/glossary/rotated-banner


rev 1.5, prev_rev 1.4
Index: rotated-banner
===================================================================
RCS file: /var/cvs/xmldocs/glossary/rotated-banner,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- rotated-banner	15 Dec 2004 14:24:00 -0000	1.4
+++ rotated-banner	28 Sep 2006 16:34:55 -0000	1.5
@@ -7,3 +7,6 @@
 </para><para>
 The available banners are displayed <emphasis>in sequential order</emphasis>,
 with an independent pointer for each client.
+</para><para>
+See the &tag-banner; tag and &howto-implement-banners; for further
+discussion and examples.



1.6       +11 -7     xmldocs/glossary/tax


rev 1.6, prev_rev 1.5
Index: tax
===================================================================
RCS file: /var/cvs/xmldocs/glossary/tax,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- tax	19 Nov 2005 22:37:41 -0000	1.5
+++ tax	28 Sep 2006 16:34:55 -0000	1.6
@@ -9,23 +9,27 @@
 <section>
 	<title>Simple "salestax.asc" Method</title>
 <para>
-In this simple taxing method, &conf-SalesTax; directive is
-set to form fields whose values will be used as keys to look up
-the tax rate in <filename>CATROOT/products/salestax.asc</filename>.
-</para>
-<para>
 Sales tax calculation in this simple scheme is performed on a straight
 percentage basis,
 with certain items allowed to be tax-exempt. Simply initialize the
 &conf-SalesTax; directive to the name of lookup fields. Those lookup fields
 are the ones that are available on the final order form and indicate
-geographical locality. Usually, the fields are zip and state codes:
+geographical locality.
+</para><para>
+&conf-SalesTax; configuration directive is
+set to form fields whose values will be used as keys to look up
+the tax rate in <filename>products/salestax.asc</filename>, based on localities.
+<database>salestax</database> is a fixed-format database, and consists
+of identifiers that match localities defined using &conf-SalesTax;.
+</para><para>
+Locality names are always forced to UPPER CASE, and 
+are usually identified by zip or state codes:
 
 <programlisting><![CDATA[
 SalesTax    zip,state
 ]]></programlisting>
 
-Each line of the mentioned <filename>CATROOT/products/salestax.asc</filename>
+Each line of the mentioned <filename>products/salestax.asc</filename>
 file should contain a code (again, usually 5-digit zip or 2-letter state
 ID), followed by a TAB character and a desired percentage.
 



1.3       +3 -0      xmldocs/glossary/variable


rev 1.3, prev_rev 1.2
Index: variable
===================================================================
RCS file: /var/cvs/xmldocs/glossary/variable,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- variable	20 Jun 2006 22:53:42 -0000	1.2
+++ variable	28 Sep 2006 16:34:55 -0000	1.3
@@ -30,6 +30,9 @@
 <listitem><para>
 &glos-value; variables
 </para></listitem>
+<listitem><para>
+&PERL; variables
+</para></listitem>
 </itemizedlist>
 
 Read the respective glossary entries.



1.8       +31 -4     xmldocs/guides/programming-style.xml


rev 1.8, prev_rev 1.7
Index: programming-style.xml
===================================================================
RCS file: /var/cvs/xmldocs/guides/programming-style.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- programming-style.xml	5 Feb 2006 13:17:15 -0000	1.7
+++ programming-style.xml	28 Sep 2006 16:34:56 -0000	1.8
@@ -194,8 +194,8 @@
 		<varname>$Vend::Xtrailer</varname>.
 <programlisting><![CDATA[
 <form action="[process]">
-  <input type="text"   name="city" value="[value city]" >
-  <input type="submit"             value=" Submit "     >
+  <input type="text"   name="city" value="[value city]" />
+  <input type="submit"             value=" Submit "     />
 </form>
 ]]></programlisting>
 	</para></listitem>
@@ -212,13 +212,36 @@
 </sect1>
 
 
+<sect1 id="Usertags">
+	<title>Writing usertags</title>
+	<para>
+	See &glos-usertag; and &glos-ITL; glossary entries and the
+	&conf-UserTag; configuration directive for technical information.
+	</para><para>
+	If you use <literal>addAttr</literal> option, then name the
+	hash-receiving variable "<literal>$opt</literal>":
+<programlisting><![CDATA[
+UserTag test Order one two three
+UserTag test addAttr
+UserTag test Routine <<EOR
+sub {
+	my ($one, $two, $three, $opt) = @_;
+
+	....
+}
+EOR
+]]></programlisting>
+	</para>
+</sect1>
+
+
 <sect1 id='XMLDOCS'>
 	<title>XMLDOCS notes</title>
 
 	<para>
 	As you might know, XMLDOCS documentation system contains 
 	<filename>bin/stattree</filename> script which parses complete &IC;
-	source tree. Although I really tried to make it recognize code regardless
+	source tree. Even though it really tries to recognize code regardless
 	of formatting (much like &PERL; interpreter does), there are still some
 	little suggestions on the programming style to make it easier for XMLDOCS.
 	</para>
@@ -238,6 +261,8 @@
 		Do not break word <literal>sub</literal> and subroutine name to separate
 		lines.
 		<code>sub test....</code> is OK, <code>sub \n test</code> is NOT.
+		It's best to use the cleanest variant that matches regular expression
+		<code>^sub \w+ {$</code>.
 		(Impact: might confuse function tracking code)
 <programlisting><![CDATA[
 sub test1 {
@@ -278,6 +303,8 @@
 	</itemizedlist>
 </sect1>
 
-
 </article>
 
+
+
+<!-- TODO add note that in usertags addAttr goes to $opt -->



1.15      +546 -86   xmldocs/guides/search.xml


rev 1.15, prev_rev 1.14
Index: search.xml
===================================================================
RCS file: /var/cvs/xmldocs/guides/search.xml,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- search.xml	15 Aug 2006 08:38:53 -0000	1.14
+++ search.xml	28 Sep 2006 16:34:56 -0000	1.15
@@ -111,7 +111,7 @@
 <programlisting>
 Swish date_format "%d %b %Y"
 </programlisting>
-See &glos-time; for possible format strings.
+See &glos-time; glossary entry for supported format strings.
 </para>
 <section>
 <title>Search Examples</title>
@@ -152,157 +152,617 @@
 </section>
 
 
-<section>
+<section id='search_reference'>
 	<title>Search Reference</title>
 
 	<itemizedlist>
-		<listitem><para>mv_all_chars</para>
-		</listitem>
-		<listitem><para>mv_base_directory</para>
-		</listitem>
-		<listitem><para>mv_begin_string</para>
-		</listitem>
-		<listitem><para>mv_cache_key</para>
-		</listitem>
-		<listitem><para>mv_coordinate</para>
-		</listitem>
-		<listitem><para>mv_case</para>
-		</listitem>
-		<listitem><para>mv_verbatim_columns</para>
-		</listitem>
-		<listitem><para>mv_dict_end</para>
-		</listitem>
-		<listitem><para>mv_dict_fold</para>
-		</listitem>
-		<listitem><para>mv_dict_limit</para>
-		</listitem>
-		<listitem><para>mv_dict_look</para>
+		<listitem><para>
+		<literal>mv_all_chars</literal>
+		(ac, <literal>0</literal>/<literal>1</literal>,
+		default <literal>1</literal>) &mdash;
+		escape non-alphanumeric characters in search specification.
+		</para>
+		</listitem>
+		<listitem><para>
+		<literal>mv_base_directory</literal>
+		(bd, <replaceable>directory_name</replaceable>,
+		default Interchange installation directory) &mdash;
+		base directory in which to look up text files to search
+		(related option <literal>fi</literal>).
+		</para>
+		</listitem>
+		<listitem><para>
+		<literal>mv_begin_string</literal>
+		(bs, <replaceable>regular_expression</replaceable>,
+		default none) &mdash;
+		&glos-regexp; that the beginning of the searched field value must match.
+		</para>
+		</listitem>
+		<listitem><para>
+		<literal>mv_cache_key</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_raw_dict_look</para>
+		<listitem><para>
+		<literal>mv_coordinate</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_dict_order</para>
+		<listitem><para>
+		<literal>mv_case</literal>
+		(cs, <literal>0</literal>/<literal>1</literal>,
+		default <literal>0</literal>) &mdash;
+		case sensitive search.
+		</para>
+		</listitem>
+		<listitem><para>
+		<literal>mv_verbatim_columns</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_record_delim</para>
+		<listitem><para>
+		<literal>mv_dict_end</literal>
+		(de, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_exact_match</para>
+		<listitem><para>
+		<literal>mv_dict_fold</literal>
+		(df, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_spelling_errors</para>
+		<listitem><para>
+		<literal>mv_dict_limit</literal>
+		(di, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_field_file</para>
+		<listitem><para>
+		<literal>mv_dict_look</literal>
+		(dl, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_search_file</para>
+		<listitem><para>
+		<literal>mv_raw_dict_look</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_field_title</para>
+		<listitem><para>
+		<literal>mv_dict_order</literal>
+		(do, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_first_match</para>
+		<listitem><para>
+		<literal>mv_record_delim</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_field_names</para>
+		<listitem><para>
+		<literal>mv_exact_match</literal>
+		(em, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_head_skip</para>
+		<listitem><para>
+		<literal>mv_spelling_errors</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_index_delim</para>
+		<listitem><para>
+		<literal>mv_field_file</literal>
+		(ff, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_search_label</para>
+		<listitem><para>
+		<literal>mv_search_file</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_like_field</para>
+		<listitem><para>
+		<literal>mv_field_title</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_list_only</para>
+		<listitem><para>
+		<literal>mv_first_match</literal>
+		(fm, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_search_line_return</para>
+		<listitem><para>
+		<literal>mv_field_names</literal>
+		(fn, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_like_spec</para>
+		<listitem><para>
+		<literal>mv_head_skip</literal>
+		(hs, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_more_alpha</para>
+		<listitem><para>
+		<literal>mv_index_delim</literal>
+		(id, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_more_alpha_chars</para>
+		<listitem><para>
+		<literal>mv_search_label</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_more_decade</para>
+		<listitem><para>
+		<literal>mv_like_field</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_more_id</para>
+		<listitem><para>
+		<literal>mv_list_only</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_matchlimit</para>
+		<listitem><para>
+		<literal>mv_search_line_return</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_max_matches</para>
+		<listitem><para>
+		<literal>mv_like_spec</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_more_matches</para>
+		<listitem><para>
+		<literal>mv_more_alpha</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_profile</para>
+		<listitem><para>
+		<literal>mv_more_alpha_chars</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_min_string</para>
+		<listitem><para>
+		<literal>mv_more_decade</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_negate</para>
+		<listitem><para>
+		<literal>mv_more_id</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_negate</para>
+		<listitem><para>
+		<literal>mv_matchlimit</literal>
+		(ml, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_no_hide</para>
+		<listitem><para>
+		<literal>mv_max_matches</literal>
+		(mm, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_no_more</para>
+		<listitem><para>
+		<literal>mv_more_matches</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_nextpage</para>
+		<listitem><para>
+		<literal>mv_profile</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_next_search</para>
+		<listitem><para>
+		<literal>mv_min_string</literal>
+		(ms, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_numeric</para>
+		<listitem><para>
+		<literal>mv_negate</literal>
+		(ne, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_column_op</para>
+		<listitem><para>
+		<literal>mv_negate</literal>
+		(ng, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_orsearch</para>
+		<listitem><para>
+		<literal>mv_no_hide</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>prefix</para>
+		<listitem><para>
+		<literal>mv_no_more</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_more_permanent</para>
+		<listitem><para>
+		<literal>mv_nextpage</literal>
+		(np, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_return_all</para>
+		<listitem><para>
+		<literal>mv_next_search</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_return_delim</para>
+		<listitem><para>
+		<literal>mv_numeric</literal>
+		(nu, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_search_reference</para>
+		<listitem><para>
+		<literal>mv_column_op</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_return_fields</para>
+		<listitem><para>
+		<literal>mv_orsearch</literal>
+		(os, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_range_alpha</para>
+		<listitem><para>
+		<literal>mv_more_permanent</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_range_look</para>
+		<listitem><para>
+		<literal>mv_return_all</literal>
+		(ra, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_range_min</para>
+		<listitem><para>
+		<literal>mv_return_delim</literal>
+		(dr, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_return_file_name</para>
+		<listitem><para>
+		<literal>mv_search_reference</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_return_reference</para>
+		<listitem><para>
+		<literal>mv_return_fields</literal>
+		(rf, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_return_spec</para>
+		<listitem><para>
+		<literal>mv_range_alpha</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_range_max</para>
+		<listitem><para>
+		<literal>mv_range_look</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_small_data</para>
+		<listitem><para>
+		<literal>mv_range_min</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_searchspec</para>
+		<listitem><para>
+		<literal>mv_return_file_name</literal>
+		(rn, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_search_field</para>
+		<listitem><para>
+		<literal>mv_return_reference</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_search_group</para>
+		<listitem><para>
+		<literal>mv_return_spec</literal>
+		(rs, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_search_immediate</para>
+		<listitem><para>
+		<literal>mv_range_max</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_start_match</para>
+		<listitem><para>
+		<literal>mv_small_data</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_search_page</para>
+		<listitem><para>
+		<literal>mv_searchspec</literal>
+		(se, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_sql_query</para>
+		<listitem><para>
+		<literal>mv_search_field</literal>
+		(sf, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_search_relate</para>
+		<listitem><para>
+		<literal>mv_search_group</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_searchtype</para>
+		<listitem><para>
+		<literal>mv_search_immediate</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_substring_match</para>
+		<listitem><para>
+		<literal>mv_start_match</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_sort_field</para>
+		<listitem><para>
+		<literal>mv_search_page</literal>
+		(sp, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_sort_option</para>
+		<listitem><para>
+		<literal>mv_sql_query</literal>
+		(sq, <replaceable>SQL_Query</replaceable>,
+		default none) &mdash;
+		for text-based searches (<literal>st=text</literal> only), this option
+		specifies the SQL query to run over the lines in the file.
+		This is not the same as an external &glos-SQL; database search.
+		</para><para>
+		Furthermore, the <replaceable>SQL_Query</replaceable> undergoes a 
+		little modification before it is used. Here's a practical
+		example:
+<programlisting><![CDATA[
+Artist: <input name="artist" />
+Title:  <input name="title"  />
+<input type="hidden" name="mv_sql_query" value="
+  SELECT  code FROM products
+  WHERE artist LIKE artist
+  AND    title LIKE title
+" />
+]]></programlisting>
+</para>
+<para>
+If the right-hand side of every part of expression is an alphanumeric,
+unquoted word, then it is replaced with the 
+appropriate form variable value. (Or if it's a one-click search, &glos-scratch;
+variables are used instead). Quoted right-hand side values are taken literally.
+<!-- it reads from value or cgi space? -->
+</para><para>
+If the left-hand side of every part of expression is a quoted word, the behavior
+is reversed.  That part is replaced with the appropriate form variable value.
+(Or if it's a one-click search, &glos-scratch; variables are used instead).
+Unquoted left-hand side values are taken literally.
+</para>
+<para>
+Here's an example that allows users to select
+whether they want to search in <database class='field'>title</database>
+or <database class='field'>artist</database> fields:
+<programlisting><![CDATA[
+Search for: <input name="searchstring" /><br />
+Search in   <input type="radio" name="column" value="title"  /> title
+            <input type="radio" name="column" value="artist" /> artist
+
+<input type=hidden name="mv_sql_query" value="
+  SELECT code    FROM products
+  WHERE 'column' LIKE searchstring
+" />
+]]></programlisting>
+Just for a reference, here's what the two above examples
+would look like when coded "manually":
+<programlisting><![CDATA[
+[page search="
+  co=yes
+  sf=artist
+  op=rm
+  se=[value artist]
+  sf=title
+  op=rm
+  se=[value title]
+"]
+Search for [value artist], [value title]
+</a>
+
+
+[page search="
+  co=yes
+  sf=[value column]
+  op=rm
+  se=[value searchstring]
+"]
+Search for [value searchstring] in [value column]
+</a>
+]]></programlisting>
+		</para>
+		</listitem>
+		<listitem><para>
+		<literal>mv_search_relate</literal>
+		(, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_unique</para>
+		<listitem><para>
+		<literal>mv_searchtype</literal>
+		(st, [ <literal>glimpse</literal> | <literal>db</literal> |
+		<literal>sql</literal> | <literal>text</literal> | 
+		<literal>ref</literal> ],
+		<!-- is default none or glimpse? Looking at Scan.pm, there's no default -->
+		default none) &mdash;
+		select search type. <literal>glimpse</literal> uses the Glimpse search
+		engine (see &conf-Glimpse;), <literal>db</literal> (or the
+		equivalent <literal>sql</literal>) iterate over every row in the
+		&glos-SQL; database, <literal>text</literal> searches
+		corresponding &glos-database; text source files, and 
+		<literal>ref</literal> iterates over the results from some
+		previous, already-performed search (related option <literal>lb</literal>).
+		</para>
+		</listitem>
+		<listitem><para>
+		<literal>mv_substring_match</literal>
+		(su, <literal>0</literal>/<literal>1</literal>,
+		default <literal>0</literal>) &mdash;
+		match on substrings as well as whole words. This is typically set in
+		dictionary-based searches.
+		</para>
+		</listitem>
+		<listitem><para>
+		<literal>mv_sort_field</literal>
+		(tf, <replaceable>field_name_or_index [,field_name2_or_index2...]</replaceable>, 
+		default none) &mdash;
+		determine sort order of the returned data. It is possible to refer
+		to columns by both using their names (if the search is such that column
+		names are known) and their indices, starting from <literal>0</literal>.
+		</para>
+		</listitem>
+		<listitem><para>
+		<literal>mv_sort_option</literal>
+		(to, <literal></literal>/<literal></literal>,
+		default <literal></literal>) &mdash;
+
+		</para>
 		</listitem>
-		<listitem><para>mv_value</para>
+		<listitem><para>
+		<literal>mv_unique</literal>
+		(un, <literal>0</literal>/<literal>1</literal>,
+		default <literal>0</literal>) &mdash;
+		return only unique fields. The option works on whatever the search
+		return fields (set with <literal>rf</literal>) are.
+		<!-- TODO returns only unique items, or compressed duplicates into one?
+		Also, does it looks for uniques in one field, or an entry is consudered
+		duplicate only if all fields are the same? -->
+		</para>
+		</listitem>
+		<listitem><para>
+		<literal>mv_value</literal>
+		(va, <replaceable>value_variable_name</replaceable>=<replaceable>value</replaceable>,
+		default none) &mdash;
+		assign <replaceable>value</replaceable> to a &glos-value; variable. This
+		is exactly what happens with normal variables in search &glos-profile;s
+		when you use the <code><replaceable>variable_name</replaceable>=<replaceable>value</replaceable></code> syntax,
+		so you should use this option only where variables cannot be set
+		directly (i.e. in one-click searches):
+<programlisting>
+[page
+  href=scan
+  arg="se=Renaissance
+       se=Impressionists
+       va=category_name=Renaissance and Impressionist Paintings
+       os=yes"
+]Renaissance and Impressionist Paintings&lt;a&gt;
+</programlisting>
+		</para>
 		</listitem>
 	</itemizedlist>
 </section>



1.3       +1 -1      xmldocs/howtos/override-admin-UI-page


rev 1.3, prev_rev 1.2
Index: override-admin-UI-page
===================================================================
RCS file: /var/cvs/xmldocs/howtos/override-admin-UI-page,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- override-admin-UI-page	3 Sep 2006 10:03:24 -0000	1.2
+++ override-admin-UI-page	28 Sep 2006 16:34:56 -0000	1.3
@@ -5,5 +5,5 @@
 into the <filename class='directory'>pages/admin/</filename> directory
 under your catalog tree, to make custom versions that override the distribution
 ones.
-You only need copy the pages you want to override; the rest are automatically
+You only need to copy the pages you want to override; the rest are automatically
 picked up from the usual, default location.



1.8       +2 -2      xmldocs/refs/DatabaseAuto


rev 1.8, prev_rev 1.7
Index: DatabaseAuto
===================================================================
RCS file: /var/cvs/xmldocs/refs/DatabaseAuto,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- DatabaseAuto	19 Nov 2005 12:25:49 -0000	1.7
+++ DatabaseAuto	28 Sep 2006 16:34:56 -0000	1.8
@@ -165,13 +165,13 @@
 in the <literal>public</literal> schema of a database, and not in
 any other schemas.
 <programlisting>
-DatabaseAuto dbi:Pg:DBNAME USERNAME PASSWORD '' public
+DatabaseAuto dbi:Pg:dbname=DBNAME USERNAME PASSWORD '' public
 </programlisting>
 __END__
 
 __NAME__ example: Making Interchange recognize views
 <programlisting>
-DatabaseAuto dbi:Pg:DBNAME USERNAME PASSWORD  ''  public  ''  VIEW
+DatabaseAuto dbi:Pg:dbname=DBNAME USERNAME PASSWORD  ''  public  ''  VIEW
 </programlisting>
 (The <literal>VIEW</literal> argument should be passed as shown
 &mdash; literally and in uppercase).



1.3       +3 -3      xmldocs/refs/UserTag


rev 1.3, prev_rev 1.2
Index: UserTag
===================================================================
RCS file: /var/cvs/xmldocs/refs/UserTag,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- UserTag	28 Jan 2006 13:45:52 -0000	1.2
+++ UserTag	28 Sep 2006 16:34:56 -0000	1.3
@@ -21,9 +21,9 @@
 
 
 __NAME__ notes
-Catalog-based usertag will run under <classname>Safe</classname> restrictions
-and will only be accessible from the corresponding catalog.
-For many purposes, a global &conf-UserTag;s are better. They're not restricted
+Catalog-based usertag will run under &glos-safe; restrictions,
+and will only be accessible only from the corresponding catalog.
+Global &conf-UserTag;s are not restricted
 by <classname>Safe</classname> and are available to all catalogs running on
 the server.
 __END__



1.5       +2 -1      xmldocs/refs/counter.tag


rev 1.5, prev_rev 1.4
Index: counter.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/counter.tag,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- counter.tag	18 Dec 2005 12:51:12 -0000	1.4
+++ counter.tag	28 Sep 2006 16:34:56 -0000	1.5
@@ -239,7 +239,8 @@
   <!-- DFL -->
   </entry>
   <entry>
-  Literal value to set counter to
+  Only show the counter value, without incrementing or decrementing it?
+	(This option is not applicable to SQL counters).
   </entry>
 
 </row> 



1.6       +6 -0      xmldocs/refs/dump.tag


rev 1.6, prev_rev 1.5
Index: dump.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/dump.tag,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- dump.tag	8 May 2006 19:48:33 -0000	1.5
+++ dump.tag	28 Sep 2006 16:34:56 -0000	1.6
@@ -72,3 +72,9 @@
 ]]></programlisting>
 __END__
 
+__NAME__ example: Displaying current user's cart structure
+<programlisting><![CDATA[
+<pre>[dump key=carts]</pre>
+]]></programlisting>
+__END__
+








More information about the docs mailing list