[docs] xmldocs - docelic modified 10 files

docs at icdevgroup.org docs at icdevgroup.org
Sat Jan 28 08:45:53 EST 2006 

User:      docelic
Date:      2006-01-28 13:45:53 GMT
Modified:  glossary configuration
Modified:  refs     Catalog Cookies Filter GlobalSub Locale MailOrderTo
Modified:           SubCatalog SysLog UserTag
Log:
* Fixes and updates

Revision  Changes    Path
1.6       +112 -0    xmldocs/glossary/configuration


rev 1.6, prev_rev 1.5
Index: configuration
===================================================================
RCS file: /var/cvs/xmldocs/glossary/configuration,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- configuration	24 Jan 2006 16:06:47 -0000	1.5
+++ configuration	28 Jan 2006 13:45:52 -0000	1.6
@@ -156,7 +156,119 @@
 </programlisting>
 </para>
 </section>
+</section>
+
+<section>
+<title>Subroutine watches</title>
+<para>
+It may come to you as a surprise, to learn that any configuration directive
+can be "tied" to a &PERL; subroutine (if the <classname>Tie::Watch</classname>
+Perl module is installed). This allows for a kind of triggers, watch points,
+or numerous other interesting applications.
+</para><para>
+Similar to "here documents" ("<literal>&lt;&lt;</literal>"), subroutine watches
+are defined using the "<literal>&lt;&amp;</literal>" notation. Consider the 
+following example:
+<programlisting>
+MailOrderTo orders@&def-hostname;
+MailOrderTo &lt;&amp;EOF
+sub {
+	my($self, $default) = @_;
+	if($Values->{special_handling}) {
+		return 'vip@&def-hostname;';
+	}
+	else {
+		return $default;
+	}
+}
+EOF
+</programlisting>
+When &IC; tries to retrieve the value of the &conf-MailOrderTo; configuration
+directive (usually to e-mail out an order), our subroutine watch is called. In 
+turn, it returns a special value (a separate e-mail address) for customers
+having &glos-value; "<literal>special_handling</literal>" defined in their
+session. For the rest, it simply returns the default value.
+</para><para>
+Now that you've grasped the basics, there's more to the story.
+From the above example, you see our watch subroutine was called in style
+of <code>&amp;{$subref}(<replaceable>SELF</replaceable>,
+<replaceable>PREVIOUS_VALUE</replaceable>)</code>.
+"<replaceable>SELF</replaceable>", meaning what it usually means in 
+&PERL; code, is a reference to the appropriate <classname>Tie::Watch</classname>
+object. "<replaceable>PREVIOUS_VALUE</replaceable>" is simply the previously
+set value for a directive (usually its default). Those are the standard
+two arguments we receive in a subroutine watch if the configuration directive
+was of type SCALAR (defined to accept one string or text value).
+</para>
+<note>
+<para>
+Subroutine watches must be defined <emphasis role='bold'>after</emphasis>
+the configuration directives have been set to their values.
+Setting values after subroutine watches will simply 
+destroy them (the watches) and have unpredictable effects.
+</para>
+</note>
+
+<para>
+If the configuration directive being watched was a list (type ARRAY), the
+subroutine would be called in pattern
+<code>&amp;{$subref}(<replaceable>SELF</replaceable>, 
+<replaceable>INDEX</replaceable>,
+<replaceable>PREVIOUS_VALUE</replaceable>)</code>.
+("<replaceable>INDEX</replaceable>" would be an array index of the
+item accessed). Setting watch points on arrays that you don't control
+completely is not recommended. (Namely, most &IC; subroutines call arrays
+in their list context, and no access method is provided for that).
+</para>
+
+<para>
+Finally, if the configuration directive watched was a hash (type HASH), 
+the subroutine would be called in pattern 
+<code>&amp;{$subref}(<replaceable>SELF</replaceable>, 
+<replaceable>KEY</replaceable>,
+<replaceable>PREVIOUS_VALUE</replaceable>)</code>.
+("<replaceable>KEY</replaceable>" would be a name of the
+hash value accessed).
+In the following example, we tie the &conf-Variable; configuration directive.
+This is not recommended for performance reasons &mdash; &conf-Variable;
+directive is called very often and should not bear any extra overhead). But
+it illustrates the power of this operation:
+<programlisting>
+Variable TESTIT Unwatch worked.
 
