cubicweb: comparison doc/book/en/A03a-concepts.en.txt

equal deleted inserted replaced

-:9f80ecdb057a
+:d474534fd04d
 ~~~~~~~~~~~~~~~~~~~
 .. image:: images/archi_globale.en.png
 `CubicWeb` framework is a server/client application framework. Those two
-parties communicates through RQL (`CubicWeb` query language implementation)
+parts communicate through RQL (`CubicWeb` query language implementation)
 and ResultSet (which will be explained in :ref:`TermsVocabulary`).
 The server manages all interactions with sources.
 .. note::
-For real, the client and server sides are integrated in the same
+Usually, the client and server sides are integrated in the same
-process and interact directly, without the needs for distants
+process and interact directly, without the need for distant
-calls using Pyro. It is important to note down that those two
+calls using Pyro. But, it is important to note that those two
 sides, client/server, are disjointed and it is possible to execute
-a couple of calls in distincts processes to balance the load of
+a couple of calls in distinct processes to balance the load of
 your web site on one or more machines.
 .. _TermsVocabulary:
 Terms and vocabulary
 The schema defines the data model of an application based on entities
 and relations, modeled with a comprehensive language made of Python
 classes based on `yams`_ library. This is the core piece
 of an application. It is initially defined in the file system and is
 stored in the database at the time an instance is created. `CubicWeb`
-provides a certain number of system entities included automatically as
+provides a certain number of system entities included automatically
-it is necessary for the core of `CubicWeb` and a library of
+(necessary for the core of `CubicWeb`) and a library of
 cubes (which defined application entities) that can be explicitely
 included if necessary.
 *entity type*
 An entity type is a set of attributes; the essential attribute of
 Entities are linked to each others by relations. In `CubicWeb`
 relations are binary: by convention we name the first item of
 a relation the `subject` and the second the `object`.
 *final entity type*
