[Zope3-checkins] SVN: Zope3/branches/ZopeX3-3.0/src/zope/ Convert
more docs to ReST.
Fred L. Drake, Jr.
fred at zope.com
Tue Jul 6 17:00:02 EDT 2004
Log message for revision 26143:
Convert more docs to ReST.
-=-
Deleted: Zope3/branches/ZopeX3-3.0/src/zope/app/session/session.stx
===================================================================
--- Zope3/branches/ZopeX3-3.0/src/zope/app/session/session.stx 2004-07-06 20:57:26 UTC (rev 26142)
+++ Zope3/branches/ZopeX3-3.0/src/zope/app/session/session.stx 2004-07-06 21:00:02 UTC (rev 26143)
@@ -1,55 +0,0 @@
-Session Support
----------------
-
-Sessions allow us to fake state over a stateless protocol - HTTP. We do this
-by having a unique identifier stored across multiple HTTP requests, be it
-a cookie or some id mangled into the URL.
-
-The IBrowserIdManager Utility provides this unique id. It is responsible
-for propagating this id so that future requests from the browser get
-the same id (eg. by setting an HTTP cookie)
-
-ISessionDataContainer Utilities store session data. The ISessionDataContainer
-is responsible for expiring data.
-
-ISessionDataContainer[product_id] returns ISessionProductData
-ISessionDataContainer[product_id][browser_id] returns ISessionData
-
-ISession(request)[product_id] returns ISessionData
-
-An ISession determines what ISessionDataContainer to use by looking
-up an ISessionDataContainer using the product_id as the name, and
-falling back to the unnamed ISessionDataContainer utility. This allows
-site administrators to select which ISessionDataContainer a particular
-product stores its session data in by registering the utility with
-the relevant name(s).
-
-Python example::
-
- >>> browser_id = IBrowserId(request)
-
- >>> session_data = ISession(request)['zopeproducts.fooprod']
- >>> session_data['color'] = 'red'
-
- or for the adventurous....
-
- >>> explicit_dc = getUtility(ISessionDataContainer, 'zopeproducts.fooprod')
- >>> session_data = explicit_dc['zopeproducts.fooprod'][str(browser_id)]
- >>> session_data = Session(explicit_dc, browser_id)['zopeproducts.fooprod']
- >>> session_data['color'] = 'red'
-
-
-Page Template example::
-
- XXX: Needs update when TALES adapter syntax decided
-
- <tal:x condition="exists:session/zopeproducts.fooprod/count">
- <tal:x condition="python:
- session['zopeproducts.fooprod']['count'] += 1" />
- </tal:x>
- <tal:x condition="not:exists:session/zopeprodicts.fooprod/count">
- <tal:x condition="python:
- session['zopeproducts.fooprod']['count'] = 1 />
- </tal:x>
- <span content="session/zopeproducts.fooprod/count">6</span>
-
Copied: Zope3/branches/ZopeX3-3.0/src/zope/app/session/session.txt (from rev 26138, Zope3/branches/ZopeX3-3.0/src/zope/app/session/session.stx)
===================================================================
--- Zope3/branches/ZopeX3-3.0/src/zope/app/session/session.stx 2004-07-06 20:18:47 UTC (rev 26138)
+++ Zope3/branches/ZopeX3-3.0/src/zope/app/session/session.txt 2004-07-06 21:00:02 UTC (rev 26143)
@@ -0,0 +1,57 @@
+Session Support
+---------------
+
+Sessions allow us to fake state over a stateless protocol - HTTP. We
+do this by having a unique identifier stored across multiple HTTP
+requests, be it a cookie or some id mangled into the URL.
+
+The `IBrowserIdManager` utility provides this unique id. It is
+responsible for propagating this id so that future requests from the
+browser get the same id (such as by setting an HTTP cookie)
+
+`ISessionDataContainer` utilities store session data. The
+`ISessionDataContainer` is responsible for expiring data.
+
+``ISessionDataContainer[product_id]`` returns `ISessionProductData`
+
+``ISessionDataContainer[product_id][browser_id]`` returns
+`ISessionData`
+
+``ISession(request)[product_id]`` returns `ISessionData`
+
+An `ISession` determines what `ISessionDataContainer` to use by
+looking up an `ISessionDataContainer` using the product_id as the
+name, and falling back to the unnamed `ISessionDataContainer` utility.
+This allows site administrators to select which
+`ISessionDataContainer` a particular product stores its session data
+in by registering the utility with the relevant name(s).
+
+Python example::
+
+ >>> browser_id = IBrowserId(request)
+
+ >>> session_data = ISession(request)['zopeproducts.fooprod']
+ >>> session_data['color'] = 'red'
+
+ or for the adventurous....
+
+ >>> explicit_dc = getUtility(ISessionDataContainer, 'zopeproducts.fooprod')
+ >>> session_data = explicit_dc['zopeproducts.fooprod'][str(browser_id)]
+ >>> session_data = Session(explicit_dc, browser_id)['zopeproducts.fooprod']
+ >>> session_data['color'] = 'red'
+
+
+Page Template example::
+
+ XXX: Needs update when TALES adapter syntax decided
+
+ <tal:x condition="exists:session/zopeproducts.fooprod/count">
+ <tal:x condition="python:
+ session['zopeproducts.fooprod']['count'] += 1" />
+ </tal:x>
+ <tal:x condition="not:exists:session/zopeprodicts.fooprod/count">
+ <tal:x condition="python:
+ session['zopeproducts.fooprod']['count'] = 1 />
+ </tal:x>
+ <span content="session/zopeproducts.fooprod/count">6</span>
+
Deleted: Zope3/branches/ZopeX3-3.0/src/zope/i18n/i18nobject.stx
===================================================================
--- Zope3/branches/ZopeX3-3.0/src/zope/i18n/i18nobject.stx 2004-07-06 20:57:26 UTC (rev 26142)
+++ Zope3/branches/ZopeX3-3.0/src/zope/i18n/i18nobject.stx 2004-07-06 21:00:02 UTC (rev 26143)
@@ -1,63 +0,0 @@
-I18n Objects
-
- I18n objects are used to internationalize content that cannot be translated
- via messages. The problem is three fold:
-
- - Internationalize an object iteself. The best example is an Image. Often
- people put text into an image that needs to be localized, but since it
- is a picture the text cannot be retrieved as a string. You therefore
- will need a mechanism to create a different version of the object for every
- language. (Note: This behavior is the same as currently implemented in
- the ZBabelObject.)
-
- - Internationalize fractions of the content. Let's say for example you
- wanted to internationalize the DublinCore information of your content
- object. In order for this to work out you need to have an
- I18n-supportive AttributeAnnotation. Solving this use case would be
- similar to some of the work David Juan did with
- InternationalizedContent in Localizer.
-
- - Formatting Objects. This problem involves converting basic or complex
- types into a localized format. Good examples for this are decimal
- numbers and date/time objects. In this case you would like to specify a
- format via a templating expression and then pass the object to the
- formatter to apply the parsed template. Initial steps for implementing
- the template parser have been already taken, therefore we only need to
- develop some interfaces and unittests here, so the parser developer
- (which will use the ICU C/C++ libraries) will (choose?) what parts of the parser
- to wrap for Python.
-
-
- The first two problems are very similar and can actually share the same
- interface for the language negotiation and redirection of the content
- request. I would therefore propose to have a II18nContent interface that
- somehow specifies how to get the and then redirect the call to the correct
- local content.
-
-
- I18nObject
-
- There will be an interface called II18nObject (which inherits I18nContent
- of course), which is a cameleon-like container, as it adapts to the
- properties of the contained object type. In order to accomplish all this,
- you will have to implement your own traverser which looks up the correct
- subobject.
-
-
- I18nAttributeAnnotation
-
- This object will basically provide an internationalized version of
- Zope.App.OFS.AttributeAnnotations. which will be accomplished in a similar
- manner as the I18nObject.
-
-
- One issue left to solve is how to know the language when we need to make the
- decision. These objects are **not** Views, therefore they do not know about
- the request variable.
-
- One way to solve the issue would be that I18nAttributeAnnotation, for
- example, would not actually implement the IAnnotations interface, but that
- there would be an Adapter converting the II18nAnnotations to
- IAnnotations. Since adapters are short-lived (meaning they are initialized
- for a particular call), we can safely store some language information in
- them in order to make the language decision.
Copied: Zope3/branches/ZopeX3-3.0/src/zope/i18n/i18nobject.txt (from rev 26138, Zope3/branches/ZopeX3-3.0/src/zope/i18n/i18nobject.stx)
===================================================================
--- Zope3/branches/ZopeX3-3.0/src/zope/i18n/i18nobject.stx 2004-07-06 20:18:47 UTC (rev 26138)
+++ Zope3/branches/ZopeX3-3.0/src/zope/i18n/i18nobject.txt 2004-07-06 21:00:02 UTC (rev 26143)
@@ -0,0 +1,74 @@
+============
+I18n Objects
+============
+
+The Problem
+-----------
+
+I18n objects are used to internationalize content that cannot be
+translated via messages. The problem is three fold:
+
+- Internationalize an object iteself. The best example is an Image.
+ Often people put text into an image that needs to be localized, but
+ since it is a picture the text cannot be retrieved as a string. You
+ therefore will need a mechanism to create a different version of the
+ object for every language. (Note: This behavior is the same as
+ currently implemented in the ZBabelObject.)
+
+- Internationalize fractions of the content. Let's say for example you
+ wanted to internationalize the DublinCore information of your
+ content object. In order for this to work out you need to have an
+ I18n-supportive `AttributeAnnotation`. Solving this use case would
+ be similar to some of the work David Juan did with
+ `InternationalizedContent` in Localizer.
+
+- Formatting Objects. This problem involves converting basic or
+ complex types into a localized format. Good examples for this are
+ decimal numbers and date/time objects. In this case you would like
+ to specify a format via a templating expression and then pass the
+ object to the formatter to apply the parsed template. Initial steps
+ for implementing the template parser have been already taken,
+ therefore we only need to develop some interfaces and unittests
+ here, so the parser developer (which will use the ICU C/C++
+ libraries) will (choose?) what parts of the parser to wrap for
+ Python.
+
+The first two problems are very similar and can actually share the
+same interface for the language negotiation and redirection of the
+content request. I would therefore propose to have a `II18nContent`
+interface that somehow specifies how to get to the translated content
+and then redirect the call to the correct local content.
+
+
+`I18nObject`
+------------
+
+There will be an interface called II18nObject (which inherits I18nContent
+of course), which is a cameleon-like container, as it adapts to the
+properties of the contained object type. In order to accomplish all this,
+you will have to implement your own traverser which looks up the correct
+subobject.
+
+
+`I18nAttributeAnnotation`
+-------------------------
+
+This object will basically provide an internationalized version of
+Zope.App.OFS.AttributeAnnotations. which will be accomplished in a
+similar manner as the `I18nObject`.
+
+
+Open Issues
+-----------
+
+One issue left to solve is how to know the language when we need to
+make the decision. These objects are **not** Views, therefore they do
+not know about the request variable.
+
+One way to solve the issue would be that `I18nAttributeAnnotation`,
+for example, would not actually implement the `IAnnotations`
+interface, but that there would be an Adapter converting the
+`II18nAnnotations` to `IAnnotations`. Since adapters are short-lived
+(meaning they are initialized for a particular call), we can safely
+store some language information in them in order to make the language
+decision.
More information about the Zope3-Checkins
mailing list