diff --git a/README b/README index 5a2ea29..69c1d9e 100644 --- a/README +++ b/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, 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 diff --git a/WRITING b/WRITING index a406d6f..71caf57 100644 --- a/WRITING +++ b/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 diff --git a/docbook/literals.ent b/docbook/literals.ent index b0e0965..a860c4e 100644 --- a/docbook/literals.ent +++ b/docbook/literals.ent @@ -49,8 +49,8 @@ diff --git a/refs/AccumulateCode b/refs/AccumulateCode new file mode 100644 index 0000000..33319a9 --- /dev/null +++ b/refs/AccumulateCode @@ -0,0 +1,51 @@ +__NAME__ purpose +fetch Interchange code on-demand from CodeRepository instead of starting up with everything +__END__ + + +__NAME__ synopsis + + No + Yes + +__END__ + + +__NAME__ description +The directive instructs &IC; to fetch code blocks "on-demand" from the +&conf-CodeRepository;, instead of starting up with everything. + +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 +$Global::TagDir/Accumulated/. +When you restart &IC; the next time, these code blocks will be found, +read normally and need not be recompiled on the fly again. + +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;: + +AccumulateCode Yes + +See &conf-CodeRepository; for a complete example. +__END__ + diff --git a/refs/AcrossLocks b/refs/AcrossLocks new file mode 100644 index 0000000..1157f56 --- /dev/null +++ b/refs/AcrossLocks @@ -0,0 +1,32 @@ +__NAME__ purpose + +__END__ + + +__NAME__ synopsis + + No + Yes + +__END__ + + +__NAME__ description +__END__ + +__NAME__ notes +__END__ + +__NAME__ see also +__END__ + +__NAME__ author +__END__ + + +__NAME__ example: Enabling AcrossLocks + +AcrossLocks yes + +__END__ + diff --git a/refs/AutoModifier b/refs/AutoModifier new file mode 100644 index 0000000..052f3d7 --- /dev/null +++ b/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 + + column + +__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 +products database column. + +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 products database. + +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. + +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: + +AutoModifier heavy downloadable + +Also make sure to have the +heavy and +downloadable columns defined in your +products database. +__END__ + diff --git a/refs/CodeRepository b/refs/CodeRepository index f28da66..29f132e 100644 --- a/refs/CodeRepository +++ b/refs/CodeRepository @@ -42,7 +42,7 @@ and ready to go. It also copies the code file to the code/ ($Global::TagDir actually) directory, in the -Accumulated subdirectory tree. +Accumulated/ 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. @@ -111,7 +111,7 @@ __NAME__ author __END__ -__NAME__ example: Enabling CodeRepository +__NAME__ example: Setting up CodeRepository Put the following in &gcf;: AccumulateCode Yes diff --git a/refs/CookieDomain b/refs/CookieDomain new file mode 100644 index 0000000..ebefcdc --- /dev/null +++ b/refs/CookieDomain @@ -0,0 +1,75 @@ +__NAME__ purpose +set domain common to all servers providing Interchange content +__END__ + + +__NAME__ synopsis + + domain + +__END__ + + +__NAME__ see also +CookieDomain,CookieLogin,Cookies,SaveExpire +__END__ + + +__NAME__ description +The directive specifies the domain common to all servers providing +&IC; content. + +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 &def-hostname;, then cookie will be set by +&def-hostname;. + +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 +ssl.&def-domain;, then users would have one +session for &def-hostname; and one for +ssl.&def-domain;. This is undesired, of course. + +To fix the described problem, we need to find part of the +FQDN that is common to all servers (&def-domain; +in our example), and add it as the +domain= parameter to the +Set-Cookie 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 .&def-domain; is valid, but .local +wouldn't be. + +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 +&def-hostname; can set a cookie for itself or the +domain &def-domain;, but it cannot set a cookie +for say, &def-domain;2. 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! + +At least in Mozilla-like browsers, the domain is prefixed with a +dot even if you omit it in the &conf-CookieDomain; specification +(&def-domain; ends up being the same as +.&def-domain;). + +&conf-CookieDomain; accepts a space-separated list of domains to set +cookies for, in which case the Set-Cookie: ... +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 + +CookieLogin .&def-domain; + +__END__ + diff --git a/refs/CookieName b/refs/CookieName index 369be5b..3cfad72 100644 --- a/refs/CookieName +++ b/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 &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 MV_SESSION_ID. + +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 CookieName SESSIONID __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. diff --git a/refs/CookiePattern b/refs/CookiePattern new file mode 100644 index 0000000..35b0f00 --- /dev/null +++ b/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 + regex_pattern +__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: + +CookiePattern \w{8,32} + +In general, however, you should only modify &conf-CookiePattern; default +value if you somehow change the content +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 diff --git a/refs/DifferentSecure b/refs/DifferentSecure new file mode 100644 index 0000000..1b3067b --- /dev/null +++ b/refs/DifferentSecure @@ -0,0 +1,16 @@ +__NAME__ purpose +(obsolete) +__END__ + +__NAME__ synopsis +__END__ + +__NAME__ see also +__END__ + +__NAME__ description +__END__ + +__NAME__ notes +__END__ + diff --git a/refs/EncryptKey b/refs/EncryptKey new file mode 100644 index 0000000..238b4f8 --- /dev/null +++ b/refs/EncryptKey @@ -0,0 +1,34 @@ +__NAME__ purpose +specify default key to use for encryption +__END__ + + +__NAME__ synopsis + key_or_user_identifier +__END__ + + +__NAME__ description +Specify default key to use for encryption. + +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 + +EncryptKey 9B726B71 + +__END__ + + +__NAME__ example: Specifying user identifier to EncryptKey + +EncryptKey racke@linuxia.de + +__END__ + diff --git a/refs/EncryptProgram b/refs/EncryptProgram index 29ae812..8702986 100644 --- a/refs/EncryptProgram +++ b/refs/EncryptProgram @@ -15,8 +15,11 @@ program will be called to perform tasks such as encrypting credit card numbers (if they are stored on the server). Two placeholders can be used, %p and -%f. At encryption time, the former expands to a password, -the latter one to a temporary file name. +%f. At encryption time, +%p +expands to a password, and +%f +to a temporary file name. If &IC; can found a variant of gpg/pgp on your system, it is the default. Setting of none disables diff --git a/refs/NoAbsolute b/refs/NoAbsolute index 1d74e00..99a4cc4 100644 --- a/refs/NoAbsolute +++ b/refs/NoAbsolute @@ -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__ diff --git a/refs/liven_urls.filter b/refs/liven_urls.filter new file mode 100644 index 0000000..31653de --- /dev/null +++ b/refs/liven_urls.filter @@ -0,0 +1,72 @@ +__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. + +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 +perlre1. + +The matching expressions were generated with the help of +Abigail's +Regex for URLs. + +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;. + +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. + +ftp://@host.com/
+ftp://host.com/
+ftp://foo:@host.com/
+ftp://myname@host.dom/%2Fetc/motd
+ftp://myname@host.dom/etc/motd
+ftp://myname@host.dom//etc/motd
+file://vms.host.edu/disk$user/my/notes/note12345.txt
+prospero://host.dom//pros/name
+ldap:///o=University%20of%20Michigan,c=US
+ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US
+ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US?postalAddress
+ldap:///o=University%20of%20Michigan,c=US??sub?(cn=Babs%20Jensen)
+ldap://ldap.itd.umich.edu/c=GB?objectClass?one
+z39.50s://melvyl.ucop.edu/cat
+z39.50r://melvyl.ucop.edu/mags?elecworld.v30.n19
+z39.50r://cnidr.org:2100/tmf?bkirch_rules__a1;esn=f;rs=marc
+mid:foo4%25foo1@bar.net
+cid:foo4*foo1@bar.net
+mid:960830.1639@XIson.com/partA.960830.1639@XIson.com
+[/filter] +]]> + +If some of the links are not clickable, then the appropriate regular +expressions have been deactivated in the filter source. +__END__ + +