[docs] xmldocs - docelic modified 9 files
docs at icdevgroup.org
docs at icdevgroup.org
Wed Sep 7 12:29:16 EDT 2005
User: docelic
Date: 2005-09-07 16:29:16 GMT
Modified: bin refs-autogen stattree
Modified: guides index.xml upgrade.xml
Modified: howtos daemon-control
Modified: refs liven_urls.filter time.tag unlink_file.tag
Modified: usertrack.tag
Log:
- bin/*: minor changes, mostly comment updates/clarification
- guides/index.html: put Multi-HTML always as first link (as per
preview aftermath ;)
- refs/*: three new tags documented, plus updates
Revision Changes Path
1.95 +19 -13 xmldocs/bin/refs-autogen
rev 1.95, prev_rev 1.94
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.94
retrieving revision 1.95
diff -u -r1.94 -r1.95
--- refs-autogen 3 Sep 2005 14:01:23 -0000 1.94
+++ refs-autogen 7 Sep 2005 16:29:16 -0000 1.95
@@ -143,6 +143,7 @@
# Support preamble texts
my %preamble = (
# Dude, this is 15 pages of text in place where there shouldn't be any really
+ # so replace it with a link to another page.
#tag => scalar readfile('glossary/ITL'),
tag => "For a complete introduction to the ⁣ Tag Language and " .
"the supported syntax, please see the &glos-ITL; glossary entry.",
@@ -150,7 +151,8 @@
"the supported syntax, please see the &glos-configuration; glossary entry.",
globvar => "",
catvar => "",
- pragma => "",
+ pragma => "For a complete introduction to ⁣ pragmas, " .
+ "please see the &glos-pragma; glossary entry.",
filter => "For a complete introduction to ⁣ filters, " .
"please see the &glos-filter; glossary entry.",
var => "For a complete introduction to ⁣ variables, " .
@@ -174,7 +176,7 @@
open FILE_ENTITIES, "> $fileentitiespath" or
die "Can't open '$fileentitiespath' ($!)\n";
-while ( $path = shift @paths) { # For each version specified
+while ( $path = shift @paths) { # Now, for each IC version specified
$dumppath = $path;
$i{ver} = $dumppath;
$dumpdir = "$dumppath/";
@@ -188,20 +190,20 @@
push @parsed_versions, $hash{version};
-
+ #########################################################################
# Ok, before doing the REAL work, let's dump file entities. We will create
# file $fileentitiespath, and dump entities to it. That file will contain
# entities from ALL IC versions.
# For non-last version, only one entity will be generated. Example:
- # FILE: IC4.8/README
- # ENTITY: &cvsfile4.8-README;
- # LOCATION: SITE/cgi-bin/cvsweb/interchange/?only_with_tag=STABLE_4_8-root
+ # FILE: IC4.8/README ----> ENTITY: &cvsfile4.8-README;
+ # (LOCATION: SITE/cgi-bin/cvsweb/interchange/?only_with_tag=STABLE_4_8-root)
+ #
# However, entities for last version will, in addition to above,
- # get a default entity (like &cvsfile-README;), and it will point to
- # some particular version or cvs-head.
+ # get a default entity (like &cvsfile-README;) where no version is specified
+ # in the entity, and it will point to some particular file in CVS-HEAD.
# First derive IC series_ (in format X_Y) and series (in format X.Y),
- # and cvs tag for non-cvs-head. (If we're in cvs-head, we don't do this
+ # and cvs tag for non-cvs-head. (If we're in cvs-head, we don't make cvs tag
# since cvs-head has no special tag).
unless ( $i{ver} eq 'cvs-head' ) {
( $i{series_} = $i{ver} ) =~ s/\./_/; $i{series_} =~ s/\..*//;
@@ -212,8 +214,9 @@
$i{series} = '';
$i{cvstag} = '';
}
-
- # Load in list of files. It's prepared for us by bin/stattree.
+ # Now load in list of files for which to generate entities.
+ # The list is already prepared for us by bin/stattree (a MANIFEST file,
+ # basically).
open IN, "< tmp/$i{ver}.MANIFEST" or
die "Can't rdopen 'tmp/$i{ver}.MANIFEST' ($!).\n" .
"Run 'make clean-cache cache'?\n";
@@ -252,13 +255,16 @@
$MANIFEST[$i] . qq{</ulink>"} . ">\n";
}
}
+ # File entities dumped....
+ #########################################################################
+
- # Ok, real work begins.
+ # Ok, now we're done with the by-the-way tasks, and the real work begins.
# Outer loop: $gkey: symbol types (pragmas, globvars, ...)
- # Inner loop (~15 lines below): $key: actual symbols
+ # Inner loop (~25 lines below): $key, actual symbols from symbol groups
while ( my ($gkey,$gval) = each %{ $hash{symbols} } ) {
# Unfortunately - $specific_only is of limited use. If you use it,
# the script won't catch symbol "migrations" - that is, for example,
1.46 +7 -6 xmldocs/bin/stattree
rev 1.46, prev_rev 1.45
Index: stattree
===================================================================
RCS file: /var/cvs/xmldocs/bin/stattree,v
retrieving revision 1.45
retrieving revision 1.46
diff -u -r1.45 -r1.46
--- stattree 4 Sep 2005 22:02:32 -0000 1.45
+++ stattree 7 Sep 2005 16:29:16 -0000 1.46
@@ -96,7 +96,7 @@
@ARGV == 1 or die "Usage: $0 path[/] \n";
# $path is the directory to process, $dumppath is relocated name, say
-# sources/cvs-head becomes cvs-head/cache/.cache.bin
+# sources/cvs-head becomes cache/cvs-head/.cache.bin
my $path = shift;
( my $dumppath = $path ) =~ s#.+?/##;
my $dumpdir = $dumppath; # Directory to dump to, without file name
@@ -370,7 +370,7 @@
next unless $_l =~ /^usertag\s/i;
my @lis = split /\s+/, $_l;
- # Remove "Usertag" which is first in the list. (Safety check
+ # Remove "Usertag" which is first word in every line. (Safety check
# done just above so we can go ahead unconditionally)
shift @lis;
@@ -381,12 +381,13 @@
my $tn = shift @lis;
my $tagopt = lc(shift @lis);
- # Check if there's a sub defined for this $tagopt.
+ # Check if there's a sub defined for this $tagopt (if it is, it
+ # would be above in %tagCanon hash).
$tagCanon{lc $tagopt} and &{ $tagCanon{lc $tagopt} }(\%c);
- next if $tagopt =~ /^documentation$/; # Docs sections are ignored
- # in a way that the dony begin with ^UserTag so they're completely
- # disregarded.
+ next if $tagopt =~ /^documentation$/; # Docs inside this section
+ # are ignored by a "side-effect": namely, all lines not matching
+ # /^UserTag/ are ignored...
#
1.2 +15 -12 xmldocs/guides/index.xml
rev 1.2, prev_rev 1.1
Index: index.xml
===================================================================
RCS file: /var/cvs/xmldocs/guides/index.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- index.xml 1 Sep 2005 23:12:38 -0000 1.1
+++ index.xml 7 Sep 2005 16:29:16 -0000 1.2
@@ -12,6 +12,9 @@
<copyright>
<year>2005</year>
<holder>Davor Ocelic</holder>
+</copyright>
+<copyright>
+ <year>2005</year>
<holder>Interchange Development Group</holder>
</copyright>
@@ -70,16 +73,16 @@
<emphasis role='bold'>
Installation/Configuration FAQ
</emphasis><sbr/>
- <ulink url="install.html">HTML</ulink> |
- <ulink url="install/index.html">Multi-HTML</ulink>
+ <ulink url="install/index.html">Multi-HTML</ulink> |
+ <ulink url="install.html">HTML</ulink>
</entry>
<entry>
<emphasis role='bold'>
Catalog Tutorial
</emphasis><sbr/>
- <ulink url="iccattut.html">HTML</ulink> |
- <ulink url="iccattut/index.html">Multi-HTML</ulink>
+ <ulink url="iccattut/index.html">Multi-HTML</ulink> |
+ <ulink url="iccattut.html">HTML</ulink>
</entry>
</row>
@@ -98,16 +101,16 @@
<emphasis role='bold'>
HOWTOs Collection
</emphasis><sbr/>
- <ulink url="howtos.html">HTML</ulink> |
- <ulink url="howtos/index.html">Multi-HTML</ulink>
+ <ulink url="howtos/index.html">Multi-HTML</ulink> |
+ <ulink url="howtos.html">HTML</ulink>
</entry>
<entry>
<emphasis role='bold'>
Programming Style
</emphasis><sbr/>
- <ulink url="programming-style.html">HTML</ulink> |
- <ulink url="programming-style/index.html">Multi-HTML</ulink>
+ <ulink url="programming-style/index.html">Multi-HTML</ulink> |
+ <ulink url="programming-style.html">HTML</ulink>
</entry>
</row>
@@ -126,16 +129,16 @@
<emphasis role='bold'>
Optimization/Efficiency FAQ
</emphasis><sbr/>
- <ulink url="optimization.html">HTML</ulink> |
- <ulink url="optimization/index.html">Multi-HTML</ulink>
+ <ulink url="optimization/index.html">Multi-HTML</ulink> |
+ <ulink url="optimization.html">HTML</ulink>
</entry>
<entry>
<emphasis role='bold'>
Upgrade Guide
</emphasis><sbr/>
- <ulink url="upgrade.html">HTML</ulink> |
- <ulink url="upgrade/index.html">Multi-HTML</ulink>
+ <ulink url="upgrade/index.html">Multi-HTML</ulink> |
+ <ulink url="upgrade.html">HTML</ulink>
</entry>
</row>
1.3 +3 -0 xmldocs/guides/upgrade.xml
rev 1.3, prev_rev 1.2
Index: upgrade.xml
===================================================================
RCS file: /var/cvs/xmldocs/guides/upgrade.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- upgrade.xml 24 May 2005 21:42:18 -0000 1.2
+++ upgrade.xml 7 Sep 2005 16:29:16 -0000 1.3
@@ -59,9 +59,12 @@
while upgrading to Interchange 5.0 and beyond, please review
WHATSNEW entries.
</para><para>
+ <emphasis role='bold'>
This Guide will be slowly losing on relevance, and users running
Interchange 5.0 or later should monitor WHATSNEW entries for
upgrade information.
+ <!-- TODO link to whatsnew -->
+ </emphasis>
</para>
</abstract>
1.4 +16 -1 xmldocs/howtos/daemon-control
rev 1.4, prev_rev 1.3
Index: daemon-control
===================================================================
RCS file: /var/cvs/xmldocs/howtos/daemon-control,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- daemon-control 15 Jun 2005 10:30:12 -0000 1.3
+++ daemon-control 7 Sep 2005 16:29:16 -0000 1.4
@@ -34,7 +34,7 @@
<sect1 id='daemon-control_introduction'>
<title>Introduction</title>
<para>
- HOW-TO version: $Id: daemon-control,v 1.3 2005/06/15 10:30:12 docelic Exp $
+ HOW-TO version: $Id: daemon-control,v 1.4 2005/09/07 16:29:16 docelic Exp $
</para>
<para>
Knowing how to manage the Interchange daemon is one of the very basic
@@ -90,6 +90,21 @@
</para>
<!-- TODO mention kill, pkill, killall, pidfile -->
+ <!--
+\NOTE: You can adjust time globally for an Interchange installation by
+setting the $ENV{TZ} variable on many systems. Set TZ in your environment
+and then restart Interchange:
+
+> ## bash/ksh/sh
+> TZ=PST7PDT; export TZ
+> interchange -restart
+>
+> ## csh/tcsh
+> setenv TZ PST7PDT
+> interchange -restart
+
+On most modern UNIX systems, all times will now be in the PST zone.
+-->
</sect1>
1.3 +2 -5 xmldocs/refs/liven_urls.filter
rev 1.3, prev_rev 1.2
Index: liven_urls.filter
===================================================================
RCS file: /var/cvs/xmldocs/refs/liven_urls.filter,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- liven_urls.filter 20 Aug 2005 13:16:28 -0000 1.2
+++ liven_urls.filter 7 Sep 2005 16:29:16 -0000 1.3
@@ -10,7 +10,7 @@
__NAME__ description
The filter searches the input for all kinds of links, and wraps them
-into the standard &glos-HTML; <a href=><> package.
+into the standard &glos-HTML; <a href=></a> package.
</para><para>
The filter can recognize all sorts of URLs and to a great detail.
__END__
@@ -26,7 +26,7 @@
<ulink url="http://ucan.foad.org/~abigail/Perl/url2.html">Regex for URLs</ulink>.
</para><para>
To save on processing time, only the most common protocols
-(http, ftp and mailto) are actually enabled in the filter.
+(http/https, ftp and mailto) are actually enabled in the filter.
For the rest of the protocols, you need to uncomment the appropriate
lines in the filter source and restart &IC;.
</para><para>
@@ -64,9 +64,6 @@
mid:960830.1639 at XIson.com/partA.960830.1639 at XIson.com<br/>
[/filter]
]]></programlisting>
-
-If some of the links are not clickable, then the appropriate regular
-expressions have been deactivated in the filter source.
__END__
1.2 +151 -17 xmldocs/refs/time.tag
rev 1.2, prev_rev 1.1
Index: time.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/time.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- time.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ time.tag 7 Sep 2005 16:29:16 -0000 1.2
@@ -1,8 +1,12 @@
+__NAME__ purpose
+display current date and time according to POSIX strftime format specifier
+__END__
+
__NAME__ synopsis
<row>
<entry>
- tz
+ locale
</entry>
<entry>
<!-- POS -->
@@ -14,14 +18,15 @@
<!-- DFL -->
</entry>
<entry>
- <!-- DSC -->
+ Format date and time according to the named &glos-locale;
+ (assuming that the locale is available on your system).
</entry>
</row>
<row>
<entry>
- time
+ tz
</entry>
<entry>
<!-- POS -->
@@ -33,14 +38,19 @@
<!-- DFL -->
</entry>
<entry>
- <!-- DSC -->
+ Specify the timezone.
+ Note that the first alphabetical string is the zone name to be used
+ when not under daylight-savings time. The following digit is the number
+ of hours displacement from GMT, and the second alphabetical string is
+ the zone name when in daylight savings time. (This may not work on all
+ operating systems.)
</entry>
</row>
<row>
<entry>
- sortable
+ time
</entry>
<entry>
<!-- POS -->
@@ -52,13 +62,38 @@
<!-- DFL -->
</entry>
<entry>
- <!-- DSC -->
+ Specify the date/time manually, instead of letting &IC; call
+ Perl <function>time()</function> function.
</entry>
</row>
<row>
<entry>
+ sortable
+ </entry>
+ <entry>
+ <!-- POS -->
+ </entry>
+ <entry>
+ <!-- REQ -->
+ </entry>
+ <entry>
+ 0
+ </entry>
+ <entry>
+ Display date in "sortable" format? Sortable format is predefined
+ <literal>format=</literal> string that displays the date in
+ "<literal>
+ <replaceable>YYYY</replaceable>/
+ <replaceable>MM</replaceable>/
+ <replaceable>DD</replaceable>
+ </literal>
+ </entry>" style.
+</row>
+<row>
+
+ <entry>
adjust
</entry>
<entry>
@@ -68,10 +103,15 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
</entry>
<entry>
- <!-- DSC -->
+ For the display purpose, adjust the time for the specified
+ value.
+ In most cases, the value will represent hours. If the
+ value ends in <literal>0</literal> and contains three or
+ more digits, then it is assumed to be in timezone format.
+ The offset can also be specified using &glos-interval; format.
+ See <xref linkend="time_examples"/> for clarification.
</entry>
</row>
@@ -87,17 +127,20 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ 0
</entry>
<entry>
- <!-- DSC -->
+ Force the <literal>adjust=</literal> argument to always
+ represent hours.
</entry>
</row>
<row>
<entry>
- format
+ <group choice='opt'>
+ <arg>format</arg><arg>fmt</arg>
+ </group>
</entry>
<entry>
<!-- POS -->
@@ -109,7 +152,8 @@
<!-- DFL -->
</entry>
<entry>
- <!-- DSC -->
+ POSIX strftime format specifier. See <command>man strftime</command>
+ for details.
</entry>
</row>
@@ -144,10 +188,10 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ 0
</entry>
<entry>
- <!-- DSC -->
+ Display GMT (UTC) time?
</entry>
</row>
@@ -163,13 +207,103 @@
<!-- REQ -->
</entry>
<entry>
- <!-- DFL -->
+ 0
</entry>
<entry>
- <!-- DSC -->
+ Strip leading zeros from numbers?
</entry>
</row>
&ROW_INTERPOLATE_0;
&ROW_REPARSE_1;
-__END__
\ No newline at end of file
+__END__
+
+
+__NAME__ description
+The tag displays the current date and time, in a format specified using
+POSIX strftime notation.
+__END__
+
+
+__NAME__ notes
+In all <literal>adjust=</literal> manipulations, the offset will just be
+applied at the end (the timezone will not be changed for the invocation
+of time function). This means you shouldn't use any format that uses
+timezone information. For the timezone to enter calculations, either use
+<literal>tz=</literal>, or manage the system yourself.
+</para><para>
+The timezone can be set globally for the &IC; installation by defining
+the <envar>TZ</envar> environment variable and restarting Interchange.
+__END__
+
+
+__NAME__ example: Basic example
+<programlisting>
+[time]%am %B %d, %Y[/time]
+</programlisting>
+This tag would return a date such as
+<literal>Sunday, September 4, 2005</literal>.
+__END__
+
+
+__NAME__ example: Specifying adjust= attribute in number of hours
+<programlisting>
+[time adjust="-3"]%c[/time]
+</programlisting>
+With a base date of <literal>Mon 01 Jan 2001 11:29:03 AM EST</literal>,
+this tag would display <literal>Mon 01 Jan 2001 08:29:03 AM EST</literal>.
+__END__
+
+
+__NAME__ example: Specifying adjust= attribute in timezone format
+<programlisting><![CDATA[
+[time]%c[/time]
+[time adjust="-330"]%c[/time]
+[time adjust="-300"]%c[/time]
+]]></programlisting>
+With a base date of <literal>Mon 01 Jan 2001 11:29:03 AM EST</literal>,
+this tag would display second date offset by 3 hours and 30 minutes,
+and the third date offset by 3 hours.
+<screen>
+Mon 01 Jan 2001 11:29:03 AM EST
+Mon 01 Jan 2001 07:59:03 AM EST
+Mon 01 Jan 2001 08:29:03 AM EST
+</screen>
+__END__
+
+__NAME__ example: Specifying adjust= attribute in interval format
+<programlisting><![CDATA[
+[time adjust="2 days"]%c[/time]
+]]></programlisting>
+__END__
+
+__NAME__ example: Displaying locale-specific date
+<programlisting><![CDATA[
+[time locale=en_US]%B %d, %Y[/time]
+[time locale=fr_FR]%B %d, %Y[/time]
+]]></programlisting>
+would result in
+<screen>
+January 01, 2001
+janvier 01, 2001
+</screen>
+__END__
+
+
+
+__NAME__ example: Specifying tz= attribute
+<programlisting><![CDATA[
+[time tz=GMT0]
+[time tz=CST6CDT]
+[time tz=PST8PDT]
+]]></programlisting>
+would result in
+<screen>
+Mon 01 Jan 2001 04:43:02 PM GMT
+Mon 01 Jan 2001 10:43:02 AM CST
+Mon 01 Jan 2001 08:43:02 AM PST
+</screen>
+__END__
+
+
+
1.2 +65 -0 xmldocs/refs/unlink_file.tag
rev 1.2, prev_rev 1.1
Index: unlink_file.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/unlink_file.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- unlink_file.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ unlink_file.tag 7 Sep 2005 16:29:16 -0000 1.2
@@ -0,0 +1,65 @@
+__NAME__ purpose
+safely delete a file within catalog root directory
+__END__
+
+
+__NAME__ see also
+write-relative-file
+__END__
+
+
+__NAME__ synopsis
+<row>
+ <entry>
+ name
+ </entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ <entry></entry>
+ <entry>File name to delete</entry>
+</row>
+<row>
+ <entry>
+ prefix
+ </entry>
+ <entry>Yes</entry>
+ <entry></entry>
+ <entry><literal>tmp/</literal></entry>
+ <entry>Prefix that the filename must match (a safety measure)</entry>
+</row>
+&ROW_INTERPOLATE_0;
+&ROW_REPARSE_1;
+__END__
+
+
+__NAME__ description
+The tag safely deletes a file from the catalog root directory (&glos-CATROOT;).
+</para><para>
+The beginning of the filename must match the <literal>prefix=</literal> option
+for the deletion to succeed.
+</para><para>
+The filename can not start with a <literal>/</literal> nor <literal>../</literal>.
+__END__
+
+
+__NAME__ example: create and delete file "tmp/testfile"
+<programlisting>
+[tmp]
+
+[write-relative-file tmp/testfile]
+ Hello, World!
+[/write-relative-file]
+
+[unlink-file tmp/testfile]
+
+[/tmp]
+</programlisting>
+The &tag-tmp; tag is only used to hide output values from the two contained tags.
+__END__
+
+
+__NAME__ example: delete file "logs/tmplog"
+[tmp] [unlink-file name="logs/tmplog" prefix="logs/"] [/tmp]
+__END__
+
+
1.2 +64 -0 xmldocs/refs/usertrack.tag
rev 1.2, prev_rev 1.1
Index: usertrack.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/usertrack.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- usertrack.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ usertrack.tag 7 Sep 2005 16:29:16 -0000 1.2
@@ -0,0 +1,64 @@
+__NAME__ purpose
+append usertrack entry with arbitrary key=value pair
+__END__
+
+
+__NAME__ see also
+TrackFile
+__END__
+
+__NAME__ synopsis
+<row>
+ <entry>
+ tag
+ </entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ <entry></entry>
+ <entry>Key name</entry>
+</row>
+<row>
+ <entry>
+ value
+ </entry>
+ <entry>Yes</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>Key value</entry>
+</row>
+&ROW_INTERPOLATE_0;
+&ROW_REPARSE_1;
+__END__
+
+
+__NAME__ description
+The tag is used to append content to the line that will be inserted into
+user &glos-tracking; log.
+</para><para>
+Key/value pairs are added to the line in "GET"-like style.
+See <xref linkend="usertrack_examples"/>.
+__END__
+
+
+__NAME__ notes
+User &glos-tracking; must be enabled for this tag to produce any noticeable effect.
+</para><para>
+&tag-usertrack; does not work on &glos-special; pages.
+__END__
+
+__NAME__ example: Basic example
+Put each of the two lines anywhere on a page:
+<programlisting>
+[usertrack HELLO WORLD]
+
+[usertrack tag=test_var value=test_value]
+</programlisting>
+__END__
+
+__NAME__ example: Recording the number of cart items each time the user visits the index page
+Put the following in <filename>index.html</filename>:
+<programlisting>
+[usertrack tag=nitems value="[nitems]"]
+</programlisting>
+__END__
+
More information about the docs
mailing list