[docs] xmldocs - docelic modified 5 files
docs at icdevgroup.org
docs at icdevgroup.org
Sat Feb 19 12:14:04 EST 2005
User: docelic
Date: 2005-02-19 17:14:04 GMT
Added: refs AutoVariable Catalog DeleteDirective EncryptProgram
Added: FullUrl
Log:
More config directives documented
Revision Changes Path
1.1 xmldocs/refs/AutoVariable
rev 1.1, prev_rev 1.0
Index: AutoVariable
===================================================================
__NAME__ purpose
list config directives that are to be made available through the Variable space
__END__
__NAME__ see also
__END__
__NAME__ synopsis
<group choice='req'>
<arg choice='plain' rep='repeat'><replaceable>directive</replaceable></arg>
</group>
__END__
__NAME__ description
Specify list of &glos-configuration; directives that are to be automatically
created as variable/value pairs. This allows you to conveniently
write say, <code>__<replaceable>DIRECTIVENAME</replaceable>__</code> and
retrieve the corresponding configuration directive's value.
</para><para>
The above example, however, only works for scalar values. Since &IC;
also supports &glos-array;s and &glos-hash;es of values (so, all three
basic &PERL; types), the syntax had to be extended a little. With
array or hashes, you need to append the index number or hash key respectively.
See <xref linkend="AutoVariable_examples"/> for clarification.
__END__
__NAME__ notes
The directive does not support &glos-hash; keys that contain non-word
characters or whitespace. Also, only the first-level of array and hash
indices/keys is translated properly.
__END__
__NAME__ example: Enabling AutoVariable
Put the following in &ccf;:
<programlisting>
# The following two are present to form a standalone example
SafeUntrap sort
SysLog command /usr/bin/logger
AutoVariable VendURL SecureURL MailOrderTo SafeUnutrap SysLog
</programlisting>
__END__
__NAME__ example: Display a scalar value
Put the following on a page:
<programlisting>
Orders are e-mailed to: __MailOrderTo__
</programlisting>
__END__
__NAME__ example: Display an array value
Put the following on a page:
<programlisting>
First SafeUntrap value is: __SafeUntrap_0__
</programlisting>
__END__
__NAME__ example: Display a hash value
Put the following on a page:
<programlisting>
Syslog command is: __SysLog_command__
</programlisting>
__END__
1.1 xmldocs/refs/Catalog
rev 1.1, prev_rev 1.0
Index: Catalog
===================================================================
__NAME__ purpose
register catalog with the Interchange server
__END__
__NAME__ see also
FullUrl
__END__
__NAME__ synopsis
<arg choice='plain'><replaceable>name</replaceable></arg>
<arg choice='plain'><replaceable>&glos-CATROOT;</replaceable></arg>
<arg choice='plain' rep='repeat'><replaceable>&glos-link-program;</replaceable></arg>
__END__
__NAME__ description
The directive registers a catalog that will run on the corresponding &IC;
installation.
</para><para>
The directive expects three or more arguments.
</para><para>
First expected is the name of the catalog. It will be referred to by the specified
name in error, warning, and informational messages. It must contain only
alphanumeric characters, hyphens, and underscores. It is highly recommended that
it is also all lowercase.
</para><para>
Second argument specifies the local filesystem base directory of the catalog.
If the directory does not exist, the required &ccf; is not there, or &IC;
detects any other problem, catalog configuration will be skipped and the catalog
won't be activated.
</para><para>
Third argument is the so called <literal>SCRIPT_NAME</literal> of the
&glos-link-program;. It is a webserver path by which the catalog can be
accessed. It can be followed by different
<emphasis role='bold'>aliases</emphasis>, all allowing you to access
the same catalog. For example, this is useful when calling an SSL server or a
members-only alias that requires a Basic HTTP authorization using the
username/password pair. All subsequently generated links would be called using
the aliased URL.
</para><para>
The script name must be unique among CGI program paths that run on the
&IC; server, unless the &conf-FullUrl; directive is specified. In this case,
hostnames can be added to differentiate otherwise same paths; as usual, see
<xref linkend="Catalog_examples"/> for clarification.
</para><para>
It is also possible to define catalog-specific &glos-configuration; directives
from the global &gcf; file. Again, see <xref linkend="Catalog_examples"/>.
__END__
__NAME__ notes
&conf-Catalog; is one of the basic &IC; &glos-configuration; directives.
</para><para>
<command>makecat</command>, the catalog creation helper script, automatically inserts
the &conf-Catalog; line in the &gcf; file as part of the standard procedure.
</para><para>
If the &ccf; file, expected in the catalog base directory, is not found, or is
unreadable by the &IC; server, somewhat misguiding error message will be reported.
Namely, instead of the appropriate permissions-problem message, the mandatory
&conf-MailOrderTo; directive will be reported undefined.
__END__
__NAME__ example: Registering a catalog
<programlisting>
Catalog simple /home/catalogs/simple /cgi-bin/ic/simple
</programlisting>
__END__
__NAME__ example: Using FullUrl to differentiate same-named catalogs on different hosts
<programlisting>
FullUrl yes
Catalog simple1 /home/catalogs/simple1 www.company1.com/cgi-bin/ic/simple
Catalog simple2 /home/catalogs/simple2 www.company2.com/cgi-bin/ic/simple
</programlisting>
Make sure to read the &conf-FullUrl; directive reference before just
including it in your &glos-configuration;.
__END__
__NAME__ example: Elaborate Catalog directive definition
Given the nature of the &conf-Catalog; directive, a catalog can be somewhat
verbosely registered as:
<programlisting>
Catalog simple directory /home/catalogs/simple
Catalog simple script /cgi-bin/ic/simple
Catalog simple alias /simple
</programlisting>
__END__
__NAME__ example: Defining catalog-specific directives in the global config file
Re-using the elaborate example from just above, it is also possible to define
catalog-specific directives in the global &gcf; file.
This is most useful to do with the &glos-ErrorFile; and &glos-DisplayErrors;
directives:
<programlisting>
Catalog simple directive ErrorFile /var/log/interchange/simple-error.log
</programlisting>
__END__
TODO: Can catalog.cfg override cat-specific directives set in interchange.cfg ?
TODO: How if catalog names supported regexps, so you could do like:
Catalog \S+ directive ErrorFile /var/log/interchange/$1-error.log
1.1 xmldocs/refs/DeleteDirective
rev 1.1, prev_rev 1.0
Index: DeleteDirective
===================================================================
__NAME__ purpose
disable use of specified configuration directive in catalog.cfg
__END__
__NAME__ synopsis
<group choice='req'>
<arg choice='plain' rep='repeat'><replaceable>directive</replaceable></arg>
</group>
__END__
__NAME__ description
This directive specifies the directives which are to be disabled during parse
of the &ccf; files.
</para><para>
This can be effectively used to both save some memory on servers with many
catalogs and prevent catalogs from setting some of the directives.
__END__
__NAME__ see also
AddDirective
__END__
__NAME__ example: Setting DeleteDirective
<programlisting>
DeleteDirective DescriptionField OfflineDir
</programlisting>
__END__
TODO: What happens when you delete, say, PriceField directive? Does IC
still properly fallbacks to default 'price' ?
1.1 xmldocs/refs/EncryptProgram
rev 1.1, prev_rev 1.0
Index: EncryptProgram
===================================================================
__NAME__ purpose
specify default encryption program
__END__
__NAME__ synopsis
<group choice='req'>
<arg choice='plain'><replaceable>filename</replaceable></arg>
</group>
__END__
__NAME__ description
Specify default encryption program. It will be called to perform tasks such
as encrypting credit card numbers (<emphasis role='bold'>if</emphasis> they
are stored on the server).
</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
encryption.
__END__
__NAME__ see also
DEBUG, DataTrace, DebugFile
__END__
__NAME__ example: Enabling DumpStructure
<programlisting>
DumpStructure Yes
</programlisting>
__END__
1.1 xmldocs/refs/FullUrl
rev 1.1, prev_rev 1.0
Index: FullUrl
===================================================================
__NAME__ purpose
use full URLs (those including hostnames) in catalog definition lines
__END__
__NAME__ synopsis
<group choice='req'>
<arg choice='plain'>No</arg>
<arg choice='plain'>Yes</arg>
</group>
__END__
__NAME__ description
&IC; determines the appropriate catalog to invoke by the
<literal>SCRIPT_NAME</literal> from the CGI call. This means that different
(possibly virtual) hosts cannot use the same <literal>SCRIPT_NAME</literal>, as
the catalogs would become indistinguishable. Set this directive to enable
differentiation performed on the hostname as well.
</para><para>
See the &conf-Catalog; directive for more on the subject and concrete
examples.
__END__
__NAME__ notes
If &conf-FullUrl; is defined, <emphasis role='bold'>all> catalogs must be
defined with hostnames included</emphasis>. Per-catalog setting will not work,
as this is used before the catalog name is known.
__END__
__NAME__ see also
Catalog
__END__
__NAME__ example: Enabling FullUrl
<programlisting>
FullUrl yes
</programlisting>
__END__
More information about the docs
mailing list