Add Sphinx docs.

1 files changed, 0 insertions, 133 deletions

diff --git a/src/zope/i18nmessageid/messages.txt b/src/zope/i18nmessageid/messages.txt
deleted file mode 100644
index 4bf52a5..0000000
--- a/src/zope/i18nmessageid/messages.txt
+++ /dev/null
@@ -1,133 +0,0 @@
-=============
-I18n Messages
-=============
-
-Rationale
----------
-
-To translate any text, we must be able to discover the source domain
-of the text.  A source domain is an identifier that identifies a
-project that produces program source strings.  Source strings occur as
-literals in python programs, text in templates, and some text in XML
-data.  The project implies a source language and an application
-context.
-
-We can think of a source domain as a collection of messages and
-associated translation strings.
-
-We often need to create unicode strings that will be displayed by
-separate views.  The view cannot translate the string without knowing
-its source domain.  A string or unicode literal carries no domain
-information, therefore we use messages.  Messages are unicode strings
-which carry a translation source domain and possibly a default
-translation.  They are created by a message factory. The message
-factory is created by calling ``MessageFactory`` with the source
-domain.
-
-ZopeMessageFactory
-------------------
-
-  >>> from zope.i18nmessageid import ZopeMessageFactory as _z_
-  >>> foo = _z_('foo')
-  >>> foo.domain
-  'zope'
-  
-
-
-Example
--------
-
-In this example, we create a message factory and assign it to _.  By
-convention, we use _ as the name of our factory to be compatible with
-translatable string extraction tools such as xgettext.  We then call _
-with a string that needs to be translatable:
-
-  >>> from zope.i18nmessageid import MessageFactory, Message
-  >>> _ = MessageFactory("futurama")
-  >>> robot = _(u"robot-message", u"${name} is a robot.")
-
-Messages at first seem like they are unicode strings:
-
-  >>> robot == u'robot-message'
-  True
-  >>> isinstance(robot, unicode)
-  True
-
-The additional domain, default and mapping information is available
-through attributes:
-
-  >>> robot.default == u'${name} is a robot.'
-  True
-  >>> robot.mapping
-  >>> robot.domain
-  'futurama'
-
-The message's attributes are considered part of the immutable message
-object.  They cannot be changed once the message id is created:
-
-  >>> robot.domain = "planetexpress"
-  Traceback (most recent call last):
-  ...
-  TypeError: readonly attribute
-
-  >>> robot.default = u"${name} is not a robot."
-  Traceback (most recent call last):
-  ...
-  TypeError: readonly attribute
-
-  >>> robot.mapping = {u'name': u'Bender'}
-  Traceback (most recent call last):
-  ...
-  TypeError: readonly attribute
-
-If you need to change their information, you'll have to make a new
-message id object:
-
-  >>> new_robot = Message(robot, mapping={u'name': u'Bender'})
-  >>> new_robot == u'robot-message'
-  True
-  >>> new_robot.domain
-  'futurama'
-  >>> new_robot.default == u'${name} is a robot.'
-  True
-  >>> new_robot.mapping == {u'name': u'Bender'}
-  True
-
-Last but not least, messages are reduceable for pickling:
-
-  >>> callable, args = new_robot.__reduce__()
-  >>> callable is Message
-  True
-  >>> args == (u'robot-message', 'futurama', u'${name} is a robot.', {u'name': u'Bender'})
-  True
-
-  >>> fembot = Message(u'fembot')
-  >>> callable, args = fembot.__reduce__()
-  >>> callable is Message
-  True
-  >>> args == (u'fembot', None, None, None)
-  True
-
-Message IDs and backward compatability
---------------------------------------
-
-The change to immutability is not a simple refactoring that can be
-coped with backward compatible APIs--it is a change in semantics.
-Because immutability is one of those "you either have it or you don't"
-things (like pregnancy or death), we will not be able to support both
-in one implementation.
-
-The proposed solution for backward compatability is to support both
-implementations in parallel, deprecating the mutable one.  A separate
-factory, ``MessageFactory``, instantiates immutable messages, while
-the deprecated old one continues to work like before.
-
-The roadmap to immutable-only message ids is proposed as follows:
-
-  Zope 3.1: Immutable message ids are introduced.  Security
-  declarations for mutable message ids are provided to make the
-  stripping of security proxies unnecessary.
-
-  Zope 3.2: Mutable message ids are deprecated.
-
-  Zope 3.3: Mutable message ids are removed.