Permalink
Browse files

- Some new stuff, some placeholders, some updates/fixes to existing f…

…iles
  • Loading branch information...
1 parent 83e19b7 commit 5f3f31fa0903d4a360c4ded54339d6181bc0f5b3 @docelic docelic committed Jun 11, 2005
View
@@ -190,6 +190,9 @@ distclean: clean clean-cache
-rm -rf docbook/auto{refs,glossary,howtos}.ent
look-clean:
-mv $T $T.temporary 2>/dev/null
+commit:
+ make look-clean
+ cvs commit
View
14 TODO
@@ -1,6 +1,8 @@
Outstanding:
=======
+- across glossary entries, insert <section>s
- At least in filters, <<EOR messes up the thing, only < is printed and stops
+s/0-1/No-Yes/
On config directives, include parse_<> function in source context
- See that if 'crypt' is put in see also, all symbols of that name appear
in see also line and their type is distinguished visually.
@@ -80,6 +82,9 @@ guide on setting complete IC environment
explain version naming.. stable/unstable and how 5.3.0 implies next stable
Documentation on how to create replicated catalog online and at your
desktop machine for ultimate convenience.
+- Whereever we count things, (like, valid Locale keys are decimal_point,
+ mon_grouping, price_picture,n_cs_precedes etc.) make that information
+ derived by scripting in stattree, not manually counting
Notes:
@@ -138,3 +143,12 @@ Nice but not fitting the idea
- Suppress inline docs (in source) for items that have xmldocs docs
- In source contexts, for tags, highlight tagCanon and provide <acronym> with
short explanation and example
+
+
+
+In IC source:
+
+- No $Vend::XTrailer on <input>, etc..
+- missing </p>s
+- lowercase SELECTED/CHECKED ?
+
@@ -0,0 +1,4 @@
+code letter
+00-0011 f
+99-102 �
+19-202 a
View
@@ -0,0 +1,69 @@
+Cookies are typically short
+<literal><replaceable>key</replaceable>/<replaceable>value</replaceable></literal> parts supported by the HTTP protocol. Their importance is in the fact that
+the server can send them to clients, and read and modify their value.
+In addition, cookies have their expiry time, which can be set, also by the
+server, to any intended value.
+</para><para>
+Clients can control whether they reject or accept cookies from all or
+some sites, and can enforce their expiry time.
+</para><para>
+Requests arriving from users
+are "anonymous" and unrelated to each other, even of course if they are
+coming from the same user, because the server can't conclude that for sure,
+based on just IP addresses it sees.
+Therefore, cookies are a crucial mechanism for preserving state
+information in programs with web-based interfaces. By reading the session ID
+value (stored in a cookie on client's computer), the server can now recognize
+and differentiate users and ongoing, active sessions.
+</para>
+
+<note>
+ <title>Interchange and its non-dependence on client cookies</title>
+ <para>
+ Large majority of any state-dependent software out there simply
+ <emphasis role='bold'>requires</emphasis> that the clients accept
+ storage and retrieval of cookies. Even solutions put forth eBay require
+ cookies, let alone any much weaker competitors such as Microsoft, or the
+ wanna-be rival "shopping carts".
+ </para><para>
+ &IC;, on the other side, does not require client support for cookies.
+ If the storage of cookies is denied by the client, &IC; appends session
+ information in generated URLs and uses them to continue keeping track of
+ user sessions. (An example session ID "embedded" in an URl looks like
+ <literal>?id=YjiSdrek</literal>).
+ </para><para>
+ One possibly confusing thing is that, by default, &IC; always appends
+ session ID information to the URLs it generates &mdash; even if clients
+ have no cookie-handing problems. For ultimate elegance, you sometimes
+ wish &IC; to stop appending session IDs to non-problematic clients, and we
+ can just say this is possible, as you'll learn from further discussion.
+ </para>
+</note>
+
+<para>
+When a new client accesses its first page from the &IC; catalog, &IC; gives
+it both the requested page and a cookie in return. At that point, &IC; can't
+know whether the client accepted the cookie or not &mdash; it has to wait for
+the client to initiate the next page request.
+If the user sends a cookie back to &IC; (which, as you see, can happen no
+sooner than on second request), &IC; knows the client is cookie-capable and
+there's no <emphasis>need</emphasis> to embed session ID in URLs.
+</para><para>
+Having said the above,
+if the &glos-scratch; variable <mv>mv_no_session_id</mv> is set in their
+session, the session ID will not be appended to the URL. Furthermore,
+on a somewhat related note (the elegance of generated URLs), if the scratch
+value <mv>mv_no_count</mv> is set, then the page count
+(<literal>mv_pc=<replaceable>random</replaceable></literal>) will not be
+appended either (page counter otherwise serves to prevent client browsers
+from caching pages).
+
+<!--
+.No session ID or count will be shown. That makes the URL shown above to be http://machine.company.com/cgi-bin/vlink/shirts.html. Once again, this is on the second page the user accesses, if they are taking and sending cookies. If the user has a pre-existing C<MV_SESSION_ID> or C<MV_USERNAME> cookie from a prior session, the effect will be immediate.
+
+.The C<argument> will be passed to Interchange and placed in the C<mv_arg> session parameter. This allows programming of a conditional page display based on where the link came from. The argument is then available with the tag [data session arg], or the embedded Perl session variable $Session->{arg}. Spaces and some other characters will be escaped with the %NN URL-style notation and unescaped when the argument is read back into the session.
+
+.A bit of magic occurs if Interchange has built a static plain HTML page for the target page. Instead of generating a normal Interchange-parsed page reference, a static page reference will be inserted if the user has accepted and sent back a cookie with the session ID.
+-->
+
+
@@ -0,0 +1,18 @@
+Internationalization (or "I18N") features are those being in relation to
+program's ability to support localized messages (see &glos-locale;),
+currencies, and other region-specific settings.
+</para><para>
+&IC; has a rich set of I18N features that allow conditional message display,
+differing price formats, different currency definitions, price factoring,
+sorting, and other settings. Currently, those features are implemented as
+&IC;-specific, and do not rely on &PERL;'s I18N/L10N features, except for
+the built-in POSIX support (<code>use locale</code>,
+<function>getlocale()</function> and <function>setlocale()</function>).
+</para><para>
+The definitions are maintained in the &ccf; file, through the use of
+Interchange's &conf-Locale; directive. All settings are
+independent for each catalog <emphasis role='bold'>and</emphasis> each user
+visiting that catalog; in other words, customers can access the same catalog
+in an unlimited number of languages, currencies and regional settings.
+</para><para>
+See &glos-locale; glossary entry for more specific information.
View
@@ -0,0 +1,157 @@
+See &glos-internationalization; (I18N) glossary entry for a general
+introduction.
+</para><para>
+Localization (or "I10N") is a process of making an I18N-enabled application
+to use specific locale definition (messages, currency format, etc.).
+</para><para>
+The important thing to have in mind is that &IC; allows customers to access
+the same catalog in an unlimited number of languages, currencies and regional
+settings. What's more, you can switch locales at will, at any time!
+</para><para>
+The simplest and recommended way to set the <emphasis>default</emphasis>
+catalog locale is to define a starting value for <mv>mv_locale</mv> in
+&ccf;:
+<programlisting>
+ScratchDefault mv_locale de_DE
+</programlisting>
+</para><para>
+The <emphasis>per-user</emphasis> locale change can be made permanent
+(for the duration of the user
+session, of course), or temporary (if you're, say, displaying pricing
+information in multiple currencies). See &tag-setlocale; for more discussion
+and examples.
+</para><para>
+Besides using actual "programmatic" methods to set locales, you can achieve
+the same effect by using one terrific feature of the <literal>process</literal>
+&glos-ActionMap;; to display page named "<literal>pricelist</literal>" in
+locale <literal>fr_FR</literal> and currency <literal>en_US</literal>, simply
+call &glos-ITL; tag
+<code>[page process/locale/fr_FR/currency/en_US/page/pricelist]</code>.
+</para><para>
+The localized messages you want to display must previously be defined, of
+course.
+The simplest way to define localized messages is to use
+the &conf-Locale; directive in any of the ways shown:
+<programlisting><![CDATA[
+Locale de_DE "Value setting" Werteinstellung
+Locale de_DE "Search" Suchen
+
+Locale fr_FR <<EOF
+{
+ "Value setting",
+ "Configuration de valeur",
+
+ "Search",
+ "Recherche"
+}
+EOF
+]]></programlisting>
+This method, however, is not practical when you have a lot of messages;
+for robust setups use &conf-LocaleDatabase;.
+</para><para>
+With the above, to display an appropriate translation of "Value setting",
+you would call "<literal>[L]Value setting[/L]</literal>", which would display as
+"<literal>Configuration de valeur</literal>" in
+locale <literal>fr_FR</literal>,
+"<literal>Werteinstellung</literal>" in locale <literal>de_DE</literal>, and as
+a fallback, it would be displayed unmodified as "Value setting" &mdash; if the
+locale is neither
+<literal>fr_FR</literal> not <literal>de_DE</literal>, or no localized string
+for the message was found at all.
+Keep in mind that the "<literal>[L]</literal>" tags must be capitalized &mdash;
+this is done for both processing speed and easy visual distinction within
+pages.
+</para>
+<note>
+ <title>A word on localization tag [L]</title>
+ <para>
+ &IC; tries to substitute text for its localized variant very early in the
+ page serving process &mdash; even before &glos-variable;s are expanded or
+ tags interpolated.
+ </para><para>
+ On one hand, this means you can use variables and tags in localized strings
+ as they will be handled properly.
+ </para><para>
+ On the other hand, it means code constructs like
+ <code>[L][item-data table field][/L]</code> will fail, as &IC; would try to
+ translate "<literal>[item-data table field]</literal>" literally.
+ There's a &tag-loc; tag available which is functionally identical to
+ &tag-L;, but is parsed in normal order and therefore solves the problem.
+ </para>
+</note>
+<para>
+Another way to display localized messages is to supply localization text
+directly within &IC; pages, inside &tag-LC; tag; have a look at this
+intuitive example:
+<programlisting>
+[LC]
+ This is the default text.
+ [fr_FR] Text for the fr_FR locale. [/fr_FR]
+ [de_DE] Text for the de_DE locale. [/de_DE]
+[/LC]
+</programlisting>
+</para><para>
+It's also possible to display completely different pages, based on the
+locale in effect. You probably know the default &conf-HTMLsuffix; in
+&IC; is "<literal>.html</literal>", but you probably do not know it is
+locale-sensitive. With a request for page named "index"
+(<code>[page index]</code>), <literal>fr_FR</literal> locale in effect, and a
+&ccf; directive of
+<programlisting>
+Locale fr_FR HTMLsuffix .fr_FR
+</programlisting>
+&IC; would first look for <filename>pages/index.fr_FR</filename>, and only if
+it's not found go to the usual <filename>pages/index.html</filename>.
+</para>
+
+<note>
+ <title>A general note on locale-sensitivity of config directives</title>
+ <para>
+ We've said &conf-HTMLsuffix; is locale-sensitive, but the story gets
+ much better. In reality, any &conf-Locale; key that matches the name of a
+ config directive, causes the directive to be re-set on locale change &mdash;
+ in other words, all config directives are locale-sensitive! (And now I
+ know you know I am no fan of exclamation marks, but can you say this feature
+ isn't just ingenious?!).
+ </para>
+</note>
+
+
+<section>
+ <title>Effect of locales on sorting</title>
+ <para>
+ &IC; sorting features (such as &mdash; but not only &mdash; the
+ &tag-sort; tag)
+ will honor a setting of <literal>LC_COLLATE</literal>, provided that
+ the operating system and C compiler support locales for POSIX,
+ have the locale definitions set, and the locale chosen matches one of
+ locales available.
+ </para>
+ <para>
+ Suppose we have a
+ <ulink url="files/locales/letters.txt">letters</ulink> database, containing
+ some of the letters of the alphabet.
+ <!--
+ <xi:include parse='text' href='../files/locales/letters.txt'/>
+ -->
+ A code of:
+
+<programlisting><![CDATA[
+[loop 19-202 00-0011 99-102]
+ [sort letters:letter]
+ [loop-data letters letter] [loop-code] <br/>
+[/loop]
+]]></programlisting>
+ would provide different order for locale <literal>C</literal> than
+ <literal>fr_FR</literal>.
+ </para>
+</section>
+
+<para>
+
+<!-- TODO mention script/localize.PL
+A C<localize> script is included with Interchange. It will parse files included on the command line and produce output that can be easily edited to produce localized information. Given an existing file, it will merge new information where appropriate.
+-->
+
+
+
View
@@ -19,7 +19,7 @@ __NAME__ description
A generic &PERL; subroutine mapper which allows mapping of subroutines to
&glos-ActionMap;s,
CoreTags, &conf-UserTag;s,
-&glos-Filter;s,
+&glos-filter;s,
&glos-form-action;s,
&conf-GlobalSub;s,
ItemActions,
View
@@ -0,0 +1,46 @@
+__NAME__ purpose
+allow autologin based on username and password stored in a client cookie
+__END__
+
+
+__NAME__ synopsis
+<group choice='req'>
+ <arg choice='plain'>No</arg>
+ <arg choice='plain'>Yes</arg>
+</group>
+__END__
+
+
+__NAME__ description
+When disabled (set to <literal>No</literal>),
+configuration meta-directives such as
+<literal>#include</literal>,
+<literal>#ifdef</literal> and
+<literal>#ifndef</literal>,
+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.
+</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.
+__END__
+
+
+__NAME__ example: Config parser behavior with ConfigParseComments disabled
+<programlisting>
+ConfigParseComments No
+
+#include comment
+# This, and the above line, are pure comments.
+
+# You better prepare the file named 'comment' for the following one:
+include comment
+</programlisting>
+__END__
+
View
@@ -23,6 +23,8 @@ __END__
__NAME__ notes
The existence of the field is not exactly crucial, but it's important
for say, &glos-flypage;s.
+</para><para>
+It's also useful to set the directive value based on &glos-locale;.
__END__
TODO: Clarify this? "If there is an
@@ -37,3 +39,18 @@ DescriptionField opis
"Opis", for example, is a croatian equivalent of "description".
__END__
+__NAME__ example: Setting DecriptionField depending on current locale
+<programlisting>
+# Establish the default at startup
+DecriptionField description
+
+# Establish locale-specific description field
+Locale fr_FR DecriptionField desc_fr
+</programlisting>
+To fully understand the example and implicitly presented &IC; features, make
+sure you're familiar with &glos-internationalization; and &glos-locale;
+glossary
+entries.
+__END__
+
+
View
@@ -15,9 +15,19 @@ Specify extension to append to the filename when looking for the source
file in the <filename class='directory'>pages/</filename> directory.
__END__
+
+__NAME__ notes
+The way &IC; looks for pages is &glos-locale;-sensitive. Besides the default
+HTML suffix which is set using this &conf-HTMLsuffix; directive, you can
+set locale-dependent suffixes using &conf-Locale;.
+__END__
+
__NAME__ example: Setting HTMLsuffix
<programlisting>
HTMLsuffix .htm
</programlisting>
__END__
+__NAME__ see also
+Locale
+__END__
Oops, something went wrong.

0 comments on commit 5f3f31f

Please sign in to comment.