[docs] xmldocs - docelic modified 26 files
docs at icdevgroup.org
docs at icdevgroup.org
Wed Sep 14 19:10:31 EDT 2005
User: docelic
Date: 2005-09-14 23:10:31 GMT
Modified: docbook xmldocs.css
Modified: refs backup-file.tag cp.tag data.tag db-date.tag
Modified: debug.tag default.tag description.tag dump.tag
Modified: dump_session.tag nitems.tag price.tag scratch.tag
Modified: scratchd.tag set.tag seti.tag time.tag tmp.tag
Modified: tmpn.tag value.tag version.tag with.tag
Modified: xfer-catalog.tag
Added: glossary cart debug environment
Log:
- docbook/xmldocs.css: minimal CSS adjustment
- refs/*: about 20 tags added
- glossary/*: placeholders
Revision Changes Path
1.22 +1 -1 xmldocs/docbook/xmldocs.css
rev 1.22, prev_rev 1.21
Index: xmldocs.css
===================================================================
RCS file: /var/cvs/xmldocs/docbook/xmldocs.css,v
retrieving revision 1.21
retrieving revision 1.22
diff -u -r1.21 -r1.22
--- xmldocs.css 1 Sep 2005 23:12:38 -0000 1.21
+++ xmldocs.css 14 Sep 2005 23:10:30 -0000 1.22
@@ -253,7 +253,7 @@
.screen {
margin-top: 0;
padding: 4px 4px 4px 4px;
- border-left: dashed 1px #ffd1d1;
+ border-left: dashed 1px #ff8300; /*#ffd1d1;*/
padding-left: 8px;
}
1.1 xmldocs/glossary/cart
<<cart: empty>>
1.1 xmldocs/glossary/debug
<<debug: empty>>
1.1 xmldocs/glossary/environment
<<environment: empty>>
1.2 +68 -0 xmldocs/refs/backup-file.tag
rev 1.2, prev_rev 1.1
Index: backup-file.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/backup-file.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- backup-file.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ backup-file.tag 14 Sep 2005 23:10:30 -0000 1.2
@@ -0,0 +1,68 @@
+__NAME__ purpose
+backup Interchange file
+__END__
+
+__NAME__ synopsis
+<row>
+
+ <entry>
+ file
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ </entry>
+ <entry>
+ File to back-up
+ </entry>
+
+</row>
+&ROW_INTERPOLATE_0;
+&ROW_REPARSE_1;
+__END__
+
+
+__NAME__ description
+The tag allows backing up of Interchange files.
+Files are simply copied
+to the <filename class='directory'>backup/</filename> subdirectory of
+the catalog root directory (&glos-CATROOT;).
+</para><para>
+File paths are preserved during copy; a target catalog file of say,
+<filename>pages/index.html</filename> would be saved to
+<filename>backup/pages/index.html</filename>.
+</para><para>
+You can copy filenames specified with absolute paths, and in fact, you
+can backup any file that the &IC; process can read.
+__END__
+
+
+__NAME__ notes
+The backup directory and the full pathname are automatically created
+if they don't already exist.
+__END__
+
+__NAME__ example: Backing-up catalog index page
+<programlisting>
+[either]
+ [tmp name=backup set="[backup-file pages/index.html]" hide=1]
+[or]
+ [scratch ui_error]
+[/either]
+</programlisting>
+__END__
+
+__NAME__ example: Backing-up system password file
+<programlisting>
+[either]
+ [tmp name=backup set="[backup-file /etc/passwd]" hide=1]
+[or]
+ [scratch ui_error]
+[/either]
+</programlisting>
+__END__
+
1.2 +52 -8 xmldocs/refs/cp.tag
rev 1.2, prev_rev 1.1
Index: cp.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/cp.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- cp.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ cp.tag 14 Sep 2005 23:10:30 -0000 1.2
@@ -1,27 +1,50 @@
+__NAME__ purpose
+copy a file
+__END__
+
__NAME__ synopsis
<row>
<entry>
- umask
+ from
</entry>
<entry>
- <!-- POS -->
+ Yes
</entry>
<entry>
- <!-- REQ -->
+ Yes
+ </entry>
+ <entry>
+ <!-- DFL -->
+ </entry>
+ <entry>
+ Source file to copy.
+ </entry>
+
+</row>
+<row>
+
+ <entry>
+ to
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ Yes
</entry>
<entry>
<!-- DFL -->
</entry>
<entry>
- <!-- DSC -->
+ Destination directory or file to copy to.
</entry>
</row>
<row>
<entry>
- hide
+ umask
</entry>
<entry>
<!-- POS -->
@@ -30,13 +53,34 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ Interchange process default
</entry>
<entry>
- <!-- DSC -->
+ File &glos-umask;.
</entry>
</row>
+&ROW_HIDE_0;
&ROW_INTERPOLATE_0;
&ROW_REPARSE_1;
-__END__
\ No newline at end of file
+__END__
+
+
+__NAME__ description
+The tag simply copies source file to the destination.
+__END__
+
+__NAME__ see also
+backup-file,backup-database
+__END__
+
+__NAME__ example: Basic example
+<programlisting>
+[either]
+ [cp from=pages/index.html to=/tmp/ hide=1]
+[or]
+ Copy failed. See error logs for details.
+[/either]
+</programlisting>
+__END__
+
1.2 +228 -16 xmldocs/refs/data.tag
rev 1.2, prev_rev 1.1
Index: data.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/data.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- data.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ data.tag 14 Sep 2005 23:10:30 -0000 1.2
@@ -1,7 +1,81 @@
+__NAME__ purpose
+get or set value of a named field or row from a database table or user session
+__END__
+
__NAME__ synopsis
<row>
<entry>
+ <group choice='optional'>
+ <arg choice='plain'>table</arg>
+ <arg choice='plain'>base</arg>
+ <arg choice='plain'>database</arg>
+ </group>
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ <!-- DFL -->
+ </entry>
+ <entry>
+ The name of the table to fetch from.
+ </entry>
+
+</row>
+<row>
+
+ <entry>
+ <group choice='optional'>
+ <arg choice='plain'>field</arg>
+ <arg choice='plain'>col</arg>
+ <arg choice='plain'>column</arg>
+ <arg choice='plain'>name</arg>
+ </group>
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ <!-- DFL -->
+ </entry>
+ <entry>
+ The name of the field whose value you want to fetch.
+ Required unless returning the entire row in combination with
+ the <literal>hash=</literal> option.
+ </entry>
+</row>
+<row>
+
+ <entry>
+ <group choice='optional'>
+ <arg choice='plain'>key</arg>
+ <arg choice='plain'>code</arg>
+ <arg choice='plain'>row</arg>
+ </group>
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ </entry>
+ <entry>
+ <!-- DFL -->
+ </entry>
+ <entry>
+ The key that identifies the row to fetch.
+ </entry>
+
+</row>
+<row>
+
+ <entry>
safe_data
</entry>
<entry>
@@ -11,10 +85,10 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ 0
</entry>
<entry>
- <!-- DSC -->
+ Is data &glos-safe;?
</entry>
</row>
@@ -33,7 +107,10 @@
<!-- DFL -->
</entry>
<entry>
- <!-- DSC -->
+ Set field to specified value. If <literal>increment=</literal> is true,
+ increment
+ the field by the specified value (negative increments can be used for
+ decreasing).
</entry>
</row>
@@ -52,7 +129,9 @@
<!-- DFL -->
</entry>
<entry>
- <!-- DSC -->
+ If reading a field, apply specified &glos-filter; to the value before
+ displaying. It setting a field, apply specified filter to the value before
+ updating the database.
</entry>
</row>
@@ -68,10 +147,12 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ 0
</entry>
<entry>
- <!-- DSC -->
+ Increment or decrement field content by <literal>value=</literal>?
+ Unless <literal>value=</literal> is specified, increment by
+ <literal>1</literal>.
</entry>
</row>
@@ -87,10 +168,10 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ 0
</entry>
<entry>
- <!-- DSC -->
+ Append the field instead of "truncating" before write?
</entry>
</row>
@@ -109,14 +190,15 @@
<!-- DFL -->
</entry>
<entry>
- <!-- DSC -->
+ <literal>change</literal>, <literal>add</literal> or
+ <literal>delete</literal>.
</entry>
</row>
<row>
<entry>
- foreign
+ serial
</entry>
<entry>
<!-- POS -->
@@ -125,17 +207,16 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ 0
</entry>
<entry>
- <!-- DSC -->
</entry>
</row>
<row>
<entry>
- serial
+ foreign
</entry>
<entry>
<!-- POS -->
@@ -147,7 +228,11 @@
<!-- DFL -->
</entry>
<entry>
- <!-- DSC -->
+ Select data element based on a specified foreign key. This allows selection
+ of a field or row based on a column that is not the primary key in the
+ &glos-database; table. If the key is unique, first selected is returned.
+ Foreign key can also be specified as a hash, see
+ <xref linkend="data_examples"/>.
</entry>
</row>
@@ -166,10 +251,137 @@
<!-- DFL -->
</entry>
<entry>
- <!-- DSC -->
+ Return the result as a reference to a hash? Hash keys will correspond
+ to column names.
</entry>
</row>
&ROW_INTERPOLATE_0;
&ROW_REPARSE_1;
-__END__
\ No newline at end of file
+__END__
+
+
+__NAME__ description
+The tag is primarily used for reading fields from database tables or
+user's &glos-session; namespace. However, with appropriate options,
+whole rows can be returned, and the fields can be set, incremented,
+appended and filtered.
+</para><para>
+If a database with <literal>WRITE_CONTROL</literal> enabled is to be written
+(such as a DBM-based database, which has it by default), it must be flagged
+writable on the page wishing to perform the update;
+use <code>[tag flag write]<replaceable>DATABASE_NAME</replaceable>[/tag]</code>
+to mark a database writable, and do this before any access to that table.
+</para><para>
+In addition, the &tag-data; tag can access values in users'
+&glos-session; namespace, using the special <literal>session</literal> keyword.
+Do not call your own database "<literal>session</literal>" because it would
+mask accesses to the actual sessions database.
+__END__
+
+__NAME__ see also
+tag,dump_session
+__END__
+
+
+__NAME__ missing
+What do alter and serial do
+__END__
+
+
+__NAME__ example: Basic example
+Display price for the item SKU <literal>4595</literal>:
+<programlisting>
+[data products price 4595]
+</programlisting>
+__END__
+
+__NAME__ example: Dumping user session
+To dump user &glos-session;, see &tag-dump_session;. Once you do it, you can
+learn the names of all the session keys you can use in the following example.
+__END__
+
+__NAME__ example: Retrieving session values
+In this example we produce a simple "report" about the user. We take the
+data from the user's session record.
+<programlisting><![CDATA[
+[if session logged_in]
+ User is logged in as [data session username].
+[else]
+ User is not logged in.
+[/else]
+[/if] <br />
+[data session host] is user's IP. <br />
+Browser used is [data session browser]. <br />
+]]></programlisting>
+__END__
+
+__NAME__ example: Retrieving fields from a table using a foreign key
+If we wrote <code>[data products price 4595]</code>, we would retrieve
+the price of the item &glos-SKU; <literal>4595</literal>. The SKU column
+is the <emphasis>primary key</emphasis> in the <database>products</database>
+database, and that's why &IC; implicitly searches it for the specified
+<literal>key=</literal>.
+</para><para>
+To retrieve price of an item based on say, it's description field (which
+is not a primary key), we need to use the foreign key functionality:
+<programlisting>
+[data
+ table=products
+ column=price
+ foreign=description
+ key="Nice Bio Test"
+]
+</programlisting>
+__END__
+
+__NAME__ example: Retrieving fields from a table using foreign key hash
+To retrieve &glos-SKU; of an item based on say, both it's description and
+price fields, we need to use the foreign key functionality with the hash
+argument:
+<programlisting>
+[data
+ table=products
+ column=price
+ foreign.description='Nice Bio Test'
+ foreign.price=275.45
+]
+</programlisting>
+TODO not working
+__END__
+
+__NAME__ example: Retrieving fields from a table using foreign key array
+Sometimes you want a query that is optimized in a particular order. To
+achieve that, use either your custom code, or an array-type foreign key:
+<programlisting>
+[data
+ table=products
+ column=price
+ foreign.0="price=275.45"
+ foreign.1="description='Nice Bio Test'"
+]
+</programlisting>
+TODO not working
+__END__
+
+__NAME__ example: Retrieving rows from a database
+Here's a &PERL; example of retrieving complete table rows.
+<programlisting>
+[perl tables=products]
+ my $row_hash = $Tag->data({
+ table => 'products',
+ key => '4595',
+ hash => 1
+ });
+
+ my $out = "Item SKU " . $row_hash->{sku} . " has";
+
+ $out .= " price " . $row_hash->{price} . " and" .
+ " description " . $row_hash->{description} . ". Cheers!";
+
+ $out
+[/perl]
+</programlisting>
+__END__
+
+
1.2 +54 -0 xmldocs/refs/db-date.tag
rev 1.2, prev_rev 1.1
Index: db-date.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/db-date.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- db-date.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ db-date.tag 14 Sep 2005 23:10:30 -0000 1.2
@@ -0,0 +1,54 @@
+__NAME__ purpose
+report last-modified time of the named database source file
+__END__
+
+
+__NAME__ see also
+__END__
+
+__NAME__ synopsis
+<row>
+ <entry>
+ table
+ </entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ <entry><literal>products</literal></entry>
+ <entry>Interchange &glos-database; name.</entry>
+</row>
+<row>
+ <entry>
+ format
+ </entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ <entry><literal>%A %d %b %Y</literal></entry>
+ <entry>POSIX strftime format specifier.</entry>
+</row>
+&ROW_INTERPOLATE_0;
+&ROW_REPARSE_1;
+__END__
+
+__NAME__ description
+The tag displays the last-modified time of the &glos-database; source
+text file. Output format can be specified using <literal>format=</literal>.
+__END__
+
+
+__NAME__ notes
+This tag will be of use for you only if you use source file based
+&glos-database;s.
+If you use &glos-SQL; databases, the logical connection with text source
+files will probably not be maintained so the output of this tag will be
+worthless.
+__END__
+
+
+__NAME__ example: Displaying products database last-modified time
+Provided that you use file-based databases in your catalog (*DB* variants),
+you can run this example:
+<programlisting>
+[db-date]
+</programlisting>
+__END__
+
1.2 +35 -0 xmldocs/refs/debug.tag
rev 1.2, prev_rev 1.1
Index: debug.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/debug.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- debug.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ debug.tag 14 Sep 2005 23:10:30 -0000 1.2
@@ -0,0 +1,35 @@
+__NAME__ purpose
+send messages to debug log
+__END__
+
+__NAME__ see also
+__END__
+
+
+O: List items missing to consider the item completely documented.
+ Each item in its own line, without any formatting.
+__NAME__ missing
+__END__
+
+
+__NAME__ synopsis
+&ROW_INTERPOLATE_0;
+&ROW_REPARSE_1;
+__END__
+
+__NAME__ description
+The tags sends a message to &IC; debug log.
+__END__
+
+
+__NAME__ notes
+Debugging must be enabled for the tag to produce any
+noticeable effect; see &glos-debug; glossary entry.
+__END__
+
+__NAME__ example: Sending a message to debug log
+<programlisting>
+[debug] There are [nitems] items in session [data session id] [/debug]
+</programlisting>
+__END__
+
1.2 +200 -2 xmldocs/refs/default.tag
rev 1.2, prev_rev 1.1
Index: default.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/default.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- default.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ default.tag 14 Sep 2005 23:10:30 -0000 1.2
@@ -1,10 +1,91 @@
+__NAME__ purpose
+(deprecated) return content of the named form input field, defaulting to value 'default'
+__END__
+
+
__NAME__ synopsis
<row>
<entry>
+ name
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ </entry>
+ <entry>
+ Name of the form variable.
+ </entry>
+
+</row>
+<row>
+
+ <entry>
default
</entry>
<entry>
+ Yes
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ <literal>default</literal>
+ </entry>
+ <entry>
+ Default value to return if the specified variable is <emphasis>missing or
+ evaluates to a false value</emphasis>.
+ </entry>
+
+</row>
+<row>
+
+ <entry>
+ values_space
+ </entry>
+ <entry>
+ <!-- POS -->
+ </entry>
+ <entry>
+ <!-- REQ -->
+ </entry>
+ <entry>
+ <!-- DFL -->
+ </entry>
+ <entry>
+ Specify "&glos-value;s space" in which to perform the operation.
+ </entry>
+
+</row>
+<row>
+
+ <entry>
+ set
+ </entry>
+ <entry>
+ <!-- POS -->
+ </entry>
+ <entry>
+ <!-- REQ -->
+ </entry>
+ <entry>
+ <!-- DFL -->
+ </entry>
+ <entry>
+ Set form field variable &glos-value; to the specified content.
+ </entry>
+
+</row>
+<row>
+
+ <entry>
+ filter
+ </entry>
+ <entry>
<!-- POS -->
</entry>
<entry>
@@ -14,10 +95,127 @@
<!-- DFL -->
</entry>
<entry>
- <!-- DSC -->
+ Apply specified &glos-filter; to the variable content. The application of
+ a filter actually modifies the variable value in-place (in addition to,
+ of course, displaying the filtered content).
</entry>
</row>
+<row>
+
+ <entry>
+ keep
+ </entry>
+ <entry>
+ <!-- POS -->
+ </entry>
+ <entry>
+ <!-- REQ -->
+ </entry>
+ <entry>
+ 0
+ </entry>
+ <entry>
+ Only apply filter for display, and do not modify actual variable value?
+ </entry>
+
+</row>
+<row>
+
+ <entry>
+ scratch
+ </entry>
+ <entry>
+ <!-- POS -->
+ </entry>
+ <entry>
+ <!-- REQ -->
+ </entry>
+ <entry>
+ 0
+ </entry>
+ <entry>
+ Along with setting a form field value, also create the variable/content
+ pair in the &glos-scratch; space?
+ </entry>
+
+</row>
+<row>
+
+ <entry>
+ enable_itl
+ </entry>
+ <entry>
+ <!-- POS -->
+ </entry>
+ <entry>
+ <!-- REQ -->
+ </entry>
+ <entry>
+ 0
+ </entry>
+ <entry>
+ Allow &glos-ITL; tags to appear in the output? By default, all
+ "<literal>[</literal>" characters are encoded as
+ "<literal>&#91;</literal>".
+ </entry>
+
+</row>
+<row>
+
+ <entry>
+ enable_html
+ </entry>
+ <entry>
+ <!-- POS -->
+ </entry>
+ <entry>
+ <!-- REQ -->
+ </entry>
+ <entry>
+ 0
+ </entry>
+ <entry>
+ Allow &glos-HTML; tags to appear in the output? By default, all
+ "<literal><</literal>" characters are encoded as
+ "<literal>&lt;</literal>".
+ </entry>
+
+</row>
+&ROW_HIDE_0;
&ROW_INTERPOLATE_0;
&ROW_REPARSE_1;
-__END__
\ No newline at end of file
+__END__
+
+
+__NAME__ description
+The tag returns the named form input field &glos-value;.
+Any &IC; tags in the output are &glos-HTML;- and &glos-ITL;-escaped by default
+for security reasons.
+</para><para>
+This tag is very similar to &tag-value;, except that it provides the
+default value for the <literal>default=</literal> parameter.
+
+__END__
+
+__NAME__ example: displaying user's first name
+<programlisting>
+Hello, [default fname Anonymous]!
+</programlisting>
+__END__
+
+__NAME__ example: displaying user's first name in a modifiable field
+<programlisting><![CDATA[
+<form action="[process]">
+ Hello, <input type="text" name="fname" value="[default fname Anonymous]" />!
+</form>
+]]></programlisting>
+TODO: Add a submit button
+__END__
+
+__NAME__ example: displaying user's first name, or falling back to the default
+<programlisting><![CDATA[
+Hello, [default fname Anonymous]!
+]]></programlisting>
+__END__
+
1.2 +47 -0 xmldocs/refs/description.tag
rev 1.2, prev_rev 1.1
Index: description.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/description.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- description.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ description.tag 14 Sep 2005 23:10:30 -0000 1.2
@@ -0,0 +1,47 @@
+__NAME__ purpose
+return description for a specific product from the products database
+__END__
+
+
+__NAME__ see also
+DescriptionField,price
+__END__
+
+
+__NAME__ synopsis
+<row>
+ <entry>
+ code
+ </entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ <entry></entry>
+ <entry>Product &glos-SKU;.</entry>
+</row>
+<row>
+ <entry>
+ base
+ </entry>
+ <entry>Yes</entry>
+ <entry></entry>
+ <entry>All &conf-ProductFiles; databases</entry>
+ <entry>Database to look up the product in.</entry>
+</row>
+&ROW_INTERPOLATE_0;
+&ROW_REPARSE_1;
+__END__
+
+
+__NAME__ description
+The tag returns the description for a specified product.
+If no <literal>base=</literal> is specified, all &conf-ProductFiles;
+are searched for the specified &glos-SKU;.
+__END__
+
+
+__NAME__ example: Displaying description for item 1299
+<programlisting>
+[description 1299]
+</programlisting>
+__END__
+
1.2 +65 -0 xmldocs/refs/dump.tag
rev 1.2, prev_rev 1.1
Index: dump.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/dump.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- dump.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ dump.tag 14 Sep 2005 23:10:30 -0000 1.2
@@ -0,0 +1,65 @@
+__NAME__ purpose
+dump all relevant information about a users' session
+__END__
+
+
+__NAME__ synopsis
+<row>
+ <entry>
+ key
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ </entry>
+ <entry>
+ </entry>
+ <entry>
+ User &glos-session; ID.
+ </entry>
+
+</row>
+<row>
+ <entry>no_env</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>0</entry>
+ <entry>Do not output &glos-environment; structure?</entry>
+</row>
+<row>
+ <entry>no_cgi</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>0</entry>
+ <entry>Do not output &glos-CGI; structure?</entry>
+</row>
+<row>
+ <entry>no_session</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>0</entry>
+ <entry>Do not output &glos-session; structure?</entry>
+</row>
+&ROW_INTERPOLATE_0;
+&ROW_REPARSE_1;
+__END__
+
+
+__NAME__ description
+The tag dumps client connection information, &glos-cart; contents, query value,
+&glos-environment; contents, &glos-session; contents, and &glos-CGI; contents
+to the page. This is useful for &glos-debug;ging.
+__END__
+
+
+__NAME__ see also
+dump_session
+__END__
+
+__NAME__ example: Displaying current user's session dump
+<programlisting><![CDATA[
+<pre> [dump] </pre>
+]]></programlisting>
+__END__
+
1.2 +53 -4 xmldocs/refs/dump_session.tag
rev 1.2, prev_rev 1.1
Index: dump_session.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/dump_session.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- dump_session.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ dump_session.tag 14 Sep 2005 23:10:30 -0000 1.2
@@ -1,6 +1,27 @@
+__NAME__ purpose
+dump named user session in whole or partially
+__END__
+
+
__NAME__ synopsis
<row>
+ <entry>
+ name
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ </entry>
+ <entry>
+ User &glos-session; ID.
+ </entry>
+</row>
+<row>
<entry>
joiner
</entry>
@@ -11,10 +32,9 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ A space
</entry>
<entry>
- <!-- DSC -->
</entry>
</row>
@@ -52,10 +72,39 @@
<!-- DFL -->
</entry>
<entry>
- <!-- DSC -->
+ Hash key to use as top-level value in session dump,
+ instead of the complete session.
</entry>
</row>
&ROW_INTERPOLATE_0;
&ROW_REPARSE_1;
-__END__
\ No newline at end of file
+__END__
+
+
+__NAME__ description
+The tag dumps content of a named &glos-session;.
+</para><para>
+If the <literal>key=</literal> argument is specified,
+that will become the top-level element for display.
+__END__
+
+
+__NAME__ see also
+dump
+__END__
+
+__NAME__ example: Displaying current user's session dump
+<programlisting><![CDATA[
+<pre> [dump-session name="[data session id]"] </pre>
+]]></programlisting>
+__END__
+
+__NAME__ example: Displaying a specific part of current user's session
+<programlisting><![CDATA[
+<pre> [dump-session name="[data session id]" key=browser] </pre>
+]]></programlisting>
+__END__
+
+
+TODO: clarify find=1, joiner=, and add appropriate examples
1.2 +43 -3 xmldocs/refs/nitems.tag
rev 1.2, prev_rev 1.1
Index: nitems.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/nitems.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- nitems.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ nitems.tag 14 Sep 2005 23:10:30 -0000 1.2
@@ -1,7 +1,30 @@
+__NAME__ purpose
+return the total number of items in the electronic cart
+__END__
+
__NAME__ synopsis
<row>
<entry>
+ name
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ <literal>$Vend::Items</literal>
+ </entry>
+ <entry>
+ Cart name.
+ </entry>
+
+</row>
+<row>
+
+ <entry>
qualifier
</entry>
<entry>
@@ -14,7 +37,8 @@
<!-- DFL -->
</entry>
<entry>
- <!-- DSC -->
+ An item attribute that must evaluate to a &glos-true; value,
+ in order for the item to be counted.
</entry>
</row>
@@ -33,10 +57,26 @@
<!-- DFL -->
</entry>
<entry>
- <!-- DSC -->
+ Instead of counting items based solely on item attribute
+ "&glos-true;ness" (as <literal>qualifier=</literal> does by default),
+ perform the specified regular expression pattern matching on the
+ <literal>qualifier=</literal> attribute.
</entry>
</row>
&ROW_INTERPOLATE_0;
&ROW_REPARSE_1;
-__END__
\ No newline at end of file
+__END__
+
+
+__NAME__ description
+The tag returns the total number of items in users' electronic cart.
+__END__
+
+__NAME__ example: Basic example
+<programlisting>
+You have [nitems] items in your cart.
+</programlisting>
+__END__
+
+TODO examples with qualifier and compare
1.2 +36 -0 xmldocs/refs/price.tag
rev 1.2, prev_rev 1.1
Index: price.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/price.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- price.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ price.tag 14 Sep 2005 23:10:30 -0000 1.2
@@ -0,0 +1,36 @@
+__NAME__ purpose
+return price for a specific product from the products database
+__END__
+
+
+__NAME__ see also
+PriceField,description
+__END__
+
+
+__NAME__ synopsis
+<row>
+ <entry>
+ code
+ </entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ <entry></entry>
+ <entry>Product &glos-SKU;.</entry>
+</row>
+&ROW_INTERPOLATE_0;
+&ROW_REPARSE_1;
+__END__
+
+
+__NAME__ description
+The tag returns the price for a specified product.
+__END__
+
+
+__NAME__ example: Displaying price for item 1299
+<programlisting>
+[price 1299]
+</programlisting>
+__END__
+
1.2 +42 -4 xmldocs/refs/scratch.tag
rev 1.2, prev_rev 1.1
Index: scratch.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/scratch.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- scratch.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ scratch.tag 14 Sep 2005 23:10:30 -0000 1.2
@@ -1,7 +1,30 @@
+__NAME__ purpose
+return content of the named scratch variable
+__END__
+
__NAME__ synopsis
<row>
<entry>
+ name
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ <!-- DFL -->
+ </entry>
+ <entry>
+ Name of the &glos-scratch; variable.
+ </entry>
+
+</row>
+<row>
+
+ <entry>
filter
</entry>
<entry>
@@ -14,7 +37,7 @@
<!-- DFL -->
</entry>
<entry>
- <!-- DSC -->
+ Filter to apply to the value.
</entry>
</row>
@@ -30,13 +53,28 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ 0
</entry>
<entry>
- <!-- DSC -->
+ Keep variable value in memory intact, and only apply filter for display?
</entry>
</row>
&ROW_INTERPOLATE_0;
&ROW_REPARSE_1;
-__END__
\ No newline at end of file
+__END__
+
+
+__NAME__ description
+The tag returns value of the named &glos-scratch; variable.
+__END__
+
+__NAME__ notes
+Scratch variables cannot be set using the &tag-scratch; tag; see
+&glos-scratch; glossary entry for a complete discussion.
+__END__
+
+__NAME__ see also
+scratch,scratchd,set,seti,tmp,tmpn,value
+__END__
+
1.2 +57 -2 xmldocs/refs/scratchd.tag
rev 1.2, prev_rev 1.1
Index: scratchd.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/scratchd.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- scratchd.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ scratchd.tag 14 Sep 2005 23:10:30 -0000 1.2
@@ -1,7 +1,30 @@
+__NAME__ purpose
+return content of the named scratch variable, then delete the variable
+__END__
+
__NAME__ synopsis
<row>
<entry>
+ name
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ <!-- DFL -->
+ </entry>
+ <entry>
+ Name of the &glos-scratch; variable.
+ </entry>
+
+</row>
+<row>
+
+ <entry>
filter
</entry>
<entry>
@@ -14,10 +37,42 @@
<!-- DFL -->
</entry>
<entry>
- <!-- DSC -->
+ Filter to apply to the value.
+ </entry>
+
+</row>
+<row>
+
+ <entry>
+ keep
+ </entry>
+ <entry>
+ <!-- POS -->
+ </entry>
+ <entry>
+ <!-- REQ -->
+ </entry>
+ <entry>
+ 0
+ </entry>
+ <entry>
+ Keep variable value in memory intact, and only apply filter for display?
</entry>
</row>
&ROW_INTERPOLATE_0;
&ROW_REPARSE_1;
-__END__
\ No newline at end of file
+__END__
+
+
+__NAME__ description
+The tag returns value of the named &glos-scratch; variable, and then
+deletes the variable.
+__END__
+
+__NAME__ notes
+Scratch variables cannot be set using the &tag-scratch; tag; see
+&glos-scratch; glossary entry for a complete discussion.
+__END__
+
+
1.2 +42 -0 xmldocs/refs/set.tag
rev 1.2, prev_rev 1.1
Index: set.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/set.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- set.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ set.tag 14 Sep 2005 23:10:30 -0000 1.2
@@ -0,0 +1,42 @@
+__NAME__ purpose
+set content of the named scratch variable
+__END__
+
+__NAME__ synopsis
+<row>
+
+ <entry>
+ name
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ <!-- DFL -->
+ </entry>
+ <entry>
+ Name of the &glos-scratch; variable.
+ </entry>
+
+</row>
+&ROW_INTERPOLATE_0;
+&ROW_REPARSE_1;
+__END__
+
+
+__NAME__ description
+The tag sets value of the named &glos-scratch; variable.
+</para><para>
+By default, the provided value is not &glos-interpolate;d before
+assignment. To interpolate contents, use &tag-seti; or provide
+<literal>interpolate=1</literal> attribute to this tag.
+__END__
+
+__NAME__ notes
+See &glos-scratch; glossary entry for a complete discussion.
+__END__
+
+
1.2 +42 -0 xmldocs/refs/seti.tag
rev 1.2, prev_rev 1.1
Index: seti.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/seti.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- seti.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ seti.tag 14 Sep 2005 23:10:30 -0000 1.2
@@ -0,0 +1,42 @@
+__NAME__ purpose
+set content of the named scratch variable, interpolating it before assignment
+__END__
+
+__NAME__ synopsis
+<row>
+
+ <entry>
+ name
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ <!-- DFL -->
+ </entry>
+ <entry>
+ Name of the &glos-scratch; variable.
+ </entry>
+
+</row>
+&ROW_INTERPOLATE_1;
+&ROW_REPARSE_1;
+__END__
+
+
+__NAME__ description
+The tag sets value of the named &glos-scratch; variable.
+</para><para>
+By default, the provided value is &glos-interpolate;d before
+assignment. To not interpolate contents, use &tag-set; or provide
+<literal>interpolate=0</literal> attribute to this tag.
+__END__
+
+__NAME__ notes
+See &glos-scratch; glossary entry for a complete discussion.
+__END__
+
+
1.3 +2 -22 xmldocs/refs/time.tag
rev 1.3, prev_rev 1.2
Index: time.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/time.tag,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- time.tag 7 Sep 2005 16:29:16 -0000 1.2
+++ time.tag 14 Sep 2005 23:10:30 -0000 1.3
@@ -139,7 +139,7 @@
<entry>
<group choice='opt'>
- <arg>format</arg><arg>fmt</arg>
+ <arg choice='plain'>format</arg><arg choice='plain'>fmt</arg>
</group>
</entry>
<entry>
@@ -152,27 +152,7 @@
<!-- DFL -->
</entry>
<entry>
- POSIX strftime format specifier. See <command>man strftime</command>
- for details.
- </entry>
-
-</row>
-<row>
-
- <entry>
- fmt
- </entry>
- <entry>
- <!-- POS -->
- </entry>
- <entry>
- <!-- REQ -->
- </entry>
- <entry>
- <!-- DFL -->
- </entry>
- <entry>
- <!-- DSC -->
+ POSIX strftime format specifier.
</entry>
</row>
1.2 +48 -0 xmldocs/refs/tmp.tag
rev 1.2, prev_rev 1.1
Index: tmp.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/tmp.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- tmp.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ tmp.tag 14 Sep 2005 23:10:30 -0000 1.2
@@ -0,0 +1,48 @@
+__NAME__ purpose
+set content of the named scratch variable, interpolating it before assignment
+__END__
+
+__NAME__ synopsis
+<row>
+
+ <entry>
+ name
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ <!-- DFL -->
+ </entry>
+ <entry>
+ Name of the temporary &glos-scratch; variable.
+ </entry>
+
+</row>
+&ROW_INTERPOLATE_1;
+&ROW_REPARSE_1;
+__END__
+
+
+__NAME__ description
+The tag sets value of the named temporary &glos-scratch; variable.
+</para><para>
+The variable is temporary in a way that &IC; adds its name to the list of
+variables to delete directly after the
+current page is processed and served.
+Except for being part of good design, temporary variables also speed up
+&glos-session; write time in many cases.
+</para><para>
+By default, the provided value is &glos-interpolate;d before
+assignment. To not interpolate contents, use &tag-tmpn; or provide
+<literal>interpolate=0</literal> attribute to this tag.
+__END__
+
+__NAME__ notes
+See &glos-scratch; glossary entry for a complete discussion.
+__END__
+
+
1.2 +48 -0 xmldocs/refs/tmpn.tag
rev 1.2, prev_rev 1.1
Index: tmpn.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/tmpn.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- tmpn.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ tmpn.tag 14 Sep 2005 23:10:30 -0000 1.2
@@ -0,0 +1,48 @@
+__NAME__ purpose
+set content of the named scratch variable
+__END__
+
+__NAME__ synopsis
+<row>
+
+ <entry>
+ name
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ <!-- DFL -->
+ </entry>
+ <entry>
+ Name of the temporary &glos-scratch; variable.
+ </entry>
+
+</row>
+&ROW_INTERPOLATE_0;
+&ROW_REPARSE_1;
+__END__
+
+
+__NAME__ description
+The tag sets value of the named temporary &glos-scratch; variable.
+</para><para>
+The variable is temporary in a way that &IC; adds its name to the list of
+variables to delete directly after the
+current page is processed and served.
+Except for being part of good design, temporary variables also speed up
+&glos-session; write time in many cases.
+</para><para>
+By default, the provided value is not &glos-interpolate;d before
+assignment. To interpolate contents, use &tag-tmp; or
+<literal>interpolate=1</literal> attribute to this tag.
+__END__
+
+__NAME__ notes
+See &glos-scratch; glossary entry for a complete discussion.
+__END__
+
+
1.3 +3 -0 xmldocs/refs/value.tag
rev 1.3, prev_rev 1.2
Index: value.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/value.tag,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- value.tag 3 Sep 2005 23:05:21 -0000 1.2
+++ value.tag 14 Sep 2005 23:10:30 -0000 1.3
@@ -196,6 +196,9 @@
Using the <literal>set=</literal> attribute, you can also set values.
__END__
+__NAME__ see also
+default
+__END__
__NAME__ example: displaying user's first name
<programlisting>
1.2 +93 -34 xmldocs/refs/version.tag
rev 1.2, prev_rev 1.1
Index: version.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/version.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- version.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ version.tag 14 Sep 2005 23:10:30 -0000 1.2
@@ -1,7 +1,30 @@
+__NAME__ purpose
+print all sorts of Interchange-related system information
+__END__
+
__NAME__ synopsis
<row>
<entry>
+ extended
+ </entry>
+ <entry>
+ Yes
+ </entry>
+ <entry>
+ <!-- REQ -->
+ </entry>
+ <entry>
+ 0
+ </entry>
+ <entry>
+ Print extended version report?
+ </entry>
+
+</row>
+<row>
+
+ <entry>
joiner
</entry>
<entry>
@@ -11,10 +34,10 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ <literal><br></literal>
</entry>
<entry>
- <!-- DSC -->
+ Record/line separator.
</entry>
</row>
@@ -30,10 +53,10 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ 0
</entry>
<entry>
- <!-- DSC -->
+ Print location of the global (Interchange) error file?
</entry>
</row>
@@ -49,10 +72,11 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ 0
</entry>
<entry>
- <!-- DSC -->
+ Print location of the local (catalog) error file? (The filename is
+ provided as a hyperlink).
</entry>
</row>
@@ -68,10 +92,11 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ 0
</entry>
<entry>
- <!-- DSC -->
+ Print &glos-environment; variable names? (the environment variables specified
+ in &conf-Environment;).
</entry>
</row>
@@ -87,10 +112,10 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ 0
</entry>
<entry>
- <!-- DSC -->
+ Print &conf-SafeUntrap; value?
</entry>
</row>
@@ -106,10 +131,10 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ 0
</entry>
<entry>
- <!-- DSC -->
+ Print child process PID?
</entry>
</row>
@@ -128,7 +153,7 @@
<!-- DFL -->
</entry>
<entry>
- <!-- DSC -->
+ Test for availability of the specified &glos-PERL; module.
</entry>
</row>
@@ -144,10 +169,10 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ 0
</entry>
<entry>
- <!-- DSC -->
+ Print parent PID?
</entry>
</row>
@@ -163,10 +188,10 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ 0
</entry>
<entry>
- <!-- DSC -->
+ Print Interchange &glos-ic-run-mode;?
</entry>
</row>
@@ -182,10 +207,10 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ 0
</entry>
<entry>
- <!-- DSC -->
+ Print &IC; process username and numerical ID?
</entry>
</row>
@@ -201,10 +226,11 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ 0
</entry>
<entry>
- <!-- DSC -->
+ Print &glos-locale; information? (Available locale codes
+ and language names)
</entry>
</row>
@@ -220,10 +246,10 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ 0
</entry>
<entry>
- <!-- DSC -->
+ Print &PERL; information? (Perl version and the location of the Perl binary)
</entry>
</row>
@@ -239,10 +265,11 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ 0
</entry>
<entry>
- <!-- DSC -->
+ Print &PERL; config information? (output of the
+ <function>Config::myconfig()</function> function)
</entry>
</row>
@@ -258,17 +285,17 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ 0
</entry>
<entry>
- <!-- DSC -->
+ Print hostname?
</entry>
</row>
<row>
<entry>
- db
+ modules
</entry>
<entry>
<!-- POS -->
@@ -277,17 +304,19 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ 0
</entry>
<entry>
- <!-- DSC -->
+ Print modules information? (List of &IC;-related modules found and
+ their installed versions. For optional modules, print why one would
+ want to have them).
</entry>
</row>
<row>
<entry>
- modules
+ db
</entry>
<entry>
<!-- POS -->
@@ -296,13 +325,43 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ 1, if none of the above options were set
</entry>
<entry>
- <!-- DSC -->
+ Print database information?
</entry>
</row>
&ROW_INTERPOLATE_0;
&ROW_REPARSE_1;
-__END__
\ No newline at end of file
+__END__
+
+__NAME__ description
+The tag produces all sorts of system information that is in some relation
+to &IC;.
+__END__
+
+__NAME__ example: Invoking the tag with the full set of options
+<programlisting>
+[version
+ extended=1
+ global_error=1
+ local_error=1
+ env=1
+ safe=1
+ pid=1
+ child_pid=1
+ mode=1
+ uid=1
+ global_locale_options=1
+ perl=1
+ perl_config=1
+ hostname=1
+ db=1
+ modules=1
+ modtest=DBI
+]
+</programlisting>
+__END__
+
+
1.2 +3 -0 xmldocs/refs/with.tag
rev 1.2, prev_rev 1.1
Index: with.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/with.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- with.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ with.tag 14 Sep 2005 23:10:30 -0000 1.2
@@ -0,0 +1,3 @@
+__NAME__ purpose
+(obsolete)
+__END__
1.2 +137 -10 xmldocs/refs/xfer-catalog.tag
rev 1.2, prev_rev 1.1
Index: xfer-catalog.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/xfer-catalog.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- xfer-catalog.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ xfer-catalog.tag 14 Sep 2005 23:10:30 -0000 1.2
@@ -1,14 +1,18 @@
+__NAME__ purpose
+conveniently package the catalog for backup or transfer purposes
+__END__
+
__NAME__ synopsis
<row>
<entry>
- backup_old
+ file
</entry>
<entry>
- <!-- POS -->
+ Yes
</entry>
<entry>
- <!-- REQ -->
+ <!-- TODO is it required? -->
</entry>
<entry>
<!-- DFL -->
@@ -21,7 +25,7 @@
<row>
<entry>
- show_error
+ backup_old
</entry>
<entry>
<!-- POS -->
@@ -30,17 +34,18 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ 0
</entry>
<entry>
- <!-- DSC -->
+ Save existing, old backup by renaming it to
+ <literal>xfer.backup.<replaceable>DATE</replaceable></literal>?
</entry>
</row>
<row>
<entry>
- keep_together
+ show_error
</entry>
<entry>
<!-- POS -->
@@ -52,14 +57,14 @@
<!-- DFL -->
</entry>
<entry>
- <!-- DSC -->
+ Return eventual error to the catalog page?
</entry>
</row>
<row>
<entry>
- "keep_$_"
+ keep_together
</entry>
<entry>
<!-- POS -->
@@ -172,4 +177,126 @@
</row>
&ROW_INTERPOLATE_0;
&ROW_REPARSE_1;
-__END__
\ No newline at end of file
+__END__
+
+
+__NAME__ description
+The tag implements a more or less complete "catalog transfer" facility.
+It can come handy to backup the catalog or prepare it for deployment at
+another place.
+</para><para>
+The steps include:
+<itemizedlist>
+ <listitem><para>
+ Exporting non-&MYSQL; and non-&PGSQL; databases to text files
+ </para></listitem>
+ <listitem><para>
+ Dumping MySQL and PostgreSQL &glos-databases; with their native tools
+ (usually <command>mysqldump</command> and <command>pg_dump</command>
+ </para></listitem>
+ <listitem><para>
+ Building &glos-tarball; image, optionally saving temporary files
+ and user sessions.
+ </para></listitem>
+ <listitem><para>
+ Creating a restore script
+ </para></listitem>
+</itemizedlist>
+</para><para>
+The restore script activities include:
+<itemizedlist>
+ <listitem><para>
+ Creating <filename>site.txt</filename> variable database containing the new
+ settings for <varname>SERVER_NAME</varname>, <varname>CGI_URL</varname>,
+ <varname>DOCROOT</varname>, etc.
+ </para></listitem>
+ <listitem><para>
+ Restoring &glos-SQL; dump files, optionally creating the databases
+ </para></listitem>
+ <listitem><para>
+ Copying over exported text databases
+ </para></listitem>
+ <listitem><para>
+ Creating the image directory and copying images to it, and symlinking
+ the target directory to the catalog directory
+ </para></listitem>
+ <listitem><para>
+ Optionally compiling and copying a &glos-link-program;.
+ </para></listitem>
+ <listitem><para>
+ Optionally adding the <literal>Catalog</literal> line to &gcf;.
+ </para></listitem>
+</itemizedlist>
+__END__
+
+
+
+__NAME__ example: Triggering catalog backup, or transfer
+<programlisting><![CDATA[
+[calc]
+
+ my $old = $Scratch->{xfer_catname} = $Config->{CatalogName};
+ return if $CGI->{do_xfer};
+ my $new = $CGI->{rename};
+ return unless $old and $new;
+
+ $new =~ s/[^-\w]+//g;
+
+ for(qw/
+ SERVER_NAME
+ SECURE_SERVER
+ CGI_URL
+ IMAGE_DIR
+ SQLDSN
+ SQLUSER
+ SQLPASS
+ DOCROOT
+ ORDERS_TO
+ SAMPLEHTML
+ SAMPLEURL
+ IC_DIR
+ CGI_DIR
+ CGIWRAP
+ LINKMODE
+ LINKHOST
+ LINKPORT
+ /)
+ {
+ my $val = $Variable->{$_};
+ $val =~ s/$old\b/$new/g;
+ $CGI->{$_} = $val;
+ }
+ return;
+[/calc]
+
+[if cgi do_xfer] [tmp xfer_success][xfer-catalog][/tmp] [/if]
+]]></programlisting>
+__END__
+
+__NAME__ example: Offering the created tarball for download
+<programlisting><![CDATA[
+[if scratch xfer_success]
+ Catalog output successfully.
+[/if]
+
+[if type=file term="[scratch xfer_catname].tar.gz"]
+
+ <p>
+ [calc]
+ $Scratch->{mv_deliver} .= " $Scratch->{xfer_catname}.tar.gz" ; return;
+ [/calc]
+
+ [page add_dot_html=0 href="ui/[scratch xfer_catname].tar.gz"
+ form="
+ mv_data_file=[scratch xfer_catname].tar.gz
+ mv_content_type=application/x-gzip
+ mv_todo=deliver
+ "]
+ [L]Download transfer file[/L]
+ ([file-info name="[scratch xfer_catname].tar.gz"])</a>
+ </p>
+
+[/if]
+]]></programlisting>
+__END__
+
More information about the docs
mailing list