[Checkins] SVN: bluebream/website/docs/v1.0/ Various language improvements
Daniel Nilsson
vq at telia.com
Tue Apr 6 12:51:41 EDT 2010
Log message for revision 110570:
Various language improvements
Changed:
U bluebream/website/docs/v1.0/introduction.rst
U bluebream/website/docs/v1.0/tutorial1.rst
-=-
Modified: bluebream/website/docs/v1.0/introduction.rst
===================================================================
--- bluebream/website/docs/v1.0/introduction.rst 2010-04-06 12:02:37 UTC (rev 110569)
+++ bluebream/website/docs/v1.0/introduction.rst 2010-04-06 16:51:40 UTC (rev 110570)
@@ -25,11 +25,11 @@
- BlueBream uses the powerful and familiar :term:`Buildout` system
written in Python.
-
+
- BlueBream employs the Zope Object Database (:term:`ZODB`), a
- transactional object database, providing extremely powerful and
- easy to use persistence.
-
+ transactional object database providing extremely powerful and easy
+ to use persistence.
+
- BlueBream registers components with Zope Component Markup Language
(:term:`ZCML`), an XML based configuration language, providing
limitless flexibility.
@@ -48,15 +48,15 @@
- BlueBream includes a number of well tested components to implement
common activities. A few are of these are:
-
+
- zope.publisher_ publishes Python objects on the web, emphasizing
:term:`WSGI` compatibility
- - zope.security_ provides a generic mechanism for pluggable
+ - zope.security_ provides a generic mechanism for pluggable
security policies
- - zope.testing_ and zope.testbrowser_ offer unit and functional testing
- frameworks
+ - zope.testing_ and zope.testbrowser_ offer unit and functional testing
+ frameworks
- zope.pagetemplate_ is an XHTML-compliant language for devloping
templates
@@ -91,12 +91,12 @@
- Mailing list: https://mail.zope.org/mailman/listinfo/bluebream
- Twitter: http://twitter.com/bluebream
-
+
- Blog: http://bluebream.posterous.com
-
+
- IRC channel: `#bluebream at freenode.net
<http://webchat.freenode.net/?randomnick=1&channels=bluebream>`_
-
+
- Wiki: http://wiki.zope.org/bluebream
- Ohloh.net: https://www.ohloh.net/p/bluebream
@@ -104,9 +104,9 @@
- PyPi home : http://pypi.python.org/pypi/bluebream
The BlueBream developer community is an active community involved in
-the development of BlueBream itself, and is looking for contributors
-to this project. Development related information is documented in the
-`wiki <http://wiki.zope.org/bluebream>`_ wiki located at:
+the development of BlueBream itself and is looking for contributors.
+Development related information is documented in the `wiki
+<http://wiki.zope.org/bluebream>`_ wiki located at:
http://wiki.zope.org/bluebream/ContributingToBlueBream
We aim to provide high quality free online documentation for
@@ -114,7 +114,7 @@
source for this website is available from the zope.org repository
(please replace ``USERNAME`` with your zope.org username.)::
- svn co svn+ssh://USERNAME@svn.zope.org/repos/main/bluebream/website
+ svn co svn+ssh://USERNAME@svn.zope.org/repos/main/bluebream/website
If you don't have svn commit access, please consult: `becoming a
contributor
@@ -144,14 +144,14 @@
core of *Principia*, a commercial application server. In November of
1998, investor Hadar Pedhazur convinced Digital Creations to open
source Principia. These packages evolved into the core components of
-Zope 2, and Digital Creations became Zope Corporation.
+Zope 2 and Digital Creations became Zope Corporation.
-Since those days, Zope has been under active development. It has
+Since those days Zope has been under active development. It has
evolved in several ways as the community gained experience,
-continually seeking the optimum balance between power and ease of use.
-Zope 2 emphasized rapid development. The :term:`Zope Component
+continually seeking the optimum balance between power and ease of
+use. Zope 2 emphasized rapid development, the :term:`Zope Component
Architecture`, which is the core of Zope 3, emphasized modularity and
-configurability, which proved very successful in "enterprise"
+configurability which proved very successful in "enterprise"
applications requiring flexibility and scalability.
justify the longer learning curve which Zope 3 requires, but is
@@ -163,9 +163,10 @@
the power of ZCA under the hood. Notable among these are :term:`grok`
and Repoze_.
-Zope 3 is now known as BlueBream. The name stems from the coincidence
-that the Z Object Publishing Environment, when spelled `zope`, is the
-name of a fish. `Blue bream`_ is another for the fish.
+Zope 3 is now known as BlueBream. The name stems from the
+coincidence that the Z Object Publishing Environment when spelled
+`zope` is the name of a species of fish. `Blue bream`_ is another
+name for the same species.
BlueBream combines the ZCA, Buildout into a well defined, and
documented, that makes building powerhouse applications fun.
@@ -184,7 +185,7 @@
.. _Convention over configuration: http://en.wikipedia.org/wiki/Convention_over_configuration
-.. _python and Internet Programming: http://www.python.org/workshops/1996-06/agenda.html
+.. _python and Internet Programming: http://www.python.org/workshops/1996-06/agenda.html
.. _Repoze: http://repoze.org/
.. _Blue bream: http://en.wikipedia.org/wiki/Blue_bream
@@ -194,9 +195,9 @@
More about the project
----------------------
-The original intent of Zope 3 was to become a replacement for Zope 2.
-However, this did not happen as planned. Instead, Zope 2 continued to
-make up the majority of new Zope deployments, due mostly to the
+The original intent of Zope 3 was to become a replacement for Zope 2,
+however this did not happen as planned. Instead Zope 2 continued to
+make up the majority of new Zope deployments, mostly due to the
popularity of Plone.
Zope 3 was conceived as a fresh start to leave certain aspects and
@@ -205,19 +206,19 @@
a new component architecture to address some of the
inheritance-based-programming limitations of Zope 2.
-The `ZCA <http://www.muthukadan.net/docs/zca.html>`_, notionally
-includes the packages named ``zope.component``, ``zope.interface`` and
-``zope.configuration``. Zope 3 added to this a large number of extra
-libraries and provided an application server that enabled programmers
-to develop standalone web applications.
+The `ZCA <http://www.muthukadan.net/docs/zca.html>`_ notionally
+includes the packages named ``zope.component``, ``zope.interface``
+and ``zope.configuration``. Zope 3 added to this a large number of
+extra libraries and provided an application server that enabled
+programmers to develop standalone web applications.
-In the meantime, another wave of web frameworks appeared.
+In the meantime another wave of web frameworks appeared.
:term:`Grok` evolved with many Zope 3 libraries at its core.
`repoze.bfg (aka BFG) <http://bfg.repoze.org>`_ evolved around the
-ZCA. Additionally, Zope 2 began to make use of the ZCA and various
+ZCA. Additionally Zope 2 began to make use of the ZCA and various
other Zope 3 packages.
-In 2009, a group of Zope developers agreed to concentrate primarily on
+In 2009 a group of Zope developers agreed to concentrate primarily on
the development of the Zope 3 libraries and formed the Zope Toolkit
(ZTK) that focused on a slim library subset of the Zope 3 project,
which can then be efficiently utilized by web application frameworks
@@ -225,12 +226,12 @@
- Form a project around the remaining web application part of Zope 3
-- Name it BlueBream as a new, unique name to avoid confusion
+- Name it BlueBream as a new and unique name to avoid confusion
- Create an upgrade path from the former Zope 3 application server
BlueBream can thus be seen as the successor of Zope 3 web application
-server; along with Grok, it relies on the ZTK.
+server that like Grok relies on the ZTK.
Organization of the documentation
---------------------------------
@@ -261,8 +262,9 @@
Tutorial --- Part 2
~~~~~~~~~~~~~~~~~~~
-This chapter continues with Part 2 of the ticket collector application
-tutorial excercise,, providing more detail on forms and schemas.
+This chapter is a continuation of the ticket collector application
+tutorial excercises, providing more detail regarding forms and
+schemas.
Manual
~~~~~~
@@ -301,11 +303,11 @@
on the concepts of Zope 2 which was built on Bobo and friends. The
list of Zope Corporation alumni is a *Who's Who* of Python
development, including one *Guido Van Rossum*. For more than 10 years
-contributions have come from a a world-wide community. We thank you
+contributions have come from a world-wide community. We thank you
all. Please help us add more names to the list of contributor as we
move forward from January 2010.
-:ref:`contributors-start`
+:ref:`contributors-start`
.. raw:: html
Modified: bluebream/website/docs/v1.0/tutorial1.rst
===================================================================
--- bluebream/website/docs/v1.0/tutorial1.rst 2010-04-06 12:02:37 UTC (rev 110569)
+++ bluebream/website/docs/v1.0/tutorial1.rst 2010-04-06 16:51:40 UTC (rev 110570)
@@ -774,12 +774,13 @@
As the first step for creating the main application container object
which is going to hold all other objects, you need to create an
interface. You can name the main application container interface as
-``ICollector``. To make this a container object, inherit from
-``zope.container.interfaces.IContainer`` or any derived interfaces.
-It is recommended add a site manager inside the main application
-container. In order to add a site manager later, it is recommend to
-inherit from ``zope.site.interfaces.IFolder`` interface. The
-``IFolder`` is inheriting from ``IContainer``.
+``ICollector``. To make this interface describe a container object
+have it inherit ``zope.container.interfaces.IContainer`` or any
+interface derived from it. It is recommended to add a site manager
+inside the main application container. In order to add a site
+manager later, it is recommend to inherit from
+``zope.site.interfaces.IFolder`` interface. The ``IFolder`` is
+inheriting from ``IContainer``.
You can create a new Python package named ``collector`` inside
``src/tc`` like this::
@@ -809,17 +810,18 @@
default=u"",
required=False)
-The interface defined here is your schema for the object. There are
-two fields defined in the schema. The first one is ``name`` and the
-second one is ``description``. The schema is also can be used to
-auto-generate web forms.
+The interface defined here is your schema for the main application
+object. There are two fields defined in the schema. The first one
+is ``name`` and the second one is ``description``. This schema can
+later can be used to auto-generate web forms.
Implementing Interface
~~~~~~~~~~~~~~~~~~~~~~
-Schema is kind of blueprint for your objects, schema define the
-contracts for the objects. Once you have schema ready, you can
-create some concrete classes which implement the schema.
+A schema can be described as a blueprint for your objects as it
+defines the fields that the object must implement and the contracts
+that it must fulfil. Once written you can create some concrete
+classes which implement your schema.
Next, you need to implement this interface. To implement
``IContainer``, you can inherit from ``zope.site.folder.Folder``.
@@ -840,16 +842,16 @@
name = u""
description = u""
-To declare a class is implementing a particular interface, you can
-use ``implements`` function. The class also provides defaults values
-for attributes.
+To declare that a class is implementing a particular interface you
+can use the ``implements`` function from ``zope.interface``.
Registering components
~~~~~~~~~~~~~~~~~~~~~~
-Once the interfaces and its implementations are ready. You can do
-the configuration in ZCML. Open the ``src/tc/collector/configure.zcml``
-file to edit, then mark the ``ICollector`` as a content component::
+Once the interfaces and its implementations are ready you can do the
+configuration in ZCML. Open the ``src/tc/collector/configure.zcml``
+file for editing and enter the following to declare ``ICollector`` a
+content component::
<interface
interface="tc.collector.interfaces.ICollector"
@@ -857,18 +859,18 @@
/>
The ``zope.app.content.interfaces.IContentType`` represents a content
-type. If an **interface** provides ``IContentType`` interface type,
-then all objects providing the **interface** are considered content
-objects.
+type. If an **interface** provides the ``IContentType`` interface
+type, then all objects providing the **interface** are considered to
+be content objects.
-To set annotations for collector objects, we need to mark it as
-implementing ``zope.annotation.interfaces.IAttributeAnnotatable``
-marker interface. Also this configuration declare that ``Collector``
-class implements ``zope.container.interfaces.IContentContainer``.
-These two classes are marker interfaces. An interface used to
-declare that a particular object belongs to a special type is called
-marker interface. Marker interface won't be having any attribute or
-method.
+To set annotations for collector objects we need to configure it as
+implementing the ``zope.annotation.interfaces.IAttributeAnnotatable``
+interface. The example configuration below also declare that our
+``Collector`` class implements
+``zope.container.interfaces.IContentContainer``. These two classes
+are examples of marker interfaces, interfaces used to declare that a
+particular object belongs to a special type without requiring the
+presence of any attributes or methods.
::
@@ -897,10 +899,10 @@
A view for adding collector
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Now the content component is ready to use. You need a web page from
-where we can add the ticket collector. You can use ``zope.formlib``
-package to create a form. You can add the view class definition
-inside ``src/tc/collector/views.py`` like this::
+Now the content component is ready to use but you will need a web
+page from where to add a ticket collector object. You can use
+``zope.formlib`` package to create a form view. You can add the view
+class definition inside ``src/tc/collector/views.py`` like this::
from zope.site import LocalSiteManager
from zope.formlib import form
@@ -923,17 +925,18 @@
collector.setSiteManager(LocalSiteManager(collector))
self.request.response.redirect(".")
-The ``createAndAdd`` function will be called when used submit *Add*
-button from web form. The second last line is very important::
+The ``createAndAdd`` function will be called when the user presses
+the *Add* button from the web form. The second last line is very
+important::
collector.setSiteManager(LocalSiteManager(collector))
-This line add a site manager to the collector, so that it can be used
+This line adds a site manager to the collector so that it can be used
as a persistent component registry to register local components like
local utilities.
-As you have already seen in the previous chapter, ``browser:page``
-directive is used for registering pages. You can give the name as
+As you have already seen in the previous chapter the ``browser:page``
+directive is used for registering pages. You can use the name
``add_ticket_collector`` and register it for
``zope.site.interfaces.IRootFolder``. Add these lines to
``src/tc/collector/configure.zcml``::
@@ -945,11 +948,10 @@
class="tc.collector.views.AddTicketCollector"
/>
-The package development is completed now. This package is not
-included from the main package yet. To include this package from the
-main package (``tc.main``), you need to modify the
-``src/tc/main/configure.zcml`` and add this line before
-``</configure>``::
+The package development is completed now but it is not yet included
+from the main package. To include this package from the main package
+(``tc.main``) you need to modify the ``src/tc/main/configure.zcml``
+and add this line before ``</configure>``::
<include package="tc.collector" />
@@ -961,11 +963,11 @@
You can see the file size of ``var/filestorage/Data.fs`` is
increasing as objects are getting added. The ``Data.fs`` is where
-the data is physically stored.
+the persisted objects are physically stored.
-You can also confirm the object is actually saved into database from
-Python shell. If you go to Python shell and try to access the root
-object, you can see that it has the object you added::
+You can also confirm that the object is actually saved into database
+from the Python shell. If you go to the Python shell and try to
+access the root object you can see that it has the object you added::
jack at computer:/projects/ticketcollector$ ./bin/paster shell debug.ini
...
@@ -975,22 +977,21 @@
>>> list(root.keys())
[u'mycollector']
-You can use this debug shell to introspect Python objects stored in
-ZODB. You can add, update or delete objects and attributes from the
-debug shell.
+Through this debug shell you can introspect, add, update or delete
+Python objects and attributes.
A default view for collector
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-If you try to access the collector from the URL:
-http://localhost:8080/mycollector , you will get ``NotFound`` error
+If you try to access the collector from the URL
+http://localhost:8080/mycollector you will get a ``NotFound`` error
like this::
URL: http://localhost:8080/mycollector
...
NotFound: Object: <tc.collector.ticketcollector.Collector object at 0x9fe44ac>, name: u'@@index'
-This error is raised, because there is no view named ``index``
+This error is raised because there is no view named ``index``
registered for ``ICollector``. This section will show how to create
a default view for ``ICollector`` interface.
@@ -1004,7 +1005,7 @@
def __call__(self):
return "Hello ticket collector!"
-Then, in the ``src/tc/collector/configure.zcml``::
+Then add the following in ``src/tc/collector/configure.zcml``::
<browser:page
for="tc.collector.interfaces.ICollector"
@@ -1018,8 +1019,8 @@
Hello ticket collector!
-In the next section, you will see more details about the main page
-for collector. Also we are going to learn about Zope Page Template.
+In the next section you will see more details about the main page for
+collector. We're also going to learn about Zope Page Template.
.. _tut1-main-page:
@@ -1035,8 +1036,6 @@
``TicketCollectorMainView``. Update the ``TicketCollectorMainView``
class inside ``src/tc/collector/views.py`` like this::
-::
-
from zope.browserpage import ViewPageTemplateFile
class TicketCollectorMainView(form.DisplayForm):
@@ -1061,20 +1060,20 @@
</html>
Now you can visit: http://localhost:8080/mycollector . It should
-display "Welcome to ticket collector!" message.
+display "Welcome to ticket collector!".
-.. _tut1-conclusion:
+.. _tut1-conclusions:
-Conclusion
-----------
+Conclusions
+-----------
-This part of tutorial covered the basics of creating a web
+This part of the tutorial covered the basics of creating a web
application using BlueBream. This chapter narrated in detail about
the usage of ``bluebream`` paster project template to create a new
-project. This part of tutorial also walked though the process of
-building application using Buildout. Then, narrated creating an
-application container. Finally, a default view for application
-container is also created. The :ref:`tut2-tutorial` will expand the
+project. This part of the tutorial also walked though the process of
+building application using Buildout. Then narrated creating an
+application container. Finally a default view for the application
+container was created. :ref:`tut2-tutorial` will expand the
application with additional functionalities.
.. raw:: html
More information about the checkins
mailing list