+Variable &lt;&amp;EOV
+sub {
+  my ($self, $key, $orig) = @_;
+
+  if($key eq 'TESTIT') {
+    # only the first time
+    if($Scratch->{$key}++) {
+      $self->Unwatch();
+      return $orig->{TESTIT};
+    }
+    else {
+      return "Tie::Watch works! -- name=$Values->{fname}";
+    }
+  }
+  else {
+    return $orig->{$key};
+  }
+}
+EOV
+</programlisting>
+The first time <code>__TESTIT__</code> is called for an individual user,
+it would return the string "<literal>Tie::Watch works! -- name=<replaceable>NAME</replaceable></literal>"
+along with their first name (if they provided one at some point).
+On a second access (again, for an individual user),
+the watch would be dynamically dropped and the default value of the
+variable <varname>TESTIT</varname> returned.
+All other variables would operate as usual.
+</para>
 </section>
+
+<!--
+	TODO WATCH example doesn't work. Eats memory like crazy halts the machine
+	-->
+
 <para>
 



1.6       +2 -2      xmldocs/refs/Catalog


rev 1.6, prev_rev 1.5
Index: Catalog
===================================================================
RCS file: /var/cvs/xmldocs/refs/Catalog,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- Catalog	24 Jan 2006 16:06:47 -0000	1.5
+++ Catalog	28 Jan 2006 13:45:52 -0000	1.6
@@ -8,8 +8,8 @@
 
 __NAME__ synopsis
 	<arg choice='plain'><replaceable>name</replaceable></arg>
-	<arg choice='plain'><replaceable>&glos-CATROOT;</replaceable></arg>
-	<arg choice='plain' rep='repeat'><replaceable>&glos-link-program;</replaceable></arg>
+	<arg choice='plain'><replaceable>catalog_directory</replaceable></arg>
+	<arg choice='plain' rep='repeat'><replaceable>link_program_path</replaceable></arg>
 __END__
 
 



1.3       +2 -1      xmldocs/refs/Cookies


rev 1.3, prev_rev 1.2
Index: Cookies
===================================================================
RCS file: /var/cvs/xmldocs/refs/Cookies,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- Cookies	11 Jun 2005 08:59:51 -0000	1.2
+++ Cookies	28 Jan 2006 13:45:52 -0000	1.3
@@ -14,10 +14,11 @@
 __NAME__ description
 The directive determines whether &IC; will send &glos-cookie; to the client and
 read it back to keep track of &glos-session; ID.
+</para><para>
+For a complete discussion, see &glos-cookie; glossary entry.
 __END__
 Caching, timed builds, and static page building will never be in effect unless
 this directive is enabled.
-
 
 __NAME__ see also
 CookieLogin,SaveExpire



1.2       +2 -2      xmldocs/refs/Filter


rev 1.2, prev_rev 1.1
Index: Filter
===================================================================
RCS file: /var/cvs/xmldocs/refs/Filter,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Filter	11 Jun 2005 17:22:36 -0000	1.1
+++ Filter	28 Jan 2006 13:45:52 -0000	1.2
@@ -16,8 +16,8 @@
 __END__
 
 __NAME__ description
-The directive assigns one or more filters (comma separated) that should be
-automatically applied to a variable.
+The directive assigns one or more (space separated) &glos-filter;s
+that should be automatically applied to a variable.
 __END__
 
 



1.3       +3 -2      xmldocs/refs/GlobalSub


