[docs] xmldocs - docelic modified 12 files

docs at icdevgroup.org docs at icdevgroup.org
Tue Nov 30 17:46:23 EST 2004 

User:      docelic
Date:      2004-11-30 22:46:23 GMT
Modified:  refs     CheckHTML VariableDatabase
Added:     glossary UserDB configuration
Added:     refs     AcceptRedirect Capability DisplayErrors Require
Added:              Suggest ValuesDefault Variable
Removed:   glossary userdb
Log:
Well well, the population is growing ;)

Revision  Changes    Path
1.1                  xmldocs/glossary/UserDB


rev 1.1, prev_rev 1.0
Index: UserDB
===================================================================

<glossentry id="UserDB">
<glossterm>UserDB</glossterm>
<glossterm>User Database</glossterm>

<glossdef>
<para>
</para>
</glossdef>

</glossentry>




1.1                  xmldocs/glossary/configuration


rev 1.1, prev_rev 1.0
Index: configuration
===================================================================

<glossentry id="configuration">
<glossterm>configuration</glossterm>

<glossdef>
<para>
&IC; supports multiple catalogs, and therefore splits its configuration
into two pieces. One is global, &gcf;, and affects every catalog running
under that &IC; server.
The other, &ccf;, is specific to an individual catalog, and has no effect
on other catalogs.
</para><para>
Configuration directives are normally specified with the directive as the
first word on the line, with its value or values following. Capitalization
of the directive name is not significant (although it helps readability and
consistency). Additionally, any leading and trailing whitespace is removed
("stripped") before processing. Here's an example:
<programlisting>
DirectiveName <replaceable>value</replaceable>
</programlisting>
</para><para>
Besides specifying directive values inline, one can conveniently use
the following syntax to obtain value from external files:

<programlisting>
DirectiveName &lt;<replaceable>include_filename</replaceable>
</programlisting>

<note><para>
Note that this syntax can be used anywhere on a line, such as in 
<code>Variable MYSTUFF &lt;<replaceable>file</replaceable></code>.
You can use this to achieve the
best performance with <option>Variable</option>s.
</para></note>

Files included from &gcf; are relative to &glos-ICROOT;. Files included
from &ccf; are relative to specific &glos-CATROOT;.

</para><para>
So-called "here document" syntax is supported as well. You can use it to
spread directive values over several lines, with the usual &PERL;
&lt;&lt;MARKER syntax (but unlike Perl, &IC; syntax uses no semicolon to
terminate the marker). The closing marker must be the only thing on the line.
No leading or trailing characters are allowed, not even whitespace. Here
is a hypothetical directive using a here document:

<programlisting>
DirectiveName &lt;&lt;EOD<replaceable>
    setting1
    setting2
    setting3</replaceable>
EOD
</programlisting>


</para><para>
The above is equivalent to:
<programlisting>
DirectiveName <replaceable>setting1 setting2 setting3</replaceable>
</programlisting>

</para><para>
Other configuration files can also be included from the current one.
For example, common settings can be set in one file:

<programlisting>
include common.cfg
</programlisting>

Or all files loaded from a directory:

