[docs] xmldocs - docelic modified 3 files

docs at icdevgroup.org docs at icdevgroup.org
Sat Jun 11 04:53:42 EDT 2005


User:      docelic
Date:      2005-06-11 08:53:42 GMT
Modified:  .        TODO
Modified:  glossary cookie
Modified:  refs     CookieLogin
Log:
Some more changes, finishing off for today

Revision  Changes    Path
1.72      +3 -0      xmldocs/TODO


rev 1.72, prev_rev 1.71
Index: TODO
===================================================================
RCS file: /var/cvs/xmldocs/TODO,v
retrieving revision 1.71
retrieving revision 1.72
diff -u -r1.71 -r1.72
--- TODO	11 Jun 2005 08:28:59 -0000	1.71
+++ TODO	11 Jun 2005 08:53:41 -0000	1.72
@@ -2,6 +2,9 @@
 =======
 - across glossary entries, insert <section>s
 - At least in filters, <<EOR messes up the thing, only < is printed and stops
+- bin/refs-autogen should report which refs/* files have comments in them
+  (text outside __NAME__ __END__ markers). It indicates there's a work to do
+  on the item
 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



1.2       +25 -9     xmldocs/glossary/cookie


rev 1.2, prev_rev 1.1
Index: cookie
===================================================================
RCS file: /var/cvs/xmldocs/glossary/cookie,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- cookie	11 Jun 2005 08:29:00 -0000	1.1
+++ cookie	11 Jun 2005 08:53:41 -0000	1.2
@@ -3,6 +3,9 @@
 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.
+Whether &IC; will try to land session cookies in clients' browsers is
+determined by the &conf-Cookies; directive, and their default expiry time
+is set by &conf-SaveExpire;.
 </para><para>
 Clients can control whether they reject or accept cookies from all or 
 some sites, and can enforce their expiry time.
@@ -10,7 +13,7 @@
 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.
+based on just the 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
@@ -23,20 +26,27 @@
 	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".
+	cookies, let alone any much weaker competitors such as Microsoft or the
+	wanna-be rivalling "shopping carts".
 	</para><para>
+	<emphasis role='bold'>
 	&IC;, on the other side, does not require client support for cookies.
+	</emphasis>
 	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
+	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.
+	Session IDs embedded in URLs should theoretically be equivalent	to cookies,
+	and they <emphasis>almost</emphasis> are. The drawback is namely the fact
+	that once you visit a non-&IC; page, you lose the <literal>id=</literal>
+	argument from the URL (because &IC; isn't there to insert it appropriately).
+	The end result is the users will lose their session information when they
+	return back to &IC; pages, unless they copied the session ID information and
+	put it back in the URL manually (which is a bit too much to expect from 
+	random visitors). In practice, this isn't a problem when you're
+	not sending users out of &IC; space, and when you build the site with this
+	fact in mind.
 	</para>
 </note>
 
@@ -48,6 +58,12 @@
 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>
+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><para>
 Having said the above,
 if the &glos-scratch; variable <mv>mv_no_session_id</mv> is set in their



1.2       +25 -26    xmldocs/refs/CookieLogin


rev 1.2, prev_rev 1.1
Index: CookieLogin
===================================================================
RCS file: /var/cvs/xmldocs/refs/CookieLogin,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- CookieLogin	11 Jun 2005 08:29:00 -0000	1.1
+++ CookieLogin	11 Jun 2005 08:53:41 -0000	1.2
@@ -5,42 +5,41 @@
 
 __NAME__ synopsis
 <group choice='req'>
-	<arg choice='plain'>No</arg>
-	<arg choice='plain'>Yes</arg>
+	<arg choice='plain'>0</arg>
+	<arg choice='plain'>1</arg>
 </group>
 __END__
 
 
+__NAME__ see also
+CookieDomain,CookieLogin,Cookies,SaveExpire
+__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.
+The directive allows &IC; to save users' authentication info (username/password)
+in a &glos-cookie;. Cookie expiration time is set by &conf-SaveExpire; and is
+renewed each time they log in.
 </para><para>
-To preserve compatibility, the default is still <literal>Yes</literal>,
-but you should omit the '#' (hash) in new configuration files.
+If the login and password information can be read from a cookie, then 
+users can be logged in to the site automatically as they visit it.
 __END__
 
 
-__NAME__ example: Config parser behavior with ConfigParseComments disabled
-<programlisting>
-ConfigParseComments No
-
-#include comment
-# This, and the above line, are pure comments.
+__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.
+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.
+__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 
+that?
 
-# You better prepare the file named 'comment' for the following one:
-include comment
+__NAME__ example: Enabling CookieLogin
+<programlisting>
+CookieLogin 1
 </programlisting>
 __END__
 








More information about the docs mailing list