- Small fixes/updates to 6 existing files

- 8 new items documented

README

@@ -14,6 +14,7 @@ INTRODUCTION
 The (new) Interchange XML documentation set is completely self-contained.
 To build the complete documentation set, just run:
 
+  make cvs
   make
 
 It's also possible to change OUTPUT/ directory to something else, named
@@ -34,6 +35,7 @@ To build specific targets, see Makefile for target names. Few useful
 targets would include:
 
  -- Those that are not part of 'make' routine:
+  make cvs          (to create complete sources/ directory, or update existing)
   make clean        (removes OUTPUT/)
   make distclean    (remove OUTPUT/ and tmp/)
   make look-clean   (clean + 'mv tmp tmp.temporary'. Useful to only make
@@ -43,7 +45,6 @@ targets would include:
                     regenerating OlinkDB files).
 
  -- And those that are part of 'make':
-  make cvs          (to create complete sources/ directory, or update existing)
   make skel
   make cache
   make refxmls
@@ -109,7 +110,7 @@ During the invocation of 'make', few files will be created:
                    fit.
 
                    This can also be OUTPUT<yourprefix>, if you pass e.g.
-                   OUTPUT=-std in a call to make (as shown above).
+                   OUTPUT=-std in a call to make (as already shown above).
 
   tmp/missing[2] - After you build the documentation, there will be a file
                    named tmp/missing autogenerated, and it will contain a list

WRITING

@@ -97,7 +97,7 @@ The system separates documentation contents into 5 major groups:
 WRITING
 
 Not to waste words, and to give practical examples, best see the existing