-Final types corresponds to the basic types such as string of characters,
+Final types correspond to the basic types such as string of characters,
 integers... Those types have a main property which is that they can
 only be used as `object` of a relation. The attributes of an entity
 (non final) are entities (finals).
 *final relation type*
 *source*
 A data source is a container of data (SGBD, LDAP directory, `Google
 App Engine`'s datastore ...) integrated in the
 `CubicWeb` repository. This repository has at least one source, `system` which
-contains the schema of the application, plain-text index and others
+contains the schema of the application, plain-text index and other
 vital informations for the system.
 *configuration*
-It is possible to create differents configurations for an instance:
+It is possible to create different configurations for an instance:
 - ``repository`` : repository only, accessible for clients using Pyro
 - ``twisted`` : web interface only, access the repository using Pyro
 - ``all-in-one`` : web interface and repository in a single process.
 The repository could be or not accessible using Pyro.
 *cube*
 A cube is a model grouping one or multiple data types and/or views
-to provide a specific functionnality or a complete `CubicWeb` application
+to provide a specific functionality or a complete `CubicWeb` application
 potentially using other cubes. The available cubes are located in the file
-system at `/path/to/forest/cubicweb/cubes` for a Mercurial forest installation,
+system at `/path/to/forest/cubicweb/cubes` for a Mercurial forest installation.
-for a debian packages installation they will be located in
+For a debian packages installation they will be located in
 `/usr/share/cubicweb/cubes`.
-Larger applications can be built faster by importing cubes,
+Larger applications can be built quite fast by importing cubes,
-adding entities and relationships and overriding the
+adding entities and relationships, overriding the
-views that need to display or edit informations not provided by
+*views* that display the cubes or by editing informations not provided by
-cubes.
+the cubes.
 *instance*
 An instance is a specific installation of one or multiple cubes. All the required
 configuration files necessary for the well being of your web application
 are grouped in an instance. This will refer to the cube(s) your application
 is based on.
 For example logilab.org and our intranet are two instances of a single
-cube jpl, developped internally.
+cube "jpl", developped internally.
 The instances are defined in the directory `/etc/cubicweb.d`.
 *application*
-The term application is sometime used to talk about an instance
+The term application is sometimes used to talk about an instance
 and sometimes to talk of a cube depending on the context.
 So we would like to avoid using this term and try to use *cube* and
 *instance* instead.
 *result set*
 views are not very fancy, it is usually necessary to develop your
 own. Any generated view can be overridden by defining a new one with
 the same identifier.
 *rql*
-Relation Query Language in order to empasize the way of browsing relations.
+Relation Query Language in order to emphasize the way of browsing relations.
-This query language is inspired by SQL but is highest level, its implementation
+This query language is inspired by SQL but is on a higher level;
-generates SQL.
+its implementation generates SQL.
 .. _`Python Remote Object`: http://pyro.sourceforge.net/
 .. _`yams`: http://www.logilab.org/project/yams/
 `CubicWeb` engine
 ~~~~~~~~~~~~~~~~~
 The engine in `CubicWeb` is a set of classes managing a set of objects loaded
-dynamically at the startup of `CubicWeb` (*appobjects*). Those dynamics objects,
+dynamically at the startup of `CubicWeb` (*appobjects*). Those dynamic objects,
 based on the schema or the library, are building the final application.
-The differents dymanic components are for example:
+The different dynamic components are for example:
 * client and server side
 - entities definition, containing the logic which enables application data manipulation
 The most important method is the `execute` method of a cursor :
 `execute(rqlstring, args=None, eid_key=None, build_descr=True)`
 :rqlstring: the RQL query to execute (unicode)
-:args: if the query contains substitutions, a dictionnary containing the values to use
+:args: if the query contains substitutions, a dictionary containing the values to use
 :eid_key:
-an implementation detail of the RQL queries cache implies that if a substitution
+an implementation detail of the RQL cache implies that if a substitution
 is used to introduce an eid *susceptible to raise the ambiguities in the query
-type resolution*, then we have to specify the correponding key in the dictionnary
+type resolution*, then we have to specify the corresponding key in the dictionary
 through this argument
 The `Connection` object owns the methods `commit` and `rollback`. You *should
 never need to use them* during the development of the web interface based on
 the `CubicWeb` framework as it determines the end of the transaction depending
 on the query execution success.
 .. note::
-While executing updates queries (SET, INSERT, DELETE), if a query generates
+While executing update queries (SET, INSERT, DELETE), if a query generates
 an error related to security, a rollback is automatically done on the current
 transaction.
 The `Request` class (`cubicweb.web`)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 A request instance is created when an HTTP request is sent to the web server.
-It contains informations such as forms parameters, user authenticated, etc.
+It contains informations such as form parameters, user authenticated, etc.
 **Globally, a request represents a user query, either through HTTP or not
 (we also talk about RQL queries on the server side for example).**
 An instance of `Request` has the following attributes:
 * `user`, instance of `cubicweb.common.utils.User` corresponding to the authenticated
 user
-* `form`, dictionnary containing the values of a web form
+* `form`, dictionary containing the values of a web form
-* `encoding`, characters encoding to use in the response
+* `encoding`, character encoding to use in the response
 But also:
 :Session data handling:
-* `session_data()`, returns a dictionnary containing all the session data
+* `session_data()`, returns a dictionary containing all the session data
 * `get_session_data(key, default=None)`, returns a value associated to the given
 key or the value `default` if the key is not defined
 * `set_session_data(key, value)`, assign a value to a key
 * `del_session_data(key)`,  suppress the value associated to a key
 :Cookies handling:
-* `get_cookie()`, returns a dictionnary containing the value of the header
+* `get_cookie()`, returns a dictionary containing the value of the header
 HTTP 'Cookie'
 * `set_cookie(cookie, key, maxage=300)`, adds a header HTTP `Set-Cookie`,
 with a minimal 5 minutes length of duration by default (`maxage` = None
 returns a *session* cookie which will expire when the user closes the browser
 window)
 of the HTTP request
 * `set_header(header, value)`, adds an arbitrary header in the response
 * `cursor()` returns a RQL cursor on the session
 * `execute(*args, **kwargs)`, shortcut to ``.cursor().execute()``
 * `property_value(key)`, properties management (`EProperty`)
-* dictionnary `data` to store data to share informations between components
+* dictionary `data` to store data to share informations between components
 *while a request is executed*
 Please note that this class is abstract and that a concrete implementation
 will be provided by the *frontend* web used (in particular *twisted* as of
 today). For the views or others that are executed on the server side,
 What is a cube ?
 ````````````````
 A cube is a model grouping one or more entity types and/or views associated
 in order to provide a specific feature or even a complete application using
-others cubes.
+other cubes.
 You can decide to write your own set of cubes if you wish to re-use the
 entity types you develop. Lots of cubes are available from the `CubicWeb
 Forge`_ under a free software license.
 * ``schema`` contains the schema definition (server side only)
 * ``entities`` contains the entities definition (server side and web interface)
 * ``sobjects`` contains hooks and/or views notifications (server side only)
 * ``views`` contains the web interface components (web interface only)
 * ``test`` contains tests related to the application (not installed)
-* ``i18n`` contains messages catalogs for supported languages (server side and
+* ``i18n`` contains message catalogs for supported languages (server side and
 web interface)
 * ``data`` contains data files for static content (images, css, javascripts)
 ...(web interface only)
 * ``migration`` contains initialization file for new instances (``postcreate.py``)
 and a file containing dependencies of the component depending on the version
 At least you should have:
 * the file ``__pkginfo__.py``
 * the schema definition
 XXX false, we may want to have cubes which are only adding a service,
-no persistent data (eg embeding for instance)
+no persistent data (eg embedding for instance)
 Standard library
 ````````````````

changeset 1221	d474534fd04d
parent 466	bef394c66f10
child 1398	5fe84a5f7035