Permalink
Browse files

* Went over the rest of configuration directives, polished the text,

  fixed a few small typos, simplified synopsis lines
  • Loading branch information...
1 parent c730efb commit 267221caff58708386ce70cd3fe2766298f4a72b @docelic docelic committed Nov 6, 2006
Showing with 523 additions and 588 deletions.
  1. +2 −0 TODO
  2. +1 −0 docbook/literals.ent
  3. +19 −0 glossary/database
  4. +1 −0 guides/search.xml
  5. +4 −2 refs/CartTriggerQuantity
  6. +17 −14 refs/ChildLife
  7. +4 −2 refs/ClearCache
  8. +1 −0 refs/CodeDef
  9. +17 −12 refs/CodeRepository
  10. +2 −1 refs/CommonAdjust
  11. +1 −1 refs/ConfDir
  12. +1 −1 refs/ConfigDatabase
  13. +2 −1 refs/ConfigDir
  14. +10 −10 refs/ConfigParseComments
  15. +2 −0 refs/CookieDomain
  16. +9 −5 refs/CookieLogin
  17. +2 −0 refs/CookieName
  18. +6 −1 refs/CookiePattern
  19. +7 −5 refs/Cookies
  20. +7 −2 refs/CreditCardAuto
  21. +1 −0 refs/CustomShipping
  22. +1 −1 refs/DataTrace
  23. +0 −1 refs/Database
  24. +7 −5 refs/DatabaseAuto
  25. +6 −5 refs/DatabaseAutoIgnore
  26. +2 −2 refs/DatabaseDefault
  27. +3 −3 refs/DebugFile
  28. +1 −3 refs/DefaultLocale
  29. +2 −4 refs/DefaultShipping
  30. +1 −3 refs/DeleteDirective
  31. +4 −1 refs/DeliverImage
  32. +6 −6 refs/DescriptionField
  33. +1 −1 refs/DirConfig
  34. +1 −3 refs/DirectoryIndex
  35. +1 −1 refs/DiscountSpacesOn
  36. +1 −1 refs/DisplayErrors
  37. +7 −6 refs/DomainTail
  38. +5 −4 refs/DumpAllCfg
  39. +1 −1 refs/DumpStructure
  40. +1 −3 refs/DynamicData
  41. +1 −1 refs/EncryptKey
  42. +3 −0 refs/EncryptProgram
  43. +1 −3 refs/Environment
  44. +1 −3 refs/ErrorFile
  45. +1 −3 refs/ExecutionLocale
  46. +4 −7 refs/External
  47. +3 −3 refs/ExtraSecure
  48. +1 −3 refs/Feature
  49. +1 −3 refs/FeatureDir
  50. +10 −7 refs/Filter
  51. +6 −7 refs/FormIgnore
  52. +3 −3 refs/FractionalItems
  53. +5 −5 refs/FullUrl
  54. +2 −4 refs/Glimpse
  55. +9 −13 refs/GlobalSub
  56. +3 −5 refs/HTMLsuffix
  57. +1 −3 refs/HammerLock
  58. +3 −4 refs/History
  59. +1 −1 refs/HitCount
  60. +2 −2 refs/HostnameLookups
  61. +2 −4 refs/HotDBI
  62. +2 −4 refs/HouseKeeping
  63. +2 −4 refs/ImageAlias
  64. +4 −6 refs/ImageDir
  65. +1 −3 refs/ImageDirSecure
  66. +6 −2 refs/Inet_Mode
  67. +2 −1 refs/IpHead
  68. +1 −3 refs/IpQuad
  69. +4 −0 refs/Jobs
  70. +2 −0 refs/Locale
  71. +1 −3 refs/LocaleDatabase
  72. +4 −4 refs/LockType
  73. +1 −3 refs/LockoutCommand
  74. +4 −0 refs/MailOrderTo
  75. +4 −4 refs/Mall
  76. +1 −5 refs/MaxRequestsPerChild
  77. +1 −3 refs/MaxServers
  78. +1 −1 refs/NoAbsolute
  79. +3 −3 refs/NoCache
  80. +3 −17 refs/NoImport
  81. +3 −8 refs/NoImportExternal
  82. +3 −3 refs/NoSearch
  83. +1 −3 refs/NonTaxableField
  84. +1 −3 refs/OfflineDir
  85. +6 −6 refs/OnFly
  86. +1 −3 refs/OrderCounter
  87. +1 −3 refs/OrderLineLimit
  88. +3 −4 refs/OrderProfile
  89. +1 −3 refs/OrderReport
  90. +5 −1 refs/PGP
  91. +3 −3 refs/PIDcheck
  92. +1 −3 refs/PIDfile
  93. +2 −4 refs/PageDir
  94. +3 −4 refs/PageSelectField
  95. +9 −9 refs/ParseVariables
  96. +1 −3 refs/Password
  97. +1 −3 refs/PermanentDir
  98. +1 −1 refs/PreFork
  99. +3 −3 refs/PriceCommas
  100. +1 −3 refs/PriceDivide
  101. +2 −7 refs/PriceField
  102. +1 −3 refs/ProcessPage
  103. +1 −3 refs/ProductDir
  104. +1 −3 refs/ProductFiles
  105. +1 −3 refs/Profiles
  106. +1 −1 refs/ReadPermission
  107. +1 −3 refs/RemoteUser
  108. +5 −7 refs/Require
  109. +3 −5 refs/RobotHost
  110. +3 −5 refs/RobotIP
  111. +6 −3 refs/RobotLimit
  112. +3 −5 refs/RobotUA
  113. +1 −1 refs/SOAP
  114. +1 −3 refs/SOAP_Host
  115. +3 −5 refs/SOAP_MaxRequests
  116. +3 −5 refs/SOAP_Perms
  117. +2 −3 refs/SOAP_Socket
  118. +1 −3 refs/SOAP_StartServers
  119. +3 −4 refs/SafeUntrap
  120. +1 −3 refs/SaveExpire
  121. +2 −1 refs/ScratchDefault
  122. +9 −6 refs/ScratchDir
  123. +7 −4 refs/SearchProfile
  124. +1 −3 refs/SecureURL
  125. +1 −3 refs/SendMailProgram
  126. +2 −2 refs/SeparateItems
  127. +7 −4 refs/SessionDB
  128. +1 −3 refs/SessionDatabase
  129. +4 −5 refs/SessionExpire
  130. +1 −3 refs/SessionLockFile
  131. +8 −8 refs/SessionType
  132. +1 −3 refs/SetGroup
  133. +7 −4 refs/ShowTimes
  134. +1 −3 refs/SocketFile
  135. +1 −3 refs/SocketPerms
  136. +6 −1 refs/SpecialPage
  137. +1 −3 refs/SpecialPageDir
  138. +1 −1 refs/SpecialSub
  139. +1 −3 refs/StartServers
  140. +1 −1 refs/Static
  141. +1 −1 refs/StaticAll
  142. +1 −1 refs/StaticDBM
  143. +1 −3 refs/StaticDepth
  144. +1 −3 refs/StaticDir
  145. +1 −1 refs/StaticFly
  146. +1 −3 refs/StaticPage
  147. +1 −3 refs/StaticPath
  148. +1 −3 refs/StaticPattern
  149. +1 −3 refs/StaticSuffix
  150. +1 −5 refs/Sub
  151. +2 −2 refs/Suggest
  152. +7 −8 refs/TableRestrict
  153. +6 −6 refs/TagDir
  154. +7 −1 refs/TagGroup
  155. +2 −2 refs/TagInclude
  156. +5 −5 refs/TaxInclusive
  157. +2 −4 refs/TaxShipping
  158. +1 −3 refs/TcpHost
  159. +1 −1 refs/TcpMap
  160. +2 −4 refs/TemplateDir
  161. +1 −1 refs/TolerateGet
  162. +1 −3 refs/TrackFile
  163. +7 −6 refs/TrackPageParam
  164. +1 −3 refs/TrustProxy
  165. +1 −1 refs/Unix_Mode
  166. +1 −3 refs/UpsZoneFile
  167. +2 −4 refs/UrlSepChar
  168. +1 −3 refs/UseModifier
  169. +1 −1 refs/UserControl
  170. +1 −1 refs/UserDatabase
  171. +4 −4 refs/ValuesDefault
  172. +6 −2 refs/Variable
  173. +1 −3 refs/VariableDatabase
  174. +1 −3 refs/VendURL
  175. +7 −6 refs/WideOpen
  176. +3 −3 refs/Windows
  177. +1 −1 refs/WritePermission
  178. +4 −4 refs/XHTML
  179. +1 −1 refs/area/control