rev 1.3, prev_rev 1.2
Index: GlobalSub
===================================================================
RCS file: /var/cvs/xmldocs/refs/GlobalSub,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- GlobalSub	19 Nov 2005 22:37:41 -0000	1.2
+++ GlobalSub	28 Jan 2006 13:45:52 -0000	1.3
@@ -52,8 +52,9 @@
 marker (as you would in &PERL;).
 </para><para>
 Global subroutines are not subject to <classname>Safe</classname> security 
-checks. Therefore, &glos-scratch; or catalog subroutines (&conf-Sub;s) are
-preferred in most cases.
+checks. They can do most anything!
+Therefore, &glos-scratch; or catalog subroutines (&conf-Sub;s) are
+preferred in most cases to protect the innocent.
 __END__
 
 



1.6       +57 -8     xmldocs/refs/Locale


rev 1.6, prev_rev 1.5
Index: Locale
===================================================================
RCS file: /var/cvs/xmldocs/refs/Locale,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- Locale	19 Nov 2005 22:37:41 -0000	1.5
+++ Locale	28 Jan 2006 13:45:52 -0000	1.6
@@ -1,18 +1,59 @@
 __NAME__ purpose
-specify global locale for use in error messages
+specify locale definitions
 __END__
 
 
 __NAME__ synopsis
-<group choice='req'>
-	<arg choice='plain'>locale definition</arg>
-</group>
+<arg choice='opt'><replaceable>locale<replaceable></arg><sbr/>
+<arg choice='plain' rep='repeat'><replaceable>locale_key<replaceable> <replaceable>locale_value</replaceable></arg><sbr/>
+<arg choice='plain' rep='repeat'><replaceable>locale<replaceable></arg> <replaceable>locale_key<replaceable> <replaceable>locale_value</replaceable></arg><sbr/>
 __END__
 
 
 __NAME__ description
-The directive specifies the global &glos-locale; for error messages.
-The content is usually loaded from a file.
+The directive specifies the default &glos-locale; definitions for
+a number of items:
+<itemizedlist>
+<listitem><para>
+<literal>currency_symbol</literal> - default currency symbol. Can be a simple value like "<literal>$</literal>" or " <literal>E</literal>", or a more flexible setting such as '<literal>&lt;img src="euro.png" /&gt;</literal>'.
+</para></listitem>
+<listitem><para>
+<literal>frac_digits</literal> - 
+</para></listitem>
+<listitem><para>
+<literal>int_curr_symbol</literal> -
+</para></listitem>
+<listitem><para>
+<literal>int_frac_digits</literal> -
+</para></listitem>
+<listitem><para>
+<literal>mon_decimal_point</literal> -
+</para></listitem>
+<listitem><para>
+<literal>mon_grouping</literal> -
+</para></listitem>
+<listitem><para>
+<literal>price_picture</literal> -
+</para></listitem>
+<listitem><para>
+<literal>mon_thousands_sep</literal> -
+</para></listitem>
+<listitem><para>
+<literal>n_cs_precedes</literal> -
+</para></listitem>
+<listitem><para>
+<literal>negative_sign</literal> -
+</para></listitem>
+<listitem><para>
+<literal>p_cs_precedes</literal> -
+</para></listitem>
+<listitem><para>
+<literal>p_sep_by_space</literal> -
+</para></listitem>
+<listitem><para>
+<literal>positive_sign</literal> -
+</para></listitem>
+</itemizedlist>
 __END__
 
 __NAME__ notes
@@ -21,11 +62,19 @@
 "default" found will be set as the actual default.
 __END__
 
-__NAME__ example: Defining Locale
+__NAME__ example: Defining general Locale
+<programlisting>
+Locale fr
+</programlisting>
+__END__
+
+__NAME__ example: Defining Locale by individual keys
 Put the following in &gcf;:
 <programlisting>
-Locale &lt;locale.error
+Locale &lt;localedata
 </programlisting>
