[interchange-docs] xmldocs - docelic modified 11 files
docs at icdevgroup.org
docs at icdevgroup.org
Thu Jul 27 16:48:16 EDT 2006
User: docelic
Date: 2006-07-27 20:48:15 GMT
Modified: . TODO
Modified: bin refs-autogen
Modified: docbook literals.ent
Modified: glossary ITL profile session
Modified: guides install.xml
Modified: refs SocketPerms accessories.tag index.tag loop.tag
Log:
- TODO: Note about fixing/updating AdminUser docs
- bin/refs-autogen: use __FILENAME__ instead of __FNAME__
- docbook/literals.ent: Add MOD_PERL entity
- glossary/ITL: describe backtick notation
- glossary/{profile<section>ession}: added notes for later proper inclusion
- guides/install.xml: add makecat notes
- refs/SocketPerms: mention 0666 mode
- refs/*: notes for later inclusion
Revision Changes Path
1.90 +1 -0 xmldocs/TODO
rev 1.90, prev_rev 1.89
Index: TODO
===================================================================
RCS file: /var/cvs/xmldocs/TODO,v
retrieving revision 1.89
retrieving revision 1.90
diff -u -r1.89 -r1.90
--- TODO 14 Jul 2006 10:39:03 -0000 1.89
+++ TODO 27 Jul 2006 20:48:14 -0000 1.90
@@ -3,6 +3,7 @@
- Change -latest to version number in tarball download
- bin/whatsnew-update didn't pick up User: from messages
- some <am> is visible in feature glossary entry
+- fix/update AdminUser docs
- aliases like DataDir/DefaultTables are not documented
Outstanding:
1.111 +4 -3 xmldocs/bin/refs-autogen
rev 1.111, prev_rev 1.110
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.110
retrieving revision 1.111
diff -u -r1.110 -r1.111
--- refs-autogen 9 Jul 2006 14:08:19 -0000 1.110
+++ refs-autogen 27 Jul 2006 20:48:14 -0000 1.111
@@ -1089,13 +1089,14 @@
# XXX check if it's empty, then don't update
for my $line (@c) {
- # GLOBAL REPLACE. To ease writing reference pages, __FNAME__
+ # GLOBAL REPLACE. To ease writing reference pages, __FILENAME__
# will expand to name of file. So, if file is refs/CommonAdjust,
- # __FNAME__ will expand to CommonAdjust. XXX this only works
+ # __FILENAME__ will expand to CommonAdjust. XXX this only works
# in one-file method. Not multi-file method, but as said a few
# times above, multi-file is not to be used any more.
( my $_fname = $refpath ) =~ s#.*/##;
- $line =~ s/__FNAME__/$_fname/;
+ $_fname =~ s/\..+$//;
+ $line =~ s/__FILENAME__/$_fname/;
# Here we support format of this kind:
# __NAME__ section name: section title
1.38 +1 -0 xmldocs/docbook/literals.ent
rev 1.38, prev_rev 1.37
Index: literals.ent
===================================================================
RCS file: /var/cvs/xmldocs/docbook/literals.ent,v
retrieving revision 1.37
retrieving revision 1.38
diff -u -r1.37 -r1.38
--- literals.ent 5 Jul 2006 14:03:30 -0000 1.37
+++ literals.ent 27 Jul 2006 20:48:14 -0000 1.38
@@ -38,6 +38,7 @@
<!ENTITY SWISH-E "<ulink url='http://www.swish-e.org/'>Swish-e</ulink>">
<!ENTITY GPG "<ulink url='http://www.gnupg.org/'>GPG</ulink>">
<!ENTITY WIKIPEDIA "<ulink url='http://www.wikipedia.org/'>Wikipedia</ulink>">
+<!ENTITY MOD_PERL "<ulink url='http://perl.apache.org/'>mod_perl</ulink>">
1.18 +40 -2 xmldocs/glossary/ITL
rev 1.18, prev_rev 1.17
Index: ITL
===================================================================
RCS file: /var/cvs/xmldocs/glossary/ITL,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -r1.17 -r1.18
--- ITL 18 Jun 2006 22:36:20 -0000 1.17
+++ ITL 27 Jul 2006 20:48:15 -0000 1.18
@@ -335,6 +335,8 @@
<section>
<title>Accessing Perl from ITL</title>
+<section>
+ <title>Perl-related ITL tags</title>
<para>
Among ITL tags, &tag-perl;, &tag-calc;, &tag-calcn; and &tag-mvasp;
are used obtain direct access to the &PERL; language in &IC; pages.
@@ -419,6 +421,44 @@
</para>
</section>
+<section>
+<title>Perl-related ITL syntax</title>
+<para>
+ITL also supports a special type of quoting, using backticks
+(<literal>`</literal>), where the content is evaluated by &PERL;
+and then passed as the usual argument value.
+</para><para>
+Using this backtick notation, you can conveniently perform quick, in-place
+&PERL; evaluation of an argument, or pass complex data structures as
+attribute values.
+</para>
+<para>
+<emphasis role='bold'>Performing quick, in-place argument interpolation</emphasis>:
+<programlisting>
+[cgi name=Magic_Number hide=1 set=`2 + 3 + $CGI->{magic}`]
+
+The magic number is: [cgi Magic_Number]
+</programlisting>
+</para>
+<para>
+<emphasis role='bold'>Passing complex data structures as argument values</emphasis>:
+<programlisting>
+[cgi name=Magic_Structure hide=1 set=`{ key1 => 'val1', key2 => 'val2' }`]
+</programlisting>
+As you see, this notation (and implied functionality) is completely valid
+and possible. It is then just up to the called tag to handle attribute value
+appropriately.
+</para>
+<note>
+<para>
+<emphasis role='bold'>It is only possible to use the backticks notation with
+named parameters!</emphasis>
+</para>
+</note>
+<!-- TODO what happens with ITL code inside backticks ? -->
+</section>
+
+</section>
<section>
<title>Universal Attributes</title>
@@ -648,8 +688,6 @@
]]></programlisting>
</para>
-
-<!-- TODO backticks -->
</section>
1.7 +25 -0 xmldocs/glossary/profile
rev 1.7, prev_rev 1.6
Index: profile
===================================================================
RCS file: /var/cvs/xmldocs/glossary/profile,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- profile 16 Dec 2005 13:24:44 -0000 1.6
+++ profile 27 Jul 2006 20:48:15 -0000 1.7
@@ -196,5 +196,30 @@
[page scan se=Renaissance/mp=dict_search]Renaissance Art</a>
!endblock
+
+ [set checkout]
+ name=required Please enter your name.
+ address=required No address entered.
+ [/set] 21,1 0%
+ <INPUT TYPE=hidden NAME=mv_order_profile VALUE="checkout">
+
+
+
+.A search profile would be set with:
+
+!block example; listitem=2
+ [set substring_case]
+ mv_substring_match=yes
+ mv_case=yes
+ [/set]
+ <INPUT TYPE=hidden NAME=mv_profile VALUE="substring_case">
+!endblock
+
+.To do the same as C<[set foo]bar[/set]> in embedded Perl:
+
+!block example; listitem=2
+ [calc]$Scratch->{foo} = 'bar'; return;[/calc]
+!endblock 21,1
+
-->
1.6 +22 -0 xmldocs/glossary/session
rev 1.6, prev_rev 1.5
Index: session
===================================================================
RCS file: /var/cvs/xmldocs/glossary/session,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- session 21 Dec 2005 15:39:46 -0000 1.5
+++ session 27 Jul 2006 20:48:15 -0000 1.6
@@ -139,5 +139,27 @@
Interchange will wait until the current transaction is finished before expiring, so this can be done at any time without disabling web access. Any search paging files for the affected session (kept in C<ScratchDir>) will be removed as well.
+In addition, the C<[data ...]> tag can access a number of elements in the Interchange session database:
+
+!block example; listitem=2
+ accesses Accesses within the last 30 seconds
+ arg The argument passed in a [page ...] or [area ...] tag
+ browser The user browser string
+ host Interchange's idea of the host (modified by DomainTail)
+ last_error The last error from the error logging
+ last_url The current Interchange path_info
+ logged_in Whether the user is logged in via UserDB
+ pageCount Number of unique URLs generated
+ prev_url The previous path_info
+ referer HTTP_REFERER string
+ ship_message The last error messages from shipping
+ source Source of original entry to Interchange
+ time Time (seconds since Jan 1, 1970) of last access
+ user The REMOTE_USER string
+ username User name logged in as (UserDB)
+!endblock
+
+
+
-->
1.6 +51 -7 xmldocs/guides/install.xml
rev 1.6, prev_rev 1.5
Index: install.xml
===================================================================
RCS file: /var/cvs/xmldocs/guides/install.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- install.xml 5 Jul 2006 14:03:30 -0000 1.5
+++ install.xml 27 Jul 2006 20:48:15 -0000 1.6
@@ -332,13 +332,25 @@
or want to keep everything under your own control. However, there is the
so-called "&std-catalog;" demo that ships with &IC; — it is extremely
elaborate and feature-rich for someone looking to build an Internet store,
- and it allows custom modifications to be performed on it.
+ and it allows custom modifications to be performed on it. The most common
+ way to create a catalog based on our demo is to run our
+ <command>makecat</command> script.
+ </para><para>
+ Each catalog can be completely independent with different settings and
+ databases, or catalogs can share pages, databases, and session files.
+ This means that several catalogs can share the same information, allowing
+ "virtual malls" (although not directly out-of-the box with makecat or our
+ demo).
</para><para>
Regardless of whether you want to base your own catalogs on our demo or not,
it is strongly suggested to install the demo. It will let you
see whether your Interchange installation is correct, and it will also be
a nice presentation of Interchange features.
- </para><para>
+ </para>
+
+ <section>
+ <title>Setting up a catalog using the makecat script</title>
+ <para>
There is a catalog creation script named <command>makecat</command> available,
that you will use to create catalogs based on catalog templates (and our
demo is, of course, organized as a template).
@@ -351,12 +363,44 @@
The <command>makecat</command> is self-documented. Each question is
accompanyed with an introduction, examples, and a reasonable Unix default.
</para><para>
- Each catalog can be completely independent with different settings and
- databases, or catalogs can share pages, databases, and session files.
- This means that several catalogs can share the same information, allowing
- "virtual malls" (although not directly out-of-the box with makecat or our
- demo).
+ By far the most common problem on the way to installing a working demo,
+ is wrong information given to the <command>makecat</command> program.
+ </para><para>
+ Among the questions that <command>makecat</command> will ask you, there are
+ four quite important ones; the script will need to know:
+ <itemizedlist>
+ <listitem><para>
+ The web server's (or virtual host's) filesystem path to &glos-DocumentRoot;
+ </para></listitem>
+ <listitem><para>
+ The web server's (or virtual host's) web path to your
+ <filename class='directory'>cgi-bin/</filename> directory
+ </para></listitem>
+ <listitem><para>
+ TODO
+ </para></listitem>
+ <listitem><para>
+ TODO
+ </para></listitem>
+ </itemizedlist>
+
+ <para>
+ If you don't get it right the first time, re-run the configuration again,
+ and <emphasis role='bold'>pay close attention to the prompts given</emphasis>.
+ </para>
+ </section>
+
+ <section>
+ <title>Setting up a catalog manually</title>
+ <para>
+ Setting up a catalog manually involves creating the necessary files and
+ directories, compiling the link program, and inserting a &conf-Catalog;
+ line to the global &gcf; configuration file.
+ </para><para>
+ For a complete introduction and even ready-made files to set up a
+ catalog from scratch, see <olink targetdoc='iccattut'/>.
</para>
+ </section>
</sect1>
1.9 +9 -8 xmldocs/refs/SocketPerms
rev 1.9, prev_rev 1.8
Index: SocketPerms
===================================================================
RCS file: /var/cvs/xmldocs/refs/SocketPerms,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- SocketPerms 10 Jul 2006 14:41:10 -0000 1.8
+++ SocketPerms 27 Jul 2006 20:48:15 -0000 1.9
@@ -15,7 +15,7 @@
__NAME__ description
-Specify permissions (&glos-mode;) for the Interchange UNIX-domain socket.
+Specify permissions (&glos-mode;) for the Interchange UNIX-domain socket file.
</para><para>
Prepend a starting <literal>0</literal> to indicate an octal value. The
directive can be overridden from the command line using <literal>interchange
@@ -24,16 +24,17 @@
The default value is <literal>0600</literal>, which allows only programs
running under your &IC; server UID to access the socket.
</para><para>
-Another possible setting is <literal>0666</literal> if other programs needs
-to access the socket file, e.g. Apache2 via mod_perl and Interchange::Link.
-Please note that this setting is insecure, it allows every user on the system
-to communicate through the socket.
+Another possible value is <literal>0666</literal>. This is a bit
+insecure setting, as it allows anyone on the system to access the socket.
+It may come handy, however, if programs such as &APACHE; need to access
+the socket via &MOD_PERL; or our <classname>Interchange::Link</classname>
+module.
__END__
__NAME__ notes
-Although not recommended in practice, it sometimes makes sense to
-set the permissions to <literal>0666</literal> (world-writable) to
-debug problems easier.
+You might want to try the discussed mode, <literal>0666</literal>,
+when your &IC; installation isn't working and you quickly want to find out
+whether it's just socket file permissions problem or something deeper.
__END__
1.2 +17 -1 xmldocs/refs/accessories.tag
rev 1.2, prev_rev 1.1
Index: accessories.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/accessories.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- accessories.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ accessories.tag 27 Jul 2006 20:48:15 -0000 1.2
@@ -115,4 +115,20 @@
</row>
&ROW_INTERPOLATE_0;
&ROW_REPARSE_1;
-__END__
\ No newline at end of file
+__END__
+
+__NAME__ description
+The &tag-__FILENAME__; tag is the "swiss army-knife" tool for choosing or
+displaying &IC;'s product <emphasis>options</emphasis> (also called
+<emphasis>attributes</emphasis>, of which typical examples are size or color).
+</para><para>
+__END__
+
+__NAME__ notes
+The default item options can be set via &conf-UseModifier;.
+</para><para>
+See the &glos-attribute; glossary entry for a complete introduction to item
+options.
+__END__
+
+
1.2 +9 -1 xmldocs/refs/index.tag
rev 1.2, prev_rev 1.1
Index: index.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/index.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- index.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ index.tag 27 Jul 2006 20:48:15 -0000 1.2
@@ -191,4 +191,12 @@
</row>
&ROW_INTERPOLATE_0;
&ROW_REPARSE_1;
-__END__
\ No newline at end of file
+__END__
+
+# Resolve name clash with index.html (this will become index2.html)
+# Not too nice, but :)
+__NAME__ id
+2
+__END__
+
+
1.2 +67 -1 xmldocs/refs/loop.tag
rev 1.2, prev_rev 1.1
Index: loop.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/loop.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- loop.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ loop.tag 27 Jul 2006 20:48:15 -0000 1.2
@@ -381,4 +381,70 @@
</row>
&ROW_INTERPOLATE_0;
&ROW_REPARSE_1;
-__END__
\ No newline at end of file
+__END__
+
+
+
+
+
+ [loop list=|
+ k1 A1 A2 A3
+ k2 B1 B2 B3
+ |]
+ [loop-increment][loop-code]
+ [/loop]
+
+
+H2: loop
+
+Loop lists can be used to construct arbitrary lists based on the contents of a database field, a search or other value (like a fixed list). Loop accepts a C<search> parameter that will do one-click searches on a database table (or file).
+
+To iterate over all keys in a table, use the idiom (C<[loop search="ra=yes/ml=9999"] [/loop]>. C<ra=yes> sets C<mv_return_all>, which means "match everything". C<ml=9999> limits matches to that many records. If the text file for searching an Interchange DBM database is not used, set C<st=db> (mv_searchtype).
+
+When using C<st=db>, returned keys may be affected by C<TableRestrict>. Both can be sorted with C<[sort table:field:mod -start +number]> modifiers. See {{C[jump="icdatabase.html#Sorting"]sorting}}.
+
+The Interchange Tags Reference has more information on the
+E<lbracket>{{C[jump="ictags.html#loop"]loop}}] tag.
+
+LI1: E<lbracket>{{C[jump="ictags.html#loop"]loop}}C< item item item]> LIST C<[/loop]>
+
+.named attributes: C<[loop prefix=label* list="item item item"* search="se=whatever"*]>
+
+.Returns a string consisting of the LIST, repeated for every item in a comma-separated or space-separated list. This tag works the same way as the C<[item-list]> tag, except for order-item-specific values. It is intended to pull multiple attributes from an item modifier, but can be useful for other things, like building a pre-ordained product list on a page.
+
+.Loop lists can be nested by using different prefixes:
+
+!block example; listitem=2
+ [loop prefix=size list="Small Medium Large"]
+ [loop prefix=color list="Red White Blue"]
+ [color-code]-[size-code]<BR>
+ [/loop]
+ <P>
+ [/loop]
+!endblock
+
+.This will output:
+
+!block example; listitem=2
+ Red-Small
+ White-Small
+ Blue-Small
+
+ Red-Medium
+ White-Medium
+ Blue-Medium
+
+ Red-Large
+ White-Large
+ Blue-Large
+!endblock
+
+.The search="args" parameter will return an arbitrary search, just as in a one-click search:
+
+!block example; listitem=2
+ [loop search="se=Americana/sf=category"]
+ [loop-code] [loop-field title]
+ [/loop]
+!endblock
+
+.The above will show all items with a category containing the whole world "Americana."
More information about the docs
mailing list