View
2 TODO
@@ -15,6 +15,8 @@
listed under See Also.
- in search.xml replace mv_ listitems with sections so they're listed in TOC
- note in configuration glossentry to use '' to skip values
+- Check ConfigDatabase and DirectiveDatabase. Is description correct? One seems to be wrong
+- preprocessor directives in configuration ?
Outstanding:
=======
View
@@ -97,6 +97,7 @@ option) any later version.</para>">
<!-- ENTITIES FOR CORE DEVELOPERS, FOR AUTHOR LINES-->
<!ENTITY racke "<ulink url='mailto:racke@linuxia.de'>Stefan Hornburg (Racke)</ulink>">
<!ENTITY docelic "<ulink url='mailto:docelic@icdevgroup.org'>Davor Ocelic</ulink>">
+<!ENTITY yure "<ulink url='mailto:jure.kodzoman@spinstorm.com'>Jure Kodzoman</ulink>">
<!ENTITY mheins "Mike Heins">
<!ENTITY jon "Jon Jensen">
<!ENTITY jonc "Jonathan Clark">
View
@@ -460,3 +460,22 @@ Term definitions:
</section>
<para>
+
+
+
+<!--
+
+For &GDBM; &glos-database;s, the import would ordinarily happen when the
+gdbm file is deleted, a change in appropriate text source file is detected,
+&IC; is (re)started, or the catalog is reconfigured. &glos-SQL; databases
+are imported only once, at first configuration.
+
+
+<emphasis>External</emphasis> database types are DBI (&MYSQL;, &PGSQL;,
+&ORACLE; etc.) and LDAP (&OPENLDAP; etc.). In contrast,
+<emphasis>internal</emphasis> database types are DBM variants
+(&GDBM;, &BDBM;, SDBM) and in-memory.
+
+
+table= and sql parser
+-->
View
@@ -569,6 +569,7 @@ icdevgroup.conf</literal>.
<literal>mv_return_fields</literal>
(rf, <literal></literal>/<literal></literal>,
default <literal></literal>) &mdash;
+ (specification of <literal>:*</literal> indicates "all fields").
</para>
</listitem>
View
@@ -8,8 +8,10 @@ CartTrigger
__END__
__NAME__ synopsis
-<arg choice='plain'>No</arg>
-<arg choice='plain'>Yes</arg>
+<group choice='plain'>
+ <arg choice='plain'>No</arg>
+ <arg choice='plain'>Yes</arg>
+</group>
__END__
View
@@ -4,7 +4,7 @@ __END__
__NAME__ see also
-PreFork,MaxServers,PIDcheck,PIDfile,HouseKeeping
+MaxRequestsPerChild,PreFork,MaxServers,PIDcheck,PIDfile
__END__
@@ -14,28 +14,31 @@ __END__
__NAME__ description
-Occasionally, in &conf-PreFork; mode, you will find child processes that get
-"starved", in other words they never seem to win the battle and receive a
-page request so they just sit there forever.
+&IC; page servers are, by default, periodically restarted to make sure
+there are no problems arising from long-running processes
+(such as memory leaks).
</para><para>
-The &conf-ChildLife; directive times out a page server after a period
-of time.
+In general, periodic &IC; page server re-starting is handled by the
+&conf-MaxRequestsPerChild; configuration directive which re-starts
+each server after a specified number of served client requests.
</para><para>
-If &conf-ChildLife; is not set, the default, the server will act just
-like it did before, stuck in that internal loop forever until
-<command>kill -9</command> happens.
+However, when &conf-PreFork; &glos-ic-run-mode; is used, some page servers
+never win the page server "selection battle"; they never get to serve a page
+request and consequently they are never restarted by &conf-MaxRequestsPerChild;.
+This is why the &conf-ChildLife; directive restarts
+a page server on an unconditional, periodic basis to make sure all servers
+are re-started from time to time.
</para><para>
-All the directive does is set the start_time of the server, and then when
-&conf-HouseKeeping; gets triggered, it checks the current time and terminates
-the server (just like &conf-MaxRequestsPerChild;, basically) if it
-has expired.
+If &conf-ChildLife; is not set, the "starved" page servers will act just
+like they did before; get stuck in an internal loop forever until
+<command>kill -9</command> on the process happens.
</para><para>
This should clear up the problem where people see with a growing number of
servers over time.
__END__
__NAME__ notes
-The directive is only used when &IC; is in <literal>PreFork</literal>
+The directive should only be used when &IC; is in <literal>PreFork</literal>
&glos-ic-run-mode;.
</para><para>
The directive value can be any Interchange &glos-interval;.
View
@@ -3,8 +3,10 @@ __NAME__ purpose
__END__
__NAME__ synopsis
-<arg choice='plain'>No</arg>
-<arg choice='plain'>Yes</arg>
+<group choice='plain'>
+ <arg choice='plain'>No</arg>
+ <arg choice='plain'>Yes</arg>
+</group>
__END__
__NAME__ see also
View
@@ -20,6 +20,7 @@ _END__
__NAME__ missing
synopsis
replace plain words with entities in description
+more description
__END__
__NAME__ description
View
@@ -11,14 +11,14 @@ __END__
__NAME__ description
There is a huge base of &IC; code (collection of &conf-UserTag;s and
&conf-CodeDef;s) included in the default installation.
-Much of it is not needed in even the '&std-catalog;' catalog with full
-user interface (UI). This causes a larger memory profile than necessary.
+Much of it is not needed for the usual installations,
+causing a larger process memory profile than necessary.
</para><para>
-Furthermore, it is difficult to determine from the &IC; pages what code is
-needed (especially when an &glos-ITL; tag calls
+Furthermore, it is hard to manually determine what subset of code is required,
+especially when an &glos-ITL; tag calls
<code>$Tag-&gt;<replaceable>TAGNAME</replaceable>()</code>
-which calls a filter which calls some sort of action &mdash;
-you get the picture).
+which calls some filter which calls some sort of an action &mdash;
+you get the picture.
</para><para>
A feature was needed to allow building catalogs with a more optimal
set of code than just "everything". And as we'll see in a second,
@@ -65,23 +65,23 @@ calls another <code>$Tag-&gt;<replaceable>TAGNAME</replaceable>()</code> within.
not much to be done about it. The good news is that the error should
go away after &conf-HouseKeeping; seconds, when the tag gets compiled by the
master.
-The &tag-area;, &tag-tmp;, &tag-tmpn;, and &tag-image; tags are known to
-fail in this manner in the '&std-catalog;' catalog.
+&tag-area;, &tag-tmp;, &tag-tmpn;, and &tag-image; are examples of tags known
+to fail in this manner.
Tags that are frequently called
in this fashion should probably be manually placed in directory
<filename class='directory'>code/Vital/</filename> and not
be accumulated "by chance".
-This temporary failure could be avoided by listing &glos-catalog; in the
+Anyway, this temporary failure could be avoided by listing &glos-catalog; in the
&conf-AllowGlobal; directive, and it
-might be possible to make a directive that allows &conf-AllowGlobal; for
+might also be possible to make a directive that allows &conf-AllowGlobal; for
a catalog automatically, when in &conf-AccumulateCode; mode.
(If you don't want to trade immediate code loading for the lack of
&conf-AllowGlobal; protection, then just set &conf-HouseKeeping; to
something like <literal>20 seconds</literal> &mdash; and
only do it on your development system!)
</para><para>
-One convenient side-effect is that you can easily load new code
-"on the fly" by simply adding files to the &conf-CodeRepository;
+One convenient side-effect is that you can easily load new code (such as new
+&IC; tags) "on the fly" by simply adding files to the &conf-CodeRepository;
directory. This alleviates the need for &IC; server restart.
It might also be possible to dynamically <emphasis role='bold'>remove and
load</emphasis> code from the server in this manner, but this has yet
@@ -132,3 +132,8 @@ $ mv /usr/interchange/code/* /usr/interchange/code.pool/
</programlisting>
__END__
+
+__NAME__ missing
+Hot-link MapRoutine word
+provide link to example pricing.txt
+__END__
View
@@ -31,7 +31,8 @@ __NAME__ example: The pricing database
Most of the practical setups will use a separate (<emphasis>outboard</emphasis>)
database to define pricing-related options. This <emphasis>could</emphasis>
be all done in the <database>products</database> database as well, but let's
-stick to a visually cleaner implementation.
+stick to a visually cleaner implementation. (<emphasis role='bold'>This
+database is used by other examples above!)</emphasis>
</para><para>
An example <database>pricing</database> database looks like this:
View
@@ -4,7 +4,7 @@ __END__
__NAME__ synopsis
-<arg choice='plain'>directory</arg>
+<arg choice='plain'><replaceable>directory_name</replaceable></arg>
__END__
View
@@ -1,5 +1,5 @@
__NAME__ purpose
-specify database which should hold definitions usually found in catalog.cfg
+specify database holding definitions usually found in catalog.cfg
__END__
View
@@ -45,7 +45,8 @@ __END__
__NAME__ example: Setting directive value from a file
In combination with the above example, the following would read the
-directive value from file <filename>variables/mailorderto</filename>.
+directive value from file <filename>variables/mailorderto</filename>
+(relative to the &glos-CATROOT;, of course).
<programlisting>
MailOrderTo &lt;mailorderto
</programlisting>
View
@@ -4,13 +4,15 @@ __END__
__NAME__ synopsis
-<arg choice='plain'>Yes</arg>
-<arg choice='plain'>No</arg>
+<group choice='plain'>
+ <arg choice='plain'>Yes</arg>
+ <arg choice='plain'>No</arg>
+</group>
__END__
__NAME__ notes
This directive is obsolete as of &IC; 5.5.0, and the behavior is
-as if <code>ConfigParseComments Yes</code> was specified.
+as if <code>ConfigParseComments No</code> was specified.
__END__
@@ -23,15 +25,13 @@ configuration meta-directives such as
are treated as pure comments with no specific meaning.
</para><para>
However, since those were originally borrowed from the C preprocessor,
-and true to their C heritage - they started with an '#' (hash) character
-in &IC; versions up to and including 4.6.
+and, true to their C heritage, they started with an '<literal>#</literal>'
+(hash) character in &IC; versions up to and including 4.6.
</para><para>
This was inconvenient for newcomers who were easily misguided by thinking
-those were just comments, so Interchange versions 4.7 and up support
-meta-directives without the hash prefix.
-</para><para>
-To preserve compatibility, the default is still <literal>Yes</literal>,
-but you should omit the '#' (hash) in new configuration files.
+those were just comments, so Interchange versions 4.7 and up were changed
+to use the meta-directives <emphasis role='bold'>without the hash
+prefix</emphasis>.
__END__
View
@@ -64,6 +64,8 @@ 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>
+For a complete discussion on cookies, see &glos-cookie; glossary entry.
__END__
__NAME__ example: Specifying CookieDomain
View
@@ -4,8 +4,10 @@ __END__
__NAME__ synopsis
-<arg choice='plain'>No</arg>
-<arg choice='plain'>Yes</arg>
+<group choice='plain'>
+ <arg choice='plain'>No</arg>
+ <arg choice='plain'>Yes</arg>
+</group>
__END__
@@ -26,10 +28,12 @@ __END__
__NAME__ notes
To cause the cookie to be generated originally,
-<mv>mv_cookie_password</mv> and/or <mv>mv_cookie_username</mv> must be set.
+<mv>mv_cookie_password</mv> and/or <mv>mv_cookie_username</mv> must be set
+to a &glos-true; value.
The former causes both username and password to be saved; the latter just
-the username. This, however, is done automatically so you don't have to worry
-about it explicitly.
+the username.
+</para><para>
+For a complete discussion on cookies, see &glos-cookie; glossary entry.
__END__
TODO: Does the above really happen automatically - when you turn on
CookieLogin, or you need ScratchDefault mv_cookie_password 1 or some thing like
View
@@ -31,6 +31,8 @@ or domain name.
</para><para>
If the cookie is generated by another program and &conf-CookieName;
is set appropriately, &IC; will take it over without modification.
+</para><para>
+For a complete discussion on cookies, see &glos-cookie; glossary entry.
__END__
__NAME__ example: Defining CookieName
View
@@ -4,7 +4,7 @@ __END__
__NAME__ see also
-CookieName
+CookieName, Limit
__END__
@@ -16,6 +16,9 @@ __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;.
+</para><para>
+This is useful in extracting session IDs out of cookies generated by programs
+other than &IC;.
__END__
__NAME__ notes
@@ -36,6 +39,8 @@ 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).
+</para><para>
+For a complete discussion on cookies, see &glos-cookie; glossary entry.
__END__
View
@@ -1,25 +1,27 @@
__NAME__ purpose
-specify whether Interchange will try to land session cookies in client browsers
+specify whether Interchange will try to send session cookies to client browsers
__END__
__NAME__ synopsis
-<arg choice='plain'>Yes</arg>
-<arg choice='plain'>No</arg>
+<group choice='plain'>
+ <arg choice='plain'>Yes</arg>
+ <arg choice='plain'>No</arg>
+</group>
__END__
__NAME__ description
The directive determines whether &IC; will send &glos-cookie; to the client and
read it back to keep track of &glos-session; ID.
</para><para>
-For a complete discussion, see &glos-cookie; glossary entry.
+For a complete discussion on cookies, see &glos-cookie; glossary entry.
__END__
Caching, timed builds, and static page building will never be in effect unless
this directive is enabled.
__NAME__ see also
-CookieLogin,SaveExpire
+CookieLogin,SaveExpire,CookieDomain,CookiePattern,CookieName
__END__
View
@@ -8,8 +8,10 @@ EncryptProgram, PGP
__END__
__NAME__ synopsis
-<arg choice='plain'>No</arg>
-<arg choice='plain'>Yes</arg>
+<group choice='plain'>
+ <arg choice='plain'>No</arg>
+ <arg choice='plain'>Yes</arg>
+</group>
__END__
@@ -26,3 +28,6 @@ CreditCardAuto Yes
</programlisting>
__END__
+__NAME__ missing
+Saving CC info where ?
+__END__
Oops, something went wrong.

0 comments on commit 267221c

Please sign in to comment.