<programlisting>
include usertag/*
</programlisting>

</para><para>
In addition,
<literal>ifdef/endif</literal> and <literal>ifndef/endif</literal> pairs
can be used:

<programlisting>
Variable ORDERS_TO email_address

ifdef ORDERS_TO
  ParseVariables Yes
  MailOrderTo __ORDERS_TO__
  ParseVariables No
endif

ifdef ORDERS_TO =~ /foo.com/
  # Send all orders at foo.com to one place now
  # Set ORDERS_TO to stop default setting
  Variable  ORDERS_TO  1
  MailOrderTo   orders at foo.com
  endif

ifdef ORDERS_TO eq 'nobody at nowhere.com'
  # Better change to something else, set ORDERS_TO to stop default
  Variable  ORDERS_TO  1
  MailOrderTo   someone at somewhere.com
endif

ifndef ORDERS_TO
  #Needs to go somewhere....
  MailOrderTo  webmaster@&def-domain;
  endif
</programlisting>

</para>
</glossdef>

</glossentry>




1.2       +1 -1      xmldocs/refs/CheckHTML


rev 1.2, prev_rev 1.1
Index: CheckHTML
===================================================================
RCS file: /var/cvs/xmldocs/refs/CheckHTML,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- CheckHTML	9 Nov 2004 23:16:16 -0000	1.1
+++ CheckHTML	30 Nov 2004 22:46:22 -0000	1.2
@@ -17,7 +17,7 @@
 
 __NAME__ description
 Defines the name of an external program which will be invoked
-to check the generated page HTML code for correctness
+to check the generated page &glos-HTML; code for correctness
 (<command>/usr/bin/weblint</command>, for example).
 </para><para>
 Note that you need to put <code>[flag checkhtml]</code> on your page, 



1.2       +7 -0      xmldocs/refs/VariableDatabase


rev 1.2, prev_rev 1.1
Index: VariableDatabase
===================================================================
RCS file: /var/cvs/xmldocs/refs/VariableDatabase,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- VariableDatabase	29 Nov 2004 19:51:09 -0000	1.1
+++ VariableDatabase	30 Nov 2004 22:46:22 -0000	1.2
@@ -15,6 +15,13 @@
 
 
 __NAME__ description
+The directive specifies name of a database containing a field
+<database class='field'>Variable</database>
+which will be used to return Interchange variable values.
+</para><para>
+In other words, instead of keeping a long list of
+<code>Variable NAME value</code> definitions in &gcf; or &ccf;, you can
+simply create a database with the name and value pairs.
 __END__
 
 



1.1                  xmldocs/refs/AcceptRedirect


rev 1.1, prev_rev 1.0
Index: AcceptRedirect
===================================================================
__NAME__ purpose
accept Web server redirects
__END__

__NAME__ synopsis
<group choice='req'>
	<arg choice='plain'>No</arg>
	<arg choice='plain'>Yes</arg>
</group>
__END__


__NAME__ description
The directive
enables processing of HTTP server redirects, i.e. when handling ErrorDocument
for a Web server such as &APACHE;. For instance, if your
<filename>httpd.conf</filename> contains

<programlisting>
  ErrorDocument 404 /cgi-bin/ic/&std-catalog;
</programlisting>

then a request for <literal>/somedir/index.html</literal> that is not found
on the Web server would be resent to
<filename>/cgi-bin/ic/foundation/somedir/index.html</filename>, and
would be 
indistinguishable from the Web server-served page by the client.
__END__


__NAME__ notes
Although the idea seems attractive at first sight,
caution should be taken not to allow Web server's ErrorDocument redirection
to &IC; globally &mdash; it would render you subject to a
denial-of-service attack at random URLs (i.e. a flood of MS Windows
"Code Red" attacks). It is recommended that you enable it only for
specific directories, as &APACHE; or another HTTP server will stand up
much better under such a flood.
__END__


__NAME__ example
<example>
  <title>Enabling AcceptRedirect</title>
	<para>
	Put any of the following lines in &ccf;:
	</para>
<programlisting>
AcceptRedirect Yes
</programlisting>
</example>
__END__




1.1                  xmldocs/refs/Capability


rev 1.1, prev_rev 1.0
Index: Capability
===================================================================
__NAME__ purpose
test existence of a feature
__END__

__NAME__ see also
Require,Suggest
__END__

__NAME__ synopsis
<group choice='req'>
	<arg choice='plain' rep='repeat'>
		<replaceable>type</replaceable>
		<replaceable>type-specific value</replaceable>
	</arg>
</group>
__END__


__NAME__ description
Just like &conf-Require; or &conf-Suggest;, this directive checks for
a feature or capability, but unlike the first two it never causes a
warning or other message. This allows a module to be loaded if available
and a program can later check for the capability and dynamically adapt to the
configuration.
__END__

__NAME__ example
<example>
  <title>Testing for existence of Archive::Zip Perl module</title>
  <programlisting>
Capability module Archive::Zip
  </programlisting>
</example>
__END__




1.1                  xmldocs/refs/DisplayErrors


rev 1.1, prev_rev 1.0
Index: DisplayErrors
===================================================================
__NAME__ purpose
display eventual errors directly in the client session
__END__


__NAME__ synopsis
<group choice='req'>
	<arg choice='plain'>No</arg>
	<arg choice='plain'>Yes</arg>
</group>
__END__


__NAME__ description
All &IC; errors are reported in the error log, but errors can also be
displayed directly in the client browser. This is convenient while testing
a configuration. To allow catalog-specific settings of &conf-DisplayErrors;
the global directive needs to be enabled.
__END__

__NAME__ notes
This directive changes the operation of <code>$SIG{__DIE__}</code> and
may have other effects on program operation.
This should <emphasis role='bold'>never</emphasis> be used for normal
operation.
__END__

__NAME__ example
<example>
  <title>Enabling DisplayErrors</title>
	<para>Put the following in &gcf;</para>
<programlisting>
DisplayErrors Yes
</programlisting>
</example>
__END__




1.1                  xmldocs/refs/Require


rev 1.1, prev_rev 1.0
Index: Require
===================================================================
__NAME__ purpose
guarantee existence of a feature
__END__

__NAME__ see also
Require,Suggest
__END__

__NAME__ synopsis
<group choice='req'>
	<arg choice='plain' rep='repeat'>
		<replaceable>type</replaceable>
		<replaceable>type-specific value</replaceable>
	</arg>
</group>
__END__

__NAME__ description
Just like &conf-Capability; or &conf-Suggest;, this directive checks for
a feature or capability. When the tested feature is missing, a 
catalog is <emphasis role='bold'>not</emphasis> configured and included
in global configuration.
</para><para>
This is useful when transporting catalogs to different locations, to make
sure they will have all the needed facilities available.
__END__

__NAME__ example
<example>
  <title>Requireing features</title>
<programlisting>
Require module    Archive::Zip
Require usertag   table_editor
Require globalsub file_info
</programlisting>
</example>
__END__




1.1                  xmldocs/refs/Suggest


rev 1.1, prev_rev 1.0
Index: Suggest
===================================================================
__NAME__ purpose
check existence of a feature
__END__

__NAME__ see also
Require,Suggest
__END__

__NAME__ synopsis
<group choice='req'>
	<arg choice='plain' rep='repeat'>
		<replaceable>type</replaceable>
		<replaceable>type-specific value</replaceable>
	</arg>
</group>
__END__

__NAME__ missing
Which values can appear for 'type' ? module, usertag, globalsub, ... ?
Also make notes @ Require and Capability entries.
__END__


__NAME__ description
Just like &conf-Require; or &conf-Suggest;, this directive checks for
a feature or capability. When the tested feature is missing, a 
warning message is shown.
__END__

__NAME__ example
<example>
  <title>Testing for features</title>
<programlisting>
Suggest module    Archive::Zip
Suggest usertag   table_editor
Suggest globalsub file_info
Suggest module    Business::UPS
</programlisting>
</example>
__END__




1.1                  xmldocs/refs/ValuesDefault


rev 1.1, prev_rev 1.0
Index: ValuesDefault
===================================================================
__NAME__ purpose
define default user values
__END__


__NAME__ see also
ScratchDefault
__END__


__NAME__ synopsis
	<arg choice='plain'><replaceable>name</replaceable></arg>
	<arg choice='plain' rep='repeat'><replaceable>value</replaceable></arg>
__END__


__NAME__ description
The directive sets default user session values. Values are kept in
&glos-UserDB; and (of course) override the defaults, but when the user
is not logged in (and hasn't set any
of his preferences for the current session), the defaults will be used.
__END__

__NAME__ example
<example>
  <title>Defining default values</title>
	<para>
	Put the following in &ccf;:
	</para>
<programlisting>
ValuesDefault fname New lname User
ValuesDefault country HR
</programlisting>
	<para>
	Create a test page:
	</para>
<programlisting><![CDATA[
Welcome!<br/>
Your first name is: [value fname]<br/>
Your last name is: [value lname]<br/>
Your country code is: [value country]
]]></programlisting>
<para>
</para>
</example>
__END__




1.1                  xmldocs/refs/Variable


rev 1.1, prev_rev 1.0
Index: Variable
===================================================================
__NAME__ purpose
define an Interchange variable
__END__


__NAME__ see also
VariableDatabase
__END__


__NAME__ synopsis
	<arg choice='plain'><replaceable>NAME</replaceable></arg>
	<arg choice='plain'><replaceable>value</replaceable></arg>
__END__


__NAME__ description
The directive defines a variable that will be available either
globally (if defined in &gcf;) or within a catalog (if defined in &ccf;).
</para><para>
Cariable names are case sensitive, must begin with a capital letter
(uppercase), and can only contain word characters
(that is, a-z, A-Z, 0-9 and _).
</para><para>
Once the variable is defined, it can be accessed using the following
syntax:
<itemizedlist>
	<listitem><para>
	<literal>__<replaceable>NAME</replaceable>__</literal>
	- to only look for a catalog variable
	</para></listitem>
	<listitem><para>
	<literal>@@<replaceable>NAME</replaceable>@@</literal>
	- to only look for a global variable
	</para></listitem>
	<listitem><para>
	<literal>@_<replaceable>NAME</replaceable>_@</literal>
	- to first look for a catalog variable, falling back to global
	unless found
	</para></listitem>
</itemizedlist>
__END__


__NAME__ notes
__END__


__NAME__ example
<example>
  <title>Defining a variable</title>
	<para>
	Put the following in &ccf;:
	</para>
<programlisting>
Variable EMAIL root@&def-domain;
</programlisting>
<para>
</para>
</example>
__END__

More information about the docs mailing list