- 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

TODO

@@ -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:

bin/refs-autogen

@@ -1089,13 +1089,14 @@ sub populate {
 			# 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

docbook/literals.ent

@@ -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>">
 
 
 

glossary/ITL

@@ -335,6 +335,8 @@ disassembling named parameters takes some more CPU cycles.
 <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.
@@ -418,6 +420,44 @@ different approaches to produce the result:
 </programlisting>
 </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>
@@ -648,8 +688,6 @@ $Tag->ROUTINE( { entry => $hashref } );
 ]]></programlisting>
 </para>
 
-
-<!-- TODO backticks -->
 </section>
 
 

glossary/profile

@@ -196,5 +196,30 @@ The C<__NAME__> is the value to be specified in the C<mv_profile> variable on th
   [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       
+
 -->
 

glossary/session

@@ -139,5 +139,27 @@ Some thought should be given to where the databases, error logs, and session fil
 
 
 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
+
+
+
 
 -->

guides/install.xml

@@ -332,13 +332,25 @@ $ gzip -dc interchange-latest.tar.gz | tar xvf -
 	or want to keep everything under your own control. However, there is the
 	so-called "&std-catalog;" demo that ships with ⁣ — 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 @@ $ gzip -dc interchange-latest.tar.gz | tar xvf -
 	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>
 

refs/SocketPerms

@@ -15,7 +15,7 @@ __END__
 
 
 __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 @@ directive can be overridden from the command line using <literal>interchange
 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__
 
 

refs/accessories.tag

@@ -115,4 +115,20 @@ __NAME__ synopsis
 </row> 
 &ROW_INTERPOLATE_0;
 &ROW_REPARSE_1;
-__END__
+__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__
+
+

refs/index.tag

@@ -191,4 +191,12 @@ __NAME__ synopsis
 </row> 
 &ROW_INTERPOLATE_0;
 &ROW_REPARSE_1;
-__END__
+__END__
+
+# Resolve name clash with index.html (this will become index2.html)
+# Not too nice, but :)
+__NAME__ id
+2
+__END__
+
+

refs/loop.tag

@@ -381,4 +381,70 @@ __NAME__ synopsis
 </row> 
 &ROW_INTERPOLATE_0;
 &ROW_REPARSE_1;
-__END__
+__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."