-documentation for reference how to write new or fix existing pieces.
+documentation for reference on how to write new or update existing material.
 
 You also need to look at docbook/*.ent files, they contain XML entities
 that you are encouraged to use instead of writing common symbols, words and

docbook/literals.ent

@@ -49,8 +49,8 @@
 <!-- Do we need to be so verbose? Isn't just empty space ok?
 <!ENTITY DEF_SYNOPSIS  "None specified.">
 <!ENTITY DEF_DESCRIPTION "No more specific information was supplied. We know
-<!ENTITY DEF_NOTES "None.">
 this piece is missing and we'll try to update it.">
+<!ENTITY DEF_NOTES "None.">
 -->
 <!ENTITY DEF_SYNOPSIS  "">
 <!ENTITY DEF_DESCRIPTION "">

refs/AccumulateCode

@@ -0,0 +1,51 @@
+__NAME__ purpose
+fetch Interchange code on-demand from CodeRepository instead of starting up with everything
+__END__
+
+
+__NAME__ synopsis
+<group choice='req'>
+	<arg choice='plain'>No</arg>
+	<arg choice='plain'>Yes</arg>
+</group>
+__END__
+
+
+__NAME__ description
+The directive instructs &IC; to fetch code blocks "on-demand" from the
+&conf-CodeRepository;, instead of starting up with everything.
+</para><para>
+So, at runtime, when particular functionality is needed but is not
+yet present in the running &IC; installation, it is copied from 
+&conf-CodeRepository; to 
+<filename class='directory'>$Global::TagDir/Accumulated/</filename>.
+When you restart &IC; the next time, these code blocks will be found,
+read normally and need not be recompiled on the fly again.
+</para><para>
+Over time, as you access pages and routines, a full set of tags
+will be developed and you can then disable &conf-AccumulateCode;.
+(Infact, &code-AccumulateCode; is recommended for development and should 
+really be turned off in production systems).
+__END__
+
+__NAME__ notes
+See &conf-CodeRepository; for a complete discussion.
+__END__
+
+__NAME__ see also
+CodeRepository
+__END__
+
+__NAME__ author
+&mheins;
+__END__
+
+
+__NAME__ example: Enabling AccumulateCode
+Put the following in &gcf;:
+<programlisting>
+AccumulateCode Yes
+</programlisting>
+See &conf-CodeRepository; for a complete example.
+__END__
+

refs/AcrossLocks

@@ -0,0 +1,32 @@
+__NAME__ purpose
+
+__END__
+
+
+__NAME__ synopsis
+<group choice='req'>
+	<arg choice='plain'>No</arg>
+	<arg choice='plain'>Yes</arg>
+</group>
+__END__
+
+
+__NAME__ description
+__END__
+
+__NAME__ notes
+__END__
+
+__NAME__ see also
+__END__
+
+__NAME__ author
+__END__
+
+
+__NAME__ example: Enabling AcrossLocks
+<programlisting>
+AcrossLocks yes
+</programlisting>
+__END__
+

refs/AutoModifier

@@ -0,0 +1,54 @@
+__NAME__ purpose
+specify products database columns containing values for product attributes
+__END__
+
+
+__NAME__ missing
+__END__
+
+
+__NAME__ see also
+UseModifier
+__END__
+
+__NAME__ synopsis
+<group choice='req'>
+	<arg choice='plain' rep='repeat'><replaceable>column</replaceable></arg>
+</group>
+__END__
+
+
+__NAME__ description
+The directive specifies names of the &glos-attribute;s attached to
+your products, for which the value is provided in the equally-named 
+<database>products</database> database column.
+</para><para>
+In other words, 
+when an item is added to the shopping cart using &IC;'s routines, the
+attributes declared in &conf-AutoModifier; will be set to the values of the
+equally-named fields in the <database>products database</database>.
+</para><para>
+As you see, this is mostly useful for internal use and giving your
+code specific hints about the items ordered.
+__END__
+
+
+__NAME__ notes
+This can useful when doing shipping calculations or in embedded
+&PERL; code that works on item attributes.
+</para><para>
+See &glos-attribute; for a complete introduction to item attributes.
+__END__
+
+__NAME__ example: Specifying AutoModifier
+To set whether an item is defined as "heavy" and requires truck shipment, or
+is "downloadable", set:
+<programlisting>
+AutoModifier heavy downloadable
+</programlisting>
+Also make sure to have the
+<database class='field'>heavy</database> and 
+<database class='field'>downloadable</database> columns defined in your 
+<database>products</database> database.
+__END__
+

refs/CodeRepository

@@ -42,7 +42,7 @@ and ready to go.
 </para><para>
 It also copies the code file to the <literal>code/</literal>
 (<varname>$Global::TagDir</varname> actually) directory, in the
-<filename class='directory'>Accumulated</filename> subdirectory tree.
+<filename class='directory'>Accumulated/</filename> subdirectory tree.
 When you restart &IC; the next time, these code blocks will be found,
 read normally and need not be recompiled on the fly again.
 </para><para>
@@ -111,7 +111,7 @@ __NAME__ author
 __END__
 
 
-__NAME__ example: Enabling CodeRepository
+__NAME__ example: Setting up CodeRepository
 Put the following in &gcf;:
 <programlisting>
 AccumulateCode Yes

refs/CookieDomain

@@ -0,0 +1,75 @@
+__NAME__ purpose
+set domain common to all servers providing Interchange content
+__END__
+
+
+__NAME__ synopsis
+<group choice='req'>
+	<arg choice='plain' rep='repeat'><replaceable>domain</replaceable></arg>
+</group>
+__END__
+
+
+__NAME__ see also
+CookieDomain,CookieLogin,Cookies,SaveExpire
+__END__
+
+
+__NAME__ description
+The directive specifies the domain common to all servers providing 
+&IC; content.
+</para><para>
+By default, the &glos-session; ID cookie domain is set to the hostname
+that you're accessing. For example, if you access the catalog using
+server <literal>&def-hostname;</literal>, then cookie will be set by
+<literal>&def-hostname;</literal>.
+</para><para>
+Things, however, go bad if you use more &IC; servers
+(in a non-transparent way for the user) to provide content.
+For example, if SSL content was served from host
+<literal>ssl.&def-domain;</literal>, then users would have one 
+session for <literal>&def-hostname;</literal> and one for 
+<literal>ssl.&def-domain;</literal>. This is undesired, of course.
+</para><para>
+To fix the described problem, we need to find part of the
+FQDN that is common to all servers (<literal>&def-domain;</literal>
+in our example), and add it as the 
+<literal>domain=</literal> parameter to the
+<literal>Set-Cookie</literal> directive that we send off to users'
+browsers. That's what the &conf-CookieDomain; does.
+__END__
+
+
+__NAME__ notes
+The cookie specification mandates that the domain part must contain
+at least two fields (or 1 dot lying in between). The value 
+of <literal>.&def-domain;</literal> is valid, but <literal>.local</literal>
+wouldn't be.
+</para><para>
+Furthermore, cookie source can only be the FQDN of the host itself, or
+some of the subdomains, or domain it belongs to. Browsers will ignore
+all cookies that do not satisfy this requirement. Host 
+<literal>&def-hostname;</literal> can set a cookie for itself or the
+domain <literal>&def-domain;</literal>, but it cannot set a cookie
+for say, <literal>&def-domain;2</literal>. It is very fortunate we
+have this protection, or unrelated sites would read and set each other's
+cookies &mdash; something we definitely don't want to happen!
+</para><para>
+At least in Mozilla-like browsers, the domain is prefixed with a 
+dot even if you omit it in the &conf-CookieDomain; specification
+(<literal>&def-domain;</literal> ends up being the same as
+<literal>.&def-domain;</literal>).
+</para><para>
+&conf-CookieDomain; accepts a space-separated list of domains to set
+cookies for, in which case the <literal>Set-Cookie: ...</literal> 
+is sent to the client for each of the specified domains. Due to the
+restrictions described above, specifying multiple domains is needed and
+possible to implement only rarely, if ever.
+__END__
+
+__NAME__ example: Specifying CookieDomain
+<programlisting>
+CookieLogin .&def-domain;
+</programlisting>
+__END__
+

refs/CookieName

@@ -1,10 +1,10 @@
 __NAME__ purpose
-specify Interchange session cookie name
+specify Interchange cookie name
 __END__
 
 
 __NAME__ see also
-CookieLogin,SessionExpire
+CookiePattern,CookieLogin
 __END__
 
 
@@ -14,20 +14,30 @@ __END__
 
 
 __NAME__ description
-The directive sets the name of the ⁣ session ID cookie.
+The directive sets the name of the Interchange &glos-cookie; that 
+will be used to retrieve session ID information in users' browsers.
 The default value is <literal>MV_SESSION_ID</literal>.
+</para><para>
+The default should never be changed, but this configuration directive
+can save the day if you need to use cookies issued by programs other
+than &IC; itself.
 __END__
 
 
 __NAME__ notes
+By default, &IC; cookie planted in user's browser consists of
+a session ID followed by a colon followed by an IP address, username
+or domain name.
 __END__
 
-__NAME__ example: Redefining CookieName
+__NAME__ example: Defining CookieName
 <programlisting>
 CookieName SESSIONID
 </programlisting>
 __END__
 
 
-TODO: Seems it needs CookiePattern to work, but currently the whole
-thing is a little broken
+THE THING HERE is that IC will respect the cookie it finds if
+CookieName is set, and won't override it with a new one like it
+does in standard setup when you provide the cookie but IC doesn't like
+it because it's say, expired.

refs/CookiePattern

@@ -0,0 +1,43 @@
+__NAME__ purpose
+specify regular expression to extract session ID out of a client cookie
+__END__
+
+
+__NAME__ see also
+CookieName
+__END__
+
+
+__NAME__ synopsis
+	<arg choice='plain'><replaceable>regex_pattern</replaceable></arg>
+__END__
+
+
+__NAME__ description
+The directive sets the regular expression that &IC; will use to extract
+the session ID out of the client browser's &glos-cookie;.
+__END__
+
+__NAME__ notes
+By default, &IC; cookie planted in user's browser consists of 
+a session ID followed by a colon followed by an IP address, username
+or domain name.
+__END__
+
+__NAME__ example: Setting CookiePattern
+The default regular expression pattern used for &conf-CookiePattern;
+might work sometimes, but I find it unsuitable if you just want to change
+the &conf-CookieName;, because it then breaks the usual behavior.
+Here's a better value for common setups:
+<programlisting>
+CookiePattern \w{8,32}
+</programlisting>
+In general, however, you should only modify &conf-CookiePattern; default
+value if you somehow change the <emphasis role='bold'>content</emphasis>
+that &IC; stores in browser cookies (by say, letting other program create
+the cookie).
+__END__
+
+
+TODO: Seems it needs CookiePattern to work, but currently the whole
+thing is a little broken

refs/DifferentSecure

@@ -0,0 +1,16 @@
+__NAME__ purpose
+(obsolete)
+__END__
+
+__NAME__ synopsis
+__END__
+
+__NAME__ see also
+__END__
+
+__NAME__ description
+__END__
+
+__NAME__ notes
+__END__
+