--- a/doc/book/en/A020-tutorial.en.txt Tue Dec 23 14:42:41 2008 +0100
+++ b/doc/book/en/A020-tutorial.en.txt Tue Dec 23 14:42:52 2008 +0100
@@ -5,18 +5,20 @@
Quick overview of `CubicWeb`
============================
-`CubicWeb` allows us to develop web applications instances based on
-one or more `cubes`.
+`CubicWeb` is a semantic web application framework that favors reuse and
+object-oriented design.
+
+A `cube` is a component that includes a model defining the data types and a set of
+views to display the data.
-What we call a `cube` is a model defining the data types and views.
-A `cube` is a reusable component grouped with others cubes in the file
-system.
+An application is a `cube`, but usually an application is built by assembling
+a few smaller cubes.
-An `instance` refers to a specific installation of one or more `cubes`
- where are grouped configuration files of the final web application.
+An `instance` is a specific installation of an application and includes
+configuration files.
-In this document, we will show you how to create a `cube` and how to use it
-in an `instance` for your web application.
+This tutorial will show how to create a `cube` and how to use it as an
+application to run an `instance`.
.. include:: A02a-create-cube.en.txt
.. include:: A02b-components.en.txt
--- a/doc/book/en/A02a-create-cube.en.txt Tue Dec 23 14:42:41 2008 +0100
+++ b/doc/book/en/A02a-create-cube.en.txt Tue Dec 23 14:42:52 2008 +0100
@@ -3,19 +3,21 @@
Create your cube
----------------
-After you installed your `CubicWeb` development environment, you can start
-to build your first cube: ::
+Once your `CubicWeb` development environment is set up, you can create a new
+cube::
cubicweb-ctl newcube blog
-This will create in ``/path/to/forest/cubes`` a directory containing: ::
+This will create in the cubes directory (``/path/to/forest/cubes`` for Mercurial
+installation, ``/usr/share/cubicweb/cubes`` for debian packages installation)
+a directory named ``blog`` containing::
blog/
|
|-- data/
| |-- cubes.blog.css
| |-- cubes.blog.js
- | |-- external_resources
+ | `-- external_resources
|
|-- debian/
| |-- changelog
@@ -23,13 +25,13 @@
| |-- control
| |-- copyright
| |-- cubicweb-blog.prerm
- | |-- rules
+ | `-- rules
|
|-- entities.py
|
|-- i18n/
| |-- en.po
- | |-- fr.po
+ | `-- fr.po
|
|-- __init__.py
|
@@ -37,7 +39,7 @@
|
|-- migration/
| |-- postcreate.py
- | |-- precreate.py
+ | `-- precreate.py
|
|-- __pkginfo__.py
|
@@ -51,30 +53,27 @@
|
|-- test/
| |-- data/
- | |-- bootstrap_cubes
+ | | `-- bootstrap_cubes
| |-- pytestconf.py
| |-- realdb_test_blog.py
- | |-- test_blog.py
+ | `-- test_blog.py
|
- |-- views.py
-
-Any changes applied to your data model should be done in this
-directory.
+ `-- views.py
.. _DefineDataModel:
-Define your data schema
------------------------
+Define your data model
+----------------------
-The data model or schema is hte core of your `CubicWeb` application.
-This is where is defined the type of content you application will handle.
+The data model or schema is the core of your `CubicWeb` application.
+It defines the type of content your application will handle.
-The data model is defined in the file ``schema.py`` of your cube
-``blog`` such as follows.
+The data model of your cube ``blog`` is defined in the file ``schema.py``:
::
from cubicweb.schema import format_constraint
+
class Blog(EntityType):
title = String(maxsize=50, required=True)
description = String()
@@ -107,7 +106,7 @@
Create your instance
--------------------
-::
+To use this cube as an application and create a new instance named ``blogdemo``, do::
cubicweb-ctl create blog blogdemo
@@ -116,48 +115,46 @@
which will contain all the configuration files required to start
you web application.
-The instance ``blogdemo`` is based on the cube ``blog``.
-
-
-Welcome in your web application
+Welcome to your web application
-------------------------------
-Run your application with the following command: ::
+Start your application in debug mode with the following command: ::
cubicweb-ctl start -D blogdemo
-You can now access to your web application to create blogs and post messages
-by visitin the URL http://localhost:8080/.
-A login form will first be prompted. By default, the application will not allow
-anonymous user to get in the application. You should then use the admin
-account you created at the time you initialized the database with
-``cubicweb-ctl create``.
+You can now access your web application to create blogs and post messages
+by visiting the URL http://localhost:8080/.
+
+A login form will appear. By default, the application will not allow anonymous
+users to enter the application. To login, you need then use the admin account
+you created at the time you initialized the database with ``cubicweb-ctl
+create``.
.. image:: images/login-form.png
Once authenticated, you can start playing with your application
-and create entities. Bravo!
+and create entities.
.. image:: images/blog-demo-first-page.png
-Please notice that so far, `CubicWeb` franework managed all aspects of
-the web application based in the schema provided at first.
+Please notice that so far, the `CubicWeb` franework managed all aspects of
+the web application based on the schema provided at first.
-Create entities
----------------
+Add entities
+------------
-We will now create a couple of entities in our web application.
+We will now add entities in our web application.
-Create a Blog
-~~~~~~~~~~~~~
+Add a Blog
+~~~~~~~~~~
-Let us create a few of these entities. Click on the `[+]` at the right
-of the link Blog. Call this new Blog ``Tech-blog`` and type in
-``everything about technology`` as the description, then validate the
-form by clicking on ``Validate``.
+Let us create a few of these entities. Click on the `[+]` at the left of the
+link Blog on the home page. Call this new Blog ``Tech-blog`` and type in
+``everything about technology`` as the description, then validate the form by
+clicking on ``Validate``.
.. image:: images/cbw-create-blog.en.png
:alt: from to create blog
@@ -182,10 +179,10 @@
.. image:: images/cbw-list-two-blog.en.png
:alt: displaying a list of two blogs
-Create a BlogEntry
-~~~~~~~~~~~~~~~~~~
+Add a BlogEntry
+~~~~~~~~~~~~~~~
-Get back to the home page and click on [+] at the right of the link
+Get back to the home page and click on [+] at the left of the link
BlogEntry. Call this new entry ``Hello World`` and type in some text
before clicking on ``Validate``. You added a new blog entry without
saying to what blog it belongs. There is a box on the left entitled
@@ -240,7 +237,7 @@
A view is applied on a `result set` which contains a set of
entities we are trying to display. `CubicWeb` uses a selector
-mecanism which computes a score used to identify which view
+mechanism which computes a score used to identify which view
is the best to apply for the `result set` we are trying to
display. The standard library of selectors is in
``cubicweb.common.selector`` and a library of methods used to
--- a/doc/book/en/A02b-components.en.txt Tue Dec 23 14:42:41 2008 +0100
+++ b/doc/book/en/A02b-components.en.txt Tue Dec 23 14:42:52 2008 +0100
@@ -5,24 +5,24 @@
Cubes
-----
-What is a cube
-~~~~~~~~~~~~~~
+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.
+
You can decide to write your own set of cubes if you wish to re-use the
-entity types you develop. By default, LAX comes with its owns set of cubes
-that you can start using right away.
+entity types you develop. Lots of cubes are available from the `CubicWeb
+Forge`_ under a free software license.
+.. _`CubicWeb Forge`: http://www.cubicweb.org/project/
Standard library
~~~~~~~~~~~~~~~~
-A library of standard cubes is part of the `LAX` release (look at
-``lax/skel/ginco-apps``). Cubes provide entities and views. With
-``lax-0.4``, you should get a set of application entities and system
-entities you can re-use.
+A library of standard cubes is part of the `CubicWeb` release (look at the
+output of ``cubicweb-ctl list``). Cubes provide entities and views.
The available application entities are:
@@ -36,7 +36,6 @@
* classtags: Tag (to tag anything)
-
* file: File (to allow users to upload and store binary or text files)
* link: Link (to collect links to web resources)
@@ -56,7 +55,6 @@
* comment: Comment (to attach comment threads to entities)
-
Adding comments to BlogDemo
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--- a/doc/book/en/A02c-maintemplate.en.txt Tue Dec 23 14:42:41 2008 +0100
+++ b/doc/book/en/A02c-maintemplate.en.txt Tue Dec 23 14:42:52 2008 +0100
@@ -18,32 +18,13 @@
HTMLPageHeader
~~~~~~~~~~~~~~~
-Let's use a different logo than the default one provided with LAX
-and customize our header.
-
-Change logo
-```````````
-
-The easiest way to use a different logo is to replace the existing
-``logo.png`` in ``myapp/data`` by your prefered icon and refresh.
-By default all application will look for a ``logo.png`` to be
-rendered in the logo section.
-
-.. image:: images/lax-book.06-main-template-logo.en.png
-
-[ADD]
-customized external_resources in myapp/data cd crih for reference
-
-[WRITE ME]
-ADD how to use external_resources variables used in ginco/web/webconfig.py
-
Customize header
`````````````````
Let's now move the search box in the header and remove the login form
from the header. We'll show how to move it to the left column of the application.
-Let's sat we do not want anymore the login menu to be in the header, but we
+Let's say we do not want anymore the login menu to be in the header, but we
prefer it to be in the left column just below the logo. As the left column is
rendered by ``TheMainTemplate``, we will show how to do it in TheMainTemplate_.
@@ -205,5 +186,5 @@
[TODO]
Rajouter une section pour definir la terminologie utilisee.
-Dans ginco-doc rajouter une section pour erudi-ctl shell ou
+Dans ginco-doc rajouter une section pour cubicweb-ctl shell ou
on liste les commandes dispos.
--- a/doc/book/en/A03a-concepts.en.txt Tue Dec 23 14:42:41 2008 +0100
+++ b/doc/book/en/A03a-concepts.en.txt Tue Dec 23 14:42:52 2008 +0100
@@ -77,7 +77,9 @@
A cube is a model grouping one or multiple data types and/or views
to provide a specific functionnality or a complete `CubicWeb` application
potentially using other cubes. The available subes are located in the file
- system at `/path/to/forest/cubicweb/cubes`.
+ system at `/path/to/forest/cubicweb/cubes` for a Mercurial forest installation,
+ for a debian packages installation they will be located in
+ `/usr/share/cubicweb/cubes`.
Larger applications can be built faster by importing cubes,
adding entities and relationships and overriding the
views that need to display or edit informations not provided by
--- a/doc/book/en/B021-schema-stdlib.en.txt Tue Dec 23 14:42:41 2008 +0100
+++ b/doc/book/en/B021-schema-stdlib.en.txt Tue Dec 23 14:42:52 2008 +0100
@@ -31,8 +31,8 @@
* `Bookmark`, an entity type used to allow a user to customize his links within
the application
-Cubes in the library
-````````````````````
+Cubes available
+```````````````
An application is based on several basic cubes. In the set of available
basic cubes we can find for example :
@@ -69,3 +69,7 @@
To declare the use of a component, once installed, add the name of the component
to the variable `__use__` in the file `__pkginfo__.py` of your own component.
+.. note::
+ The listed cubes above are available as debian-packages on `CubicWeb's forge`_.
+
+.. _`CubicWeb's forge`: http://www.cubicweb.org/project?vtitle=All%20cubicweb%20projects
--- a/doc/book/en/BXXX-templates.en.txt Tue Dec 23 14:42:41 2008 +0100
+++ b/doc/book/en/BXXX-templates.en.txt Tue Dec 23 14:42:52 2008 +0100
@@ -24,16 +24,13 @@
HTMLPageHeader
--------------
-Let's use a different logo than the default one provided with LAX
-and customize our header.
-
Customize header
~~~~~~~~~~~~~~~~
Let's now move the search box in the header and remove the login form
from the header. We'll show how to move it to the left column of the application.
-Let's sat we do not want anymore the login menu to be in the header, but we
+Let's say we do not want anymore the login menu to be in the header, but we
prefer it to be in the left column just below the logo. As the left column is
rendered by ``TheMainTemplate``, we will show how to do it in TheMainTemplate_.
@@ -165,7 +162,7 @@
TheMainTemplate is responsible for the general layout of the entire application.
It defines the template of ``id = main`` that is used by the application. Is
-also defined in ``ginco/web/views/basetemplates.py`` another template that can
+also defined in ``cubicweb/web/views/basetemplates.py`` another template that can
be used based on TheMainTemplate called SimpleMainTemplate which does not have
a top section.
@@ -195,5 +192,5 @@
[TODO]
Rajouter une section pour definir la terminologie utilisee.
-Dans ginco-doc rajouter une section pour erudi-ctl shell ou
+Dans ginco-doc rajouter une section pour cubciweb-ctl shell ou
on liste les commandes dispos.
--- a/doc/book/en/C000-administration.en.txt Tue Dec 23 14:42:41 2008 +0100
+++ b/doc/book/en/C000-administration.en.txt Tue Dec 23 14:42:52 2008 +0100
@@ -15,3 +15,4 @@
C020-site-config.en.txt
C030-instance-config.en.txt
C040-rql.en.txt
+ C041-rql-tutorial.en.txt
--- a/doc/book/en/C011-installation.en.txt Tue Dec 23 14:42:41 2008 +0100
+++ b/doc/book/en/C011-installation.en.txt Tue Dec 23 14:42:52 2008 +0100
@@ -5,51 +5,61 @@
Installation
============
-Installation of `Cubicweb` and its dependancies
+Installation of `Cubicweb` and its dependencies
-----------------------------------------------
-`CubicWeb` is available as a debian package as well as an archive.
-We will detail here the two easiest way to set-up `CubciWeb`
-environment.
+`CubicWeb` is packaged for Debian and Ubuntu, but can be installed from source
+using a tarball or the Mercurial version control system.
Debian and Ubuntu packages
```````````````````````````
Depending on the distribution you are using, add the appropriate line to your list
-of sources (for example by editing ``/etc/apt/sources.list``) ::
+of sources (for example by editing ``/etc/apt/sources.list``).
+
+For Debian Lenny::
deb http://ftp.logilab.org/dists/ lenny/
+
+For Debian Sid::
+
+ deb http://ftp.logilab.org/dists/ sid/
+
+For Ubuntu Hardy::
+
deb http://ftp.logilab.org/dists/ hardy/
- deb http://ftp.logilab.org/dists/ sid/
+
You can now install the required packages with the following command: ::
- apt-get update ; apt-get install cubicweb
+ apt-get update
+ apt-get install cubicweb
+ apt-get install cubicweb-dev
+
This is it!
-``tar.gz`` archive
-``````````````````
+Install from source
+```````````````````
-You can download our sources at: ::
+You can download the archive containing the sources from our `ftp site`_ at: ::
http://ftp.logilab.org/pub/cubicweb/
-Unpack the sources
-
-
-
+.. _`ftp site`: http://ftp.logilab.org/pub/cubicweb/
-.. note::
- `CubicWeb` is also available as a Mercurial repository using the forest
- extension (see :ref:`MercurialForestInstall` for more details).
+or keep up to date with on-going development by using Mercurial and its forest
+extension::
+ hg fclone http://www.logilab.org/hg/forests/cubicweb
+
+See :ref:`MercurialPresentation` for more details about Mercurial.
Postgres installation
`````````````````````
-Please refer to the project online documentation Postgres_.
+Please refer to the `Postgresql project online documentation`_.
-.. _Postgres: http://www.postgresql.org/
+.. _`Postgresql project online documentation`: http://www.postgresql.org/
You need to install the three following packages: `postgres-8.3`,
`postgres-contrib-8.3` and `postgresql-plpython-8.3`.
@@ -69,26 +79,18 @@
Environment configuration
-------------------------
-[FIXME]
-Ces variables ne sont plus requises pour le bon fonctionnement de `CubicWeb`, non?
-A part rajouter la foret dans le PYTHONPATH, rien de plus ne doit etre fait?
-
-Update the environment variable PYTHONPATH to add to it the path to
-the forest ``cubicweb``.
+If you installed `CubicWeb` by cloning the Mercurial forest, then you
+will need to update the environment variable PYTHONPATH to add to it
+the path to the forest ``cubicweb``.
Add the following lines to either `.bashrc` or `.bash_profile` to configure
your development environment ::
export PYTHONPATH=/full/path/to/cubicweb-forest
-
- //deprecated??
- export ERUDI_REGISTRY=~/etc/erudi.d/
- export ERUDI_TEMPLATES=~/hg/
- export ERUDI_RUNTIME=/tmp/
-Cela suppose que le composant erudi que vous développez est dans un
-sous-répertoire de *~/hg/* et que vous avez créé le répertoire *~/etc/erudi.d/*
-pour que `cubicweb-ctl` y place vos instances de test.
+If you installed the debian packages, no configuration is required.
+Your new cubes will be placed in `/usr/share/cubicweb/cubes` and
+your applications will be placed in `/etc/cubicweb.d`.
.. _ConfigurationPostgres:
--- a/doc/book/en/C012-create-instance.en.txt Tue Dec 23 14:42:41 2008 +0100
+++ b/doc/book/en/C012-create-instance.en.txt Tue Dec 23 14:42:52 2008 +0100
@@ -22,8 +22,10 @@
What is a cube?
---------------
-A cube defines entities, their views, their schems and workflows
-in an independant directory located in ``/path/to/forest/cubicweb/cubes/``.
+A cube defines entities, their views, their schemas and workflows
+in an independant directory located in ``/path/to/forest/cubicweb/cubes/``
+for a Mercurila installation or in ``/usr/share/cubicweb/cubes`` for
+a debian packages installation.
When an instance is created, you list one or more cubes that your instance
will use. Use a cube means having the entities defined in your cube's schema
--- a/doc/book/en/C013-cubicweb-ctl.en.txt Tue Dec 23 14:42:41 2008 +0100
+++ b/doc/book/en/C013-cubicweb-ctl.en.txt Tue Dec 23 14:42:52 2008 +0100
@@ -118,6 +118,8 @@
cubicweb-ctl newcube <mycube>
This will create a new cube in ``/path/to/forest/cubicweb/cubes/<mycube>``
-and then create an instance as explained just above.
+for a Mercurial forest installation, or in ``/usr/share/cubicweb/cubes``
+for a debian packages installation, and then create an instance as
+explained just above.
--- a/doc/book/en/C040-rql.en.txt Tue Dec 23 14:42:41 2008 +0100
+++ b/doc/book/en/C040-rql.en.txt Tue Dec 23 14:42:52 2008 +0100
@@ -43,36 +43,31 @@
which may need to be guided at one time or another.
Finally, the syntax is a little esoteric.
-See also
-``````````
-RDFQL_
+Sparql
+``````
+
+The query language most similar to RQL is SPARQL_, defined by the W3C to serve
+for the semantic web.
The different types of queries
------------------------------
-Search ( `Any`)
+Search (`Any`)
This type of query can extract entities and attributes of entities.
-Inserting entities ( `INSERT`)
+Inserting entities (`INSERT`)
This type of query is used to insert new entities in the database. It
will also create direct relationships entities newly created.
-Update entities, relations creation( `SET`)
+Update entities, relations creation (`SET`)
This type of query updates existing entities in the database,
or create relations between existing entities.
-Deletion of entities or relationship ( `DELETE`)
+Deletion of entities or relationship (`DELETE`)
This type of query allows for the removal of entities and relations existing
in the database.
-
-
-Examples
-========
-
-(see the tutorial: ref: `tutorielRQL` for more examples)
-
Search Query
------------
@@ -582,8 +577,8 @@
-.. _Versa: Http://uche.ogbuji.net/tech/rdf/versa/
-.. _RDFQL: Http://www.w3.org/TandS/QL/QL98/pp/rdfquery.html
+.. _Versa: http://uche.ogbuji.net/tech/rdf/versa/
+.. _SPARQL: http://www.w3.org/TR/rdf-sparql-query/
-XXX see also RQL documentation in source rql/doc.
+[FIXME] see also RQL documentation in source rql/doc.
--- a/doc/book/en/D060-mercurial.en.txt Tue Dec 23 14:42:41 2008 +0100
+++ b/doc/book/en/D060-mercurial.en.txt Tue Dec 23 14:42:52 2008 +0100
@@ -16,6 +16,7 @@
It is also possible to get revisions from another repository or to export
its own revisions from the local repository to another repository.
+.. _Mercurial: http://www.selenic.com/mercurial/
In contrast to CVS/Subversion, we usually create a repository by
project to manage.
@@ -30,7 +31,7 @@
``````````````
* Create a local repository::
- hg clone ssh://orion//home/src/private/rep
+ hg clone ssh://myhost//home/src/repo
* See the contents of the local repository (graphical tool in Tk)::
@@ -38,7 +39,7 @@
* Add a sub-directory or file in the current directory::
- hg add rep
+ hg add subdir
* Move to the working directory a specific revision (or last
revision) from the local repository::
@@ -49,8 +50,8 @@
* Get in its local repository, the tree of revisions contained in a
remote repository (this does not change the local directory)::
- hg pull ssh://orion//home/src/private/rep
- hg pull-u ssh://orion//home/src/private/rep # equivalent to pull + update
+ hg pull ssh://myhost//home/src/repo
+ hg pull -u ssh://myhost//home/src/repo # equivalent to pull + update
* See what are the heads of branches of the local repository if a `pull`
returned a new branch::
@@ -72,15 +73,15 @@
* Export to a remote repository, the tree of revisions in its content
local respository (this does not change the local directory)::
- hg push ssh://orion//home/src/private/rep
+ hg push ssh://myhost//home/src/repo
* See what local revisions are not in another repository::
- hg outgoing ssh://orion//home/src/private/rep
+ hg outgoing ssh://myhost//home/src/repo
* See what are the revisions of a repository not found locally::
- hg incoming ssh://orion//home/src/private/rep
+ hg incoming ssh://myhost//home/src/repo
* See what is the revision of the local repository which has been taken out
from the working directory and amended::
@@ -97,18 +98,36 @@
Best Practices
``````````````
-* Think of making a `hg pull -u` regularly, and particularly before
+* Remember to `hg pull -u` regularly, and particularly before
a `hg commit`.
-* Think of a `hg push` when your repository contains a version
+* Remember to `hg push` when your repository contains a version
relatively stable of your changes.
-* If a `hg pull u` created a new branch head:
+* If a `hg pull -u` created a new branch head:
- 1. identify its identifier with `hg head`
+ 1. find its identifier with `hg head`
2. merge with `hg merge`
3. `hg ci`
4. `hg push`
+Installation of the forest extension
+````````````````````````````````````
-.. include:: D061-mercurial-forest.en.txt
+Set up the forest extension by getting a copy of the sources
+from http://hg.akoha.org/hgforest/ and adding the following
+lines to your ``~/.hgrc``: ::
+
+ [extensions]
+ hgext.forest=
+ # or, if forest.py is not in the hgext dir:
+ # forest=/path/to/forest.py
+
+
+More information
+````````````````
+
+For more information about Mercurial, please refer to the Mercurial project online documentation_.
+
+.. _documentation: http://www.selenic.com/mercurial/wiki/
+
--- a/doc/book/en/D061-mercurial-forest.en.txt Tue Dec 23 14:42:41 2008 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,52 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _MercurialForestInstall:
-
-Installation of `CubicWeb` with Mercurial
-=========================================
-
-`CubicWeb` is available as a Mercurial repository using the forest extension.
-First make sure Mercurial is installed and that the forest extension is
-available.
-
-Mercurial installation
-``````````````````````
-
-Please refer to the project online documentation Mercurial_.
-
-.. _Mercurial: http://www.selenic.com/mercurial/wiki/
-
-We also provide in this book a quick guide on how to use
-Mercurial (:ref:`MercurialPresentation`).
-
-
-Installation of the forest extension
-````````````````````````````````````
-
-Set up the forest extension by getting a copy of the sources
-from http://hg.akoha.org/hgforest/ and adding the following
-lines to your ``~/.hgrc``: ::
-
- [extensions]
- hgext.forest=
- # or, if forest.py is not in the hgext dir:
- # forest=/path/to/forest.py
-
-Get `CubicWeb` source code
-``````````````````````````
-
-Clone the forest in you working directory.
-
-::
-
- hg fclone http://www.logilab.org/hg/forests/cubicweb
-
-.. note::
- We recommand you to create a symbolic link to the command ``cubicweb-ctl``
- as you will use it pretty often.
-
- ::
-
- $ ln -s /path/to/forest/cubicweb/bin/cubicweb-ctl ~/bin
-
-