+The actual file <filename>localedata<filename> could be composed
+of the keys listed in <xref linkend="Locale_description"/>.
 __END__
 
 __NAME__ missing



1.3       +2 -0      xmldocs/refs/MailOrderTo


rev 1.3, prev_rev 1.2
Index: MailOrderTo
===================================================================
RCS file: /var/cvs/xmldocs/refs/MailOrderTo,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- MailOrderTo	15 Jun 2005 10:30:13 -0000	1.2
+++ MailOrderTo	28 Jan 2006 13:45:52 -0000	1.3
@@ -14,6 +14,8 @@
 __NAME__ description
 The directive specifies
 an e-mail address that completed orders should be sent to.
+With a setting of '<literal>none</literal>', no e-mail order reports
+would be sent.
 __END__
 
 __NAME__ notes



1.2       +12 -4     xmldocs/refs/SubCatalog


rev 1.2, prev_rev 1.1
Index: SubCatalog
===================================================================
RCS file: /var/cvs/xmldocs/refs/SubCatalog,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- SubCatalog	9 Jun 2005 12:02:44 -0000	1.1
+++ SubCatalog	28 Jan 2006 13:45:52 -0000	1.2
@@ -9,19 +9,27 @@
 __NAME__ synopsis
 	<arg choice='plain'><replaceable>subcatalog_name</replaceable></arg>
 	<arg choice='plain'><replaceable>base_catalog_name</replaceable></arg>
-	<arg choice='plain'><replaceable>&glos-CATROOT;</replaceable></arg>
-	<arg choice='plain' rep='repeat'><replaceable>&glos-link-program;</replaceable></arg>
+	<arg choice='plain'><replaceable>catalog_directory</replaceable></arg>
+	<arg choice='plain' rep='repeat'><replaceable>link_program_path</replaceable></arg>
 __END__
 
 
 __NAME__ description
 The directive allows definition of "subcatalogs" &mdash; &glos-catalog;s that
 share most of the characteristics of
-another, "base" catalog. Only the directives that are changed from the
-base catalog are added.
+another, "base" catalog.
+In a &conf-SubCatalog; setup, the appropriate &ccf; should only contain
+directives that differ from definitions in the base catalog's &ccf;.
 </para><para>
 &IC;'s subcatalogs feature isn't used much, but primary reasons for its use
 would be memory savings, or some kind of chained-configuration catalogs.
+</para><para>
+Concerning the directive arguments, <literal>subcatalog_name</literal> and
+<literal>base_catalog_name</literal> are the names of the new and existing
+catalog respectively. <literal>catalog_directory</literal> (&glos-CATROOT;)
+defines the catalog root directory, and can be the same for both the master-
+and sub-catalog. Finally, the &glos-link-program; is a webserver path by
+which the subcatalog can be accessed.
 __END__
 
 __NAME__ notes



1.2       +1 -1      xmldocs/refs/SysLog


rev 1.2, prev_rev 1.1
Index: SysLog
===================================================================
RCS file: /var/cvs/xmldocs/refs/SysLog,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- SysLog	18 Dec 2005 11:32:11 -0000	1.1
+++ SysLog	28 Jan 2006 13:45:52 -0000	1.2
@@ -1,5 +1,5 @@
 __NAME__ purpose
-instruct Interchange to log to system's syslog
+instruct Interchange to log to Unix system's log (syslog)
 __END__
 
 __NAME__ see also



1.2       +3 -0      xmldocs/refs/UserTag


rev 1.2, prev_rev 1.1
Index: UserTag
===================================================================
RCS file: /var/cvs/xmldocs/refs/UserTag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- UserTag	9 Jun 2005 12:02:44 -0000	1.1
+++ UserTag	28 Jan 2006 13:45:52 -0000	1.2
@@ -33,3 +33,6 @@
 _END__
 
 
+__NAME__ missing
+Take a look in there
+__END__

More information about the docs mailing list