[docs] xmldocs - docelic modified 15 files
docs at icdevgroup.org
docs at icdevgroup.org
Fri Aug 12 08:41:52 EDT 2005
User: docelic
Date: 2005-08-12 12:41:52 GMT
Modified: . README WRITING
Modified: docbook literals.ent
Modified: refs CodeRepository CookieName EncryptProgram NoAbsolute
Added: refs AccumulateCode AcrossLocks AutoModifier
Added: CookieDomain CookiePattern DifferentSecure
Added: EncryptKey liven_urls.filter
Log:
- Small fixes/updates to 6 existing files
- 8 new items documented
Revision Changes Path
1.19 +3 -2 xmldocs/README
rev 1.19, prev_rev 1.18
Index: README
===================================================================
RCS file: /var/cvs/xmldocs/README,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -r1.18 -r1.19
--- README 9 Aug 2005 00:00:17 -0000 1.18
+++ README 12 Aug 2005 12:41:51 -0000 1.19
@@ -14,6 +14,7 @@
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 @@
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 @@
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 @@
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
1.4 +1 -1 xmldocs/WRITING
rev 1.4, prev_rev 1.3
Index: WRITING
===================================================================
RCS file: /var/cvs/xmldocs/WRITING,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- WRITING 2 Feb 2005 11:35:58 -0000 1.3
+++ WRITING 12 Aug 2005 12:41:51 -0000 1.4
@@ -97,7 +97,7 @@
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
1.26 +1 -1 xmldocs/docbook/literals.ent
rev 1.26, prev_rev 1.25
Index: literals.ent
===================================================================
RCS file: /var/cvs/xmldocs/docbook/literals.ent,v
retrieving revision 1.25
retrieving revision 1.26
diff -u -r1.25 -r1.26
--- literals.ent 17 Feb 2005 23:11:31 -0000 1.25
+++ literals.ent 12 Aug 2005 12:41:51 -0000 1.26
@@ -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 "">
1.2 +2 -2 xmldocs/refs/CodeRepository
rev 1.2, prev_rev 1.1
Index: CodeRepository
===================================================================
RCS file: /var/cvs/xmldocs/refs/CodeRepository,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- CodeRepository 27 Jul 2005 17:19:13 -0000 1.1
+++ CodeRepository 12 Aug 2005 12:41:51 -0000 1.2
@@ -42,7 +42,7 @@
</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 @@
__END__
-__NAME__ example: Enabling CodeRepository
+__NAME__ example: Setting up CodeRepository
Put the following in &gcf;:
<programlisting>
AccumulateCode Yes
1.3 +16 -6 xmldocs/refs/CookieName
rev 1.3, prev_rev 1.2
Index: CookieName
===================================================================
RCS file: /var/cvs/xmldocs/refs/CookieName,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- CookieName 9 Aug 2005 00:00:17 -0000 1.2
+++ CookieName 12 Aug 2005 12:41:51 -0000 1.3
@@ -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 @@
__NAME__ description
-The directive sets the name of the &IC; 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.
1.5 +5 -2 xmldocs/refs/EncryptProgram
rev 1.5, prev_rev 1.4
Index: EncryptProgram
===================================================================
RCS file: /var/cvs/xmldocs/refs/EncryptProgram,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- EncryptProgram 9 Aug 2005 00:00:17 -0000 1.4
+++ EncryptProgram 12 Aug 2005 12:41:51 -0000 1.5
@@ -15,8 +15,11 @@
numbers (<emphasis role='bold'>if</emphasis> they are stored on the server).
</para><para>
Two placeholders can be used, <literal>%p</literal> and
-<literal>%f</literal>. At encryption time, the former expands to a password,
-the latter one to a temporary file name.
+<literal>%f</literal>. At encryption time,
+<literal>%p</literal>
+expands to a password, and
+<literal>%f</literal>
+to a temporary file name.
</para><para>
If &IC; can found a variant of <command>gpg</command>/<command>pgp</command>
on your system, it is the default. Setting of <literal>none</literal> disables
1.3 +1 -1 xmldocs/refs/NoAbsolute
rev 1.3, prev_rev 1.2
Index: NoAbsolute
===================================================================
RCS file: /var/cvs/xmldocs/refs/NoAbsolute,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- NoAbsolute 8 Dec 2004 12:39:58 -0000 1.2
+++ NoAbsolute 12 Aug 2005 12:41:51 -0000 1.3
@@ -1,5 +1,5 @@
__NAME__ purpose
-disable catalogs to read absolute filenames on the system
+deny catalogs to read absolute filenames on the system
__END__
1.1 xmldocs/refs/AccumulateCode
rev 1.1, prev_rev 1.0
Index: AccumulateCode
===================================================================
__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__
1.1 xmldocs/refs/AcrossLocks
rev 1.1, prev_rev 1.0
Index: AcrossLocks
===================================================================
__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__
1.1 xmldocs/refs/AutoModifier
rev 1.1, prev_rev 1.0
Index: AutoModifier
===================================================================
__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__
1.1 xmldocs/refs/CookieDomain
rev 1.1, prev_rev 1.0
Index: CookieDomain
===================================================================
__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 — 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__
1.1 xmldocs/refs/CookiePattern
rev 1.1, prev_rev 1.0
Index: CookiePattern
===================================================================
__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
1.1 xmldocs/refs/DifferentSecure
rev 1.1, prev_rev 1.0
Index: DifferentSecure
===================================================================
__NAME__ purpose
(obsolete)
__END__
__NAME__ synopsis
__END__
__NAME__ see also
__END__
__NAME__ description
__END__
__NAME__ notes
__END__
1.1 xmldocs/refs/EncryptKey
rev 1.1, prev_rev 1.0
Index: EncryptKey
===================================================================
__NAME__ purpose
specify default key to use for encryption
__END__
__NAME__ synopsis
<arg choice='req'><replaceable>key_or_user_identifier</replaceable></arg>
__END__
__NAME__ description
Specify default key to use for encryption.
</para><para>
GnuPG accepts both a key identifier or a part of user identifier.
__END__
__NAME__ see also
EncryptProgram
__END__
__NAME__ example: Specifying key identifier to EncryptKey
<programlisting>
EncryptKey 9B726B71
</programlisting>
__END__
__NAME__ example: Specifying user identifier to EncryptKey
<programlisting>
EncryptKey racke at linuxia.de
</programlisting>
__END__
1.1 xmldocs/refs/liven_urls.filter
rev 1.1, prev_rev 1.0
Index: liven_urls.filter
===================================================================
__NAME__ purpose
make all kinds of URLs clickable
__END__
__NAME__ see also
mailto
__END__
__NAME__ description
The filter searches the input for all kinds of links, and wraps them
into the standard &glos-HTML; <a href=><> package.
</para><para>
The filter can recognize all sorts of URLs and to a great detail.
__END__
__NAME__ notes
For more information on &PERL; Regular Expressions, pattern matching and
character classes, see
<citerefentry><refentrytitle>perlre</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para><para>
The matching expressions were generated with the help of
Abigail's
<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.
For the rest of the protocols, you need to uncomment the appropriate
lines in the filter source and restart &IC;.
</para><para>
The regular expressions used are really scary — don't try
them at home! ;-)
__END__
__NAME__ author
&docelic;
__END_
__NAME__ online: Filter example
Here's an incomplete collection of URLs that the filter can recognize.
<programlisting><![CDATA[
[filter liven_urls]
http://www.acl.lanl.gov/URI/archive/uri-archive.index.html<br/>
ftp://@host.com/<br/>
ftp://host.com/<br/>
ftp://foo:@host.com/<br/>
ftp://myname@host.dom/%2Fetc/motd<br/>
ftp://myname@host.dom/etc/motd<br/>
ftp://myname@host.dom//etc/motd<br/>
file://vms.host.edu/disk$user/my/notes/note12345.txt<br/>
prospero://host.dom//pros/name<br/>
ldap:///o=University%20of%20Michigan,c=US<br/>
ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US<br/>
ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US?postalAddress<br/>
ldap:///o=University%20of%20Michigan,c=US??sub?(cn=Babs%20Jensen)<br/>
ldap://ldap.itd.umich.edu/c=GB?objectClass?one<br/>
z39.50s://melvyl.ucop.edu/cat<br/>
z39.50r://melvyl.ucop.edu/mags?elecworld.v30.n19<br/>
z39.50r://cnidr.org:2100/tmf?bkirch_rules__a1;esn=f;rs=marc<br/>
mid:foo4%25foo1 at bar.net<br/>
cid:foo4*foo1 at bar.net<br/>
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__
More information about the docs
mailing list