--- a/doc/book/en/A020-tutorial.en.txt Mon Apr 27 10:02:58 2009 +0200
+++ b/doc/book/en/A020-tutorial.en.txt Mon Apr 27 10:48:21 2009 +0200
@@ -17,10 +17,9 @@
An `instance` is a specific installation of an application and includes
configuration files.
-This tutorial will first discuss how easy it is to build a new `instance` based on
-existing `cubes`. Then we'll see how we can develop new `cube`. We'll conclude
-by illustrating the flexibility of the framework that enable us to
-entirely customize your `instance`.
+
+This tutorial will show how to create a `cube` and how to use it as an
+application to run an `instance`.
.. include:: Z013-blog-less-ten-minutes.en.txt
.. include:: A02a-create-cube.en.txt
--- a/doc/book/en/A02b-components.en.txt Mon Apr 27 10:02:58 2009 +0200
+++ b/doc/book/en/A02b-components.en.txt Mon Apr 27 10:48:21 2009 +0200
@@ -68,7 +68,7 @@
Once you modified your data model, you need to synchronize the
database with your model. For this purpose, `CubicWeb` provides
-a very usefull command ``cubicweb-ctl shell blogdemo`` which
+a very useful command ``cubicweb-ctl shell blogdemo`` which
launches an interactive migration Python shell. (see
:ref:`cubicweb-ctl-shell` for more details))
As you modified a relation from the `BlogEntry` schema,
--- a/doc/book/en/B0012-schema-definition.en.txt Mon Apr 27 10:02:58 2009 +0200
+++ b/doc/book/en/B0012-schema-definition.en.txt Mon Apr 27 10:48:21 2009 +0200
@@ -124,7 +124,7 @@
or not within all entities of the same type (false by default)
- `indexed` : boolean indicating if an index needs to be created for this
- attribute in the database (false by default). This is usefull only if
+ attribute in the database (false by default). This is useful only if
you know that you will have to run numerous searches on the value of this
attribute.
--- a/doc/book/en/C000-administration.en.txt Mon Apr 27 10:02:58 2009 +0200
+++ b/doc/book/en/C000-administration.en.txt Mon Apr 27 10:48:21 2009 +0200
@@ -13,7 +13,8 @@
:maxdepth: 1
C010-setup.en.txt
- C020-site-config.en.txt
- C030-instance-config.en.txt
- C040-rql.en.txt
+ C020-create-instance.en.txt
+ C030-site-config.en.txt
+ C040-instance-config.en.txt
+ C050-rql.en.txt
--- a/doc/book/en/C010-setup.en.txt Mon Apr 27 10:02:58 2009 +0200
+++ b/doc/book/en/C010-setup.en.txt Mon Apr 27 10:48:21 2009 +0200
@@ -6,6 +6,202 @@
Installation and set-up of a `CubicWeb` environment
===================================================
-.. include:: C011-installation.en.txt
-.. include:: C012-create-instance.en.txt
+Installation of `Cubicweb` and its dependencies
+-----------------------------------------------
+
+`CubicWeb` is packaged for Debian and Ubuntu, but can be installed from source
+using a tarball or the Mercurial version control system.
+
+.. _DebianInstallation:
+
+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``).
+
+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/
+
+
+You can now install the required packages with the following command::
+
+ apt-get update
+ apt-get install cubicweb cubicweb-dev
+
+`cubicweb` installs the framework itself, allowing you to create
+new applications.
+
+`cubicweb-dev` installs the development environment allowing you to
+develop new cubes.
+
+There is also a wide variety of cubes listed on http://www.cubicweb.org/Project available as debian packages and tarball.
+
+
+Install from source
+```````````````````
+
+You can download the archive containing the sources from our `ftp site`_ at::
+
+ http://ftp.logilab.org/pub/cubicweb/
+
+.. _`ftp site`: http://ftp.logilab.org/pub/cubicweb/
+
+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 `Postgresql project online documentation`_.
+
+.. _`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`.
+
+
+Then you can install:
+
+* `pyro` if you wish the repository to be accessible through Pyro
+ or if the client and the server are not running on the same machine
+ (in which case the packages will have to be installed on both
+ machines)
+
+* `python-ldap` if you plan to use a LDAP source on the server
+
+.. _ConfigurationEnv:
+
+Environment configuration
+-------------------------
+
+If you installed `CubicWeb` by cloning the Mercurial forest, then you
+will need to update the environment variable PYTHONPATH by adding
+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
+
+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`.
+
+To use others directories then you will have to configure the
+following environment variables as follows::
+ export CW_CUBES_PATH=~/lib/cubes
+ export CW_REGISTRY=~/etc/cubicweb.d/
+ export CW_INSTANCE_DATA=$CW_REGISTRY
+ export CW_RUNTIME=/tmp
+
+.. note::
+ The values given above are our suggestions but of course
+ can be different.
+
+
+Databases configuration
+-----------------------
+
+
+
+.. _ConfigurationPostgres:
+
+Postgres configuration
+``````````````````````
+
+.. note::
+ If you already have an existing cluster and postgres server
+ running, you do not need to execute the initilization step
+ of your Postgres database.
+
+* First, initialize the database Postgres with the command ``initdb``.
+ ::
+
+ $ initdb -D /path/to/pgsql
+
+ Once initialized, start the database server Postgres
+ with the command::
+
+ $ postgres -D /path/to/psql
+
+ If you cannot execute this command due to permission issues, please
+ make sure that your username has write access on the database.
+ ::
+
+ $ chown username /path/to/pgsql
+
+* The database authentication can be either set to `ident sameuser`
+ or `md5`.
+ If set to `md5`, make sure to use an existing user
+ of your database.
+ If set to `ident sameuser`, make sure that your
+ client's operating system user name has a matching user in
+ the database. If not, please do as follow to create a user::
+
+ $ su
+ $ su - postgres
+ $ createuser -s -P username
+
+ The option `-P` (for password prompt), will encrypt the password with
+ the method set in the configuration file ``pg_hba.conf``.
+ If you do not use this option `-P`, then the default value will be null
+ and you will need to set it with::
+
+ $ su postgres -c "echo ALTER USER username WITH PASSWORD 'userpasswd' | psql"
+
+ This login/password will be requested when you will create an
+ instance with `cubicweb-ctl create` to initialize the database of
+ your application.
+
+.. note::
+ The authentication method can be configured in ``pg_hba.conf``.
+
+
+.. FIXME Are these steps really necessary? It seemed to work without.
+
+* Installation of plain-text index extension ::
+
+ cat /usr/share/postgresql/8.3/contrib/tsearch2.sql | psql -U username template1
+
+* Installation of plpythonu language by default ::
+
+ createlang -U pgadmin plpythonu template1
+
+MySql configuration
+```````````````````
+Yout must add the following lines in /etc/mysql/my.cnf file::
+
+ transaction-isolation = READ-COMMITTED
+ default-storage-engine=INNODB
+ default-character-set=utf8
+ max_allowed_packet = 128M
+
+Pyro configuration
+------------------
+
+If you use Pyro, it is required to have a name server Pyro running on your
+network (by default it is detected by a broadcast request).
+
+To do so, you need to :
+
+* launch the server manually before starting cubicweb as a server with
+ `pyro-nsd start`
+
+* edit the file ``/etc/default/pyro-nsd`` so that the name server pyro
+ will be launched automatically when the machine fire up
+
--- a/doc/book/en/C011-installation.en.txt Mon Apr 27 10:02:58 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,201 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _CubicWebInstallation:
-
-Installation
-============
-
-Installation of `Cubicweb` and its dependencies
------------------------------------------------
-
-`CubicWeb` is packaged for Debian and Ubuntu, but can be installed from source
-using a tarball or the Mercurial version control system.
-
-.. _DebianInstallation:
-
-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``).
-
-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/
-
-
-You can now install the required packages with the following command::
-
- apt-get update
- apt-get install cubicweb cubicweb-dev
-
-`cubicweb` installs the framework itself, allowing you to create
-new applications.
-
-`cubicweb-dev` installs the development environment allowing you to
-develop new cubes.
-
-There is also a wide variety of cubes listed on http://www.cubicweb.org/Project available as debian packages and tarball.
-
-
-Install from source
-```````````````````
-
-You can download the archive containing the sources from our `ftp site`_ at::
-
- http://ftp.logilab.org/pub/cubicweb/
-
-.. _`ftp site`: http://ftp.logilab.org/pub/cubicweb/
-
-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 `Postgresql project online documentation`_.
-
-.. _`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`.
-
-
-Then you can install:
-
-* `pyro` if you wish the repository to be accessible through Pyro
- or if the client and the server are not running on the same machine
- (in which case the packages will have to be installed on both
- machines)
-
-* `python-ldap` if you plan to use a LDAP source on the server
-
-.. _ConfigurationEnv:
-
-Environment configuration
--------------------------
-
-If you installed `CubicWeb` by cloning the Mercurial forest, then you
-will need to update the environment variable PYTHONPATH by adding
-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
-
-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`.
-
-To use others directories then you will have to configure the
-following environment variables as follows::
-
- export CW_CUBES_PATH=~/lib/cubes
- export CW_REGISTRY=~/etc/cubicweb.d/
- export CW_INSTANCE_DATA=$CW_REGISTRY
- export CW_RUNTIME=/tmp
-
-.. note::
- The values given above are our suggestions but of course
- can be different.
-
-.. _ConfigurationPostgres:
-
-Postgres configuration
-----------------------
-
-.. note::
- If you already have an existing cluster and postgres server
- running, you do not need to execute the initilization step
- of your Postgres database.
-
-* First, initialize the database Postgres with the command ``initdb``.
- ::
-
- $ initdb -D /path/to/pgsql
-
- Once initialized, start the database server Postgres
- with the command::
-
- $ postgres -D /path/to/psql
-
- If you cannot execute this command due to permission issues, please
- make sure that your username has write access on the database.
- ::
-
- $ chown username /path/to/pgsql
-
-* The database authentication can be either set to `ident sameuser`
- or `md5`.
- If set to `md5`, make sure to use an existing user
- of your database.
- If set to `ident sameuser`, make sure that your
- client's operating system user name has a matching user in
- the database. If not, please do as follow to create a user::
-
- $ su
- $ su - postgres
- $ createuser -s -P username
-
- The option `-P` (for password prompt), will encrypt the password with
- the method set in the configuration file ``pg_hba.conf``.
- If you do not use this option `-P`, then the default value will be null
- and you will need to set it with::
-
- $ su postgres -c "echo ALTER USER username WITH PASSWORD 'userpasswd' | psql"
-
- This login/password will be requested when you will create an
- instance with `cubicweb-ctl create` to initialize the database of
- your application.
-
-.. note::
- The authentication method can be configured in ``pg_hba.conf``.
-
-
-.. FIXME Are these steps really necessary? It seemed to work without.
-
-* Installation of plain-text index extension ::
-
- cat /usr/share/postgresql/8.3/contrib/tsearch2.sql | psql -U username template1
-
-* Installation of plpythonu language by default ::
-
- createlang -U pgadmin plpythonu template1
-
-MySql configuration
--------------------
-Yout must add the following lines in /etc/mysql/my.cnf file::
-
- transaction-isolation = READ-COMMITTED
- default-storage-engine=INNODB
- default-character-set=utf8
- max_allowed_packet = 128M
-
-Pyro configuration
-------------------
-
-If you use Pyro, it is required to have a name server Pyro running on your
-network (by default it is detected by a broadcast request).
-
-To do so, you need to :
-
-* launch the server manually before starting cubicweb as a server with
- `pyro-nsd start`
-
-* edit the file ``/etc/default/pyro-nsd`` so that the name server pyro
- will be launched automatically when the machine fire up
-
-
--- a/doc/book/en/C012-create-instance.en.txt Mon Apr 27 10:02:58 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,132 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Creation of your first instance
-===============================
-
-What is an instance?
---------------------
-
-A `CubicWeb` instance is a directory in ``~/etc/cubicweb.d``
-which enables us to run a web application. An instance is based on
-a cube.
-
-An instance is a container that refers to cubes and configuration
-parameters for your web application.
-
-We recommand not to define schema, entities or views in the instance
-file system itself but in the cube, in order to maintain re-usability of
-entities and their views. We strongly recommand to develop cubes which
-could be used in other instances (modular approach).
-
-
-What is a cube?
----------------
-
-A cube defines entities, their views, their schemas and workflows
-in an independant directory located in ``/path/to/forest/cubicweb/cubes/``
-for a Mercurial installation or in ``/usr/share/cubicweb/cubes`` for
-a debian package installation.
-
-When an instance is created, you list one or more cubes that your instance
-will use. Using a cube means having the entities defined in your cube's schema
-available in your instance as well as their views and workflows.
-
-.. note::
- The commands used below are more detailled in the section dedicated to
- :ref:`cubicweb-ctl`.
-
-
-Create a cube
--------------
-
-Let's start by creating the cube environment in which we will develop ::
-
- cd ~/hg
-
- cubicweb-ctl newcube mycube
-
- # answer questions
- hg init moncube
- cd mycube
- hg add .
- hg ci
-
-If all went well, you should see the cube you just create in the list
-returned by `cubicweb-ctl list` in the section *Available components*,
-and if it is not the case please refer to :ref:`ConfigurationEnv`.
-
-To use a cube, you have to list it in the variable ``__use__``
-of the file ``__pkginfo__.py`` of the instance.
-This variable is used for the instance packaging (dependencies
-handled by system utility tools such as APT) and the usable cubes
-at the time the base is created (import_erschema('MyCube') will
-not properly work otherwise).
-
-.. note::
- Please note that if you do not wish to use default directory
- for your cubes library, then you want to use the option
- --directory to specify where you would like to place
- the source code of your cube:
- ``cubicweb-ctl newcube --directory=/path/to/cubes/library cube_name``
-
-Instance creation
------------------
-
-Now that we created our cube, we can create an instance to view our
-application in a web browser. To do so we will use a `all-in-on`
-configuration to simplify things ::
-
- cubicweb-ctl create -c all-in-one mycube myinstance
-
-.. note::
- Please note that we created a new cube for a demo purpose but
- you could have use an existing cube available in our standard library
- such as blog or person for example.
-
-A serie of questions will be prompted to you, the default answer is usually
-sufficient. You can anyway modify the configuration later on by editing
-configuration files. When a user/psswd is requested to access the database
-please use the login you create at the time you configured the database
-(:ref:`ConfigurationPostgres`).
-
-It is important to distinguish here the user used to access the database and
-the user used to login to the cubicweb application. When a `CubicWeb` application
-starts, it uses the login/psswd for the database to get the schema and handle
-low level transaction. But, when ``cubicweb-ctl create`` asks for
-a manager login/psswd of `CubicWeb`, it refers to an application user you will
-use during the development to administrate your web application. It will be
-possible, later on, to create others users for your final web application.
-
-When this command is completed, the definition of your instance is
-located in *~/etc/cubicweb.d/myinstance/*. To launch it, you just type ::
-
- cubicweb-ctl start -D myinstance
-
-The option `-D` specify the *debug mode* : the instance is not running in
-server mode and does not disconnect from the termnial, which simplifies debugging
-in case the instance is not properly launched. You can see how it looks by
-visiting the URL `http://localhost:8080` (the port number depends of your
-configuration). To login, please use the cubicweb administrator login/psswd you
-defined when you created the instance.
-
-To shutdown the instance, Crtl-C in the terminal window is enough.
-If you did not use the option `-D`, then type ::
-
- cubicweb-ctl stop myinstance
-
-This is it! All is settled down to start developping your data model...
-
-
-Usage of `cubicweb-liveserver`
-``````````````````````````````
-
-To quickly test a new cube, you can also use the script `cubicweb-liveserver`
-which allows to create an application in memory (use of SQLite database by
-default) and make it accessible through a web server ::
-
- cubicweb-ctl live-server mycube
-
-or by using an existing database (SQLite or Postgres)::
-
- cubicweb-ctl live-server -s myfile_sources mycube
-
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/C020-create-instance.en.txt Mon Apr 27 10:48:21 2009 +0200
@@ -0,0 +1,132 @@
+.. -*- coding: utf-8 -*-
+
+Creation of your first instance
+===============================
+
+What is an instance?
+--------------------
+
+A `CubicWeb` instance is a directory in ``~/etc/cubicweb.d``
+which enables us to run a web application. An instance is based on
+a cube.
+
+An instance is a container that refers to cubes and configuration
+parameters for your web application.
+
+We recommand not to define schema, entities or views in the instance
+file system itself but in the cube, in order to maintain re-usability of
+entities and their views. We strongly recommand to develop cubes which
+could be used in other instances (modular approach).
+
+
+What is a cube?
+---------------
+
+A cube defines entities, their views, their schemas and workflows
+in an independant directory located in ``/path/to/forest/cubicweb/cubes/``
+for a Mercurial installation or in ``/usr/share/cubicweb/cubes`` for
+a debian package installation.
+
+When an instance is created, you list one or more cubes that your instance
+will use. Using a cube means having the entities defined in your cube's schema
+available in your instance as well as their views and workflows.
+
+.. note::
+ The commands used below are more detailled in the section dedicated to
+ :ref:`cubicweb-ctl`.
+
+
+Create a cube
+-------------
+
+Let's start by creating the cube environment in which we will develop ::
+
+ cd ~/hg
+
+ cubicweb-ctl newcube mycube
+
+ # answer questions
+ hg init moncube
+ cd mycube
+ hg add .
+ hg ci
+
+If all went well, you should see the cube you just create in the list
+returned by `cubicweb-ctl list` in the section *Available components*,
+and if it is not the case please refer to :ref:`ConfigurationEnv`.
+
+To use a cube, you have to list it in the variable ``__use__``
+of the file ``__pkginfo__.py`` of the instance.
+This variable is used for the instance packaging (dependencies
+handled by system utility tools such as APT) and the usable cubes
+at the time the base is created (import_erschema('MyCube') will
+not properly work otherwise).
+
+.. note::
+ Please note that if you do not wish to use default directory
+ for your cubes library, then you want to use the option
+ --directory to specify where you would like to place
+ the source code of your cube:
+ ``cubicweb-ctl newcube --directory=/path/to/cubes/library cube_name``
+
+Instance creation
+-----------------
+
+Now that we created our cube, we can create an instance to view our
+application in a web browser. To do so we will use a `all-in-on`
+configuration to simplify things ::
+
+ cubicweb-ctl create -c all-in-one mycube myinstance
+
+.. note::
+ Please note that we created a new cube for a demo purpose but
+ you could have use an existing cube available in our standard library
+ such as blog or person for example.
+
+A serie of questions will be prompted to you, the default answer is usually
+sufficient. You can anyway modify the configuration later on by editing
+configuration files. When a user/psswd is requested to access the database
+please use the login you create at the time you configured the database
+(:ref:`ConfigurationPostgres`).
+
+It is important to distinguish here the user used to access the database and
+the user used to login to the cubicweb application. When a `CubicWeb` application
+starts, it uses the login/psswd for the database to get the schema and handle
+low level transaction. But, when ``cubicweb-ctl create`` asks for
+a manager login/psswd of `CubicWeb`, it refers to an application user you will
+use during the development to administrate your web application. It will be
+possible, later on, to create others users for your final web application.
+
+When this command is completed, the definition of your instance is
+located in *~/etc/cubicweb.d/myinstance/*. To launch it, you just type ::
+
+ cubicweb-ctl start -D myinstance
+
+The option `-D` specify the *debug mode* : the instance is not running in
+server mode and does not disconnect from the termnial, which simplifies debugging
+in case the instance is not properly launched. You can see how it looks by
+visiting the URL `http://localhost:8080` (the port number depends of your
+configuration). To login, please use the cubicweb administrator login/psswd you
+defined when you created the instance.
+
+To shutdown the instance, Crtl-C in the terminal window is enough.
+If you did not use the option `-D`, then type ::
+
+ cubicweb-ctl stop myinstance
+
+This is it! All is settled down to start developping your data model...
+
+
+Usage of `cubicweb-liveserver`
+``````````````````````````````
+
+To quickly test a new cube, you can also use the script `cubicweb-liveserver`
+which allows to create an application in memory (use of SQLite database by
+default) and make it accessible through a web server ::
+
+ cubicweb-ctl live-server mycube
+
+or by using an existing database (SQLite or Postgres)::
+
+ cubicweb-ctl live-server -s myfile_sources mycube
+
--- a/doc/book/en/C020-site-config.en.txt Mon Apr 27 10:02:58 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,94 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-User interface for web site configuration
-=========================================
-
-.. image:: images/lax-book.03-site-config-panel.en.png
-
-This panel allows you to configure the appearance of your application site.
-Six menus are available and we will go through each of them to explain how
-to use them.
-
-Navigation
-~~~~~~~~~~
-This menu provides you a way to adjust some navigation options depending on
-your needs, such as the number of entities to display by page of results.
-Follows the detailled list of available options :
-
-* navigation.combobox-limit : maximum number of entities to display in related
- combo box (sample format: 23)
-* navigation.page-size : maximum number of objects displayed by page of results
- (sample format: 23)
-* navigation.related-limit : maximum number of related entities to display in
- the primary view (sample format: 23)
-* navigation.short-line-size : maximum number of characters in short description
- (sample format: 23)
-
-UI
-~~
-This menu provides you a way to customize the user interface settings such as
-date format or encoding in the produced html.
-Follows the detailled list of available options :
-
-* ui.date-format : how to format date in the ui ("man strftime" for format description)
-* ui.datetime-format : how to format date and time in the ui ("man strftime" for format
- description)
-* ui.default-text-format : default text format for rich text fields.
-* ui.encoding : user interface encoding
-* ui.fckeditor :should html fields being edited using fckeditor (a HTML WYSIWYG editor).
- You should also select text/html as default text format to actually get fckeditor.
-* ui.float-format : how to format float numbers in the ui
-* ui.language : language of the user interface
-* ui.main-template : id of main template used to render pages
-* ui.site-title : site title, which is displayed right next to the logo in the header
-* ui.time-format : how to format time in the ui ("man strftime" for format description)
-
-
-Actions
-~~~~~~~
-This menu provides a way to configure the context in which you expect the actions
-to be displayed to the user and if you want the action to be visible or not.
-You must have notice that when you view a list of entities, an action box is
-available on the left column which display some actions as well as a drop-down
-menu for more actions.
-
-The context available are :
-
-* mainactions : actions listed in the left box
-* moreactions : actions listed in the `more` menu of the left box
-* addrelated : add actions listed in the left box
-* useractions : actions listed in the first section of drop-down menu
- accessible from the right corner user login link
-* siteactions : actions listed in the second section of drop-down menu
- accessible from the right corner user login link
-* hidden : select this to hide the specific action
-
-Boxes
-~~~~~
-The application has already a pre-defined set of boxes you can use right away.
-This configuration section allows you to place those boxes where you want in the
-application interface to customize it.
-
-The available boxes are :
-
-* actions box : box listing the applicable actions on the displayed data
-
-* boxes_blog_archives_box : box listing the blog archives
-
-* possible views box : box listing the possible views for the displayed data
-
-* rss box : RSS icon to get displayed data as a RSS thread
-
-* search box : search box
-
-* startup views box : box listing the configuration options available for
- the application site, such as `Preferences` and `Site Configuration`
-
-Components
-~~~~~~~~~~
-[WRITE ME]
-
-Contextual components
-~~~~~~~~~~~~~~~~~~~~~
-[WRITE ME]
-
--- a/doc/book/en/C030-instance-config.en.txt Mon Apr 27 10:02:58 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,163 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-
-Configure an instance
-=====================
-
-While creating an instance, a configuration file is generated in::
-
- $ (CW_REGISTRY) / <instance> / <configuration name>.conf
-
-For example::
-
- /etc/cubicweb.d/JPL/all-in-one.conf
-
-It is a simple text file format INI. In the following description,
-each option name is prefixed with its own section and followed by its
-default value if necessary, e.g. "`<section>.<option>` [value]."
-
-
-Configuring the Web server
---------------------------
-:`web.auth-model` [cookie]:
- authentication mode, cookie or http
-:`web.realm`:
- realm of the application in http authentication mode
-:`web.http-session-time` [0]:
- period of inactivity of an HTTP session before it closes automatically.
- Duration in seconds, 0 meaning no expiration (or more exactly at the
- closing of the browser client)
-
-:`main.anonymous-user`, `main.anonymous-password`:
- login and password to use to connect to the RQL server with
- HTTP anonymous connection. EUser account should exist.
-
-:`main.base-url`:
- url base site to be used to generate the urls of web pages
-
-Https configuration
-```````````````````
-It is possible to make a site accessible for anonymous http connections
-and https for authenticated users. This requires to
-use apache (for example) for redirection and the variable `main.https-url`
-of configuration file.
-
-:Example:
-
- For an apache redirection of a site accessible via `http://localhost/demo`
- and `https://localhost/demo` and actually running on port 8080, it
- takes to the http:::
-
- RewriteCond %(REQUEST_URI) ^/demo
- RewriteRule ^/demo$/demo/
- RewriteRule ^/demo/(.*) http://127.0.0.1:8080/$1 [L,P]
-
- and for the https:::
-
- RewriteCond %(REQUEST_URI) ^/ demo
- RewriteRule ^/demo$/demo/
- RewriteRule ^/demo/(.*) http://127.0.0.1:8080/https/$1 [L,P]
-
-
- and we will file in the all-in-one.conf of the instance:::
-
- base-url = http://localhost/demo
- https-url = `https://localhost/demo`
-
-Setting up the web
---------------------------------
-:`web.embed-allowed`:
- regular expression matching sites which could be "embedded" in
- the site (controllers 'embed')
-:`web.submit-url`:
- url where the bugs encountered in the application can be mailed to
-
-
-RQL server configuration
-------------------------
-:`main.host`:
- host name if it can not be detected correctly
-:`main.pid-file`:
- file where will be written the server pid
-:`main.uid`:
- user account to use for launching the server when it is
- root launched by init
-:`main.session-time [30*60]`:
- timeout of a RQL session
-:`main.query-log-file`:
- file where all requests RQL executed by the server are written
-
-
-Pyro configuration for the instance
------------------------------------
-Web server side:
-
-:`pyro-client.pyro-application-id`:
- pyro identifier of RQL server (e.g. the instance name)
-
-RQL server side:
-
-:`pyro-server.pyro-port`:
- pyro port number. If none is specified, a port is assigned
- automatically.
-
-RQL and web servers side:
-
-:`pyro-name-server.pyro-ns-host`:
- hostname hosting pyro server name. If no value is
- specified, it is located by a request from broadcast
-:`pyro-name-server.pyro-ns-group` [cubicweb]:
- pyro group in which to save the application
-
-
-Configuring e-mail
-------------------
-RQL and web server side:
-
-:`email.mangle-mails [no]`:
- indicates whether the email addresses must be displayed as is or
- transformed
-
-RQL server side:
-
-:`email.smtp-host [mail]`:
- hostname hosting the SMTP server to use for outgoing mail
-:`email.smtp-port [25]`:
- SMTP server port to use for outgoing mail
-:`email.sender-name`:
- name to use for outgoing mail of the application
-:`email.sender-addr`:
- address for outgoing mail of the application
-:`email.default dest-addrs`:
- destination addresses by default, if used by the configuration of the
- dissemination of the model (separated by commas)
-:`email.supervising-addrs`:
- destination addresses of e-mails of supervision (separated by
- commas)
-
-
-Configuring logging
--------------------
-:`main.log-threshold`:
- level of filtering messages (DEBUG, INFO, WARNING, ERROR)
-:`main.log-file`:
- file to write messages
-
-
-Configuring Eproperties
------------------------
-Other configuration settings are in the form of entities `EProperty`
-in the database. It must be edited via the web interface or by
-RQL queries.
-
-:`ui.encoding`:
- Character encoding to use for the web
-:`navigation.short-line-size`: # XXX should be in ui
- number of characters for "short" display
-:`navigation.page-size`:
- maximum number of entities to show per results page
-:`navigation.related-limit`:
- number of related entities to show up on primary entity view
-:`navigation.combobox-limit`:
- number of entities unrelated to show up on the drop-down lists of
- the sight on an editing entity view
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/C030-site-config.en.txt Mon Apr 27 10:48:21 2009 +0200
@@ -0,0 +1,94 @@
+.. -*- coding: utf-8 -*-
+
+User interface for web site configuration
+=========================================
+
+.. image:: images/lax-book.03-site-config-panel.en.png
+
+This panel allows you to configure the appearance of your application site.
+Six menus are available and we will go through each of them to explain how
+to use them.
+
+Navigation
+~~~~~~~~~~
+This menu provides you a way to adjust some navigation options depending on
+your needs, such as the number of entities to display by page of results.
+Follows the detailled list of available options :
+
+* navigation.combobox-limit : maximum number of entities to display in related
+ combo box (sample format: 23)
+* navigation.page-size : maximum number of objects displayed by page of results
+ (sample format: 23)
+* navigation.related-limit : maximum number of related entities to display in
+ the primary view (sample format: 23)
+* navigation.short-line-size : maximum number of characters in short description
+ (sample format: 23)
+
+UI
+~~
+This menu provides you a way to customize the user interface settings such as
+date format or encoding in the produced html.
+Follows the detailled list of available options :
+
+* ui.date-format : how to format date in the ui ("man strftime" for format description)
+* ui.datetime-format : how to format date and time in the ui ("man strftime" for format
+ description)
+* ui.default-text-format : default text format for rich text fields.
+* ui.encoding : user interface encoding
+* ui.fckeditor :should html fields being edited using fckeditor (a HTML WYSIWYG editor).
+ You should also select text/html as default text format to actually get fckeditor.
+* ui.float-format : how to format float numbers in the ui
+* ui.language : language of the user interface
+* ui.main-template : id of main template used to render pages
+* ui.site-title : site title, which is displayed right next to the logo in the header
+* ui.time-format : how to format time in the ui ("man strftime" for format description)
+
+
+Actions
+~~~~~~~
+This menu provides a way to configure the context in which you expect the actions
+to be displayed to the user and if you want the action to be visible or not.
+You must have notice that when you view a list of entities, an action box is
+available on the left column which display some actions as well as a drop-down
+menu for more actions.
+
+The context available are :
+
+* mainactions : actions listed in the left box
+* moreactions : actions listed in the `more` menu of the left box
+* addrelated : add actions listed in the left box
+* useractions : actions listed in the first section of drop-down menu
+ accessible from the right corner user login link
+* siteactions : actions listed in the second section of drop-down menu
+ accessible from the right corner user login link
+* hidden : select this to hide the specific action
+
+Boxes
+~~~~~
+The application has already a pre-defined set of boxes you can use right away.
+This configuration section allows you to place those boxes where you want in the
+application interface to customize it.
+
+The available boxes are :
+
+* actions box : box listing the applicable actions on the displayed data
+
+* boxes_blog_archives_box : box listing the blog archives
+
+* possible views box : box listing the possible views for the displayed data
+
+* rss box : RSS icon to get displayed data as a RSS thread
+
+* search box : search box
+
+* startup views box : box listing the configuration options available for
+ the application site, such as `Preferences` and `Site Configuration`
+
+Components
+~~~~~~~~~~
+[WRITE ME]
+
+Contextual components
+~~~~~~~~~~~~~~~~~~~~~
+[WRITE ME]
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/C040-instance-config.en.txt Mon Apr 27 10:48:21 2009 +0200
@@ -0,0 +1,163 @@
+.. -*- coding: utf-8 -*-
+
+
+Configure an instance
+=====================
+
+While creating an instance, a configuration file is generated in::
+
+ $ (CW_REGISTRY) / <instance> / <configuration name>.conf
+
+For example::
+
+ /etc/cubicweb.d/JPL/all-in-one.conf
+
+It is a simple text file format INI. In the following description,
+each option name is prefixed with its own section and followed by its
+default value if necessary, e.g. "`<section>.<option>` [value]."
+
+
+Configuring the Web server
+--------------------------
+:`web.auth-model` [cookie]:
+ authentication mode, cookie or http
+:`web.realm`:
+ realm of the application in http authentication mode
+:`web.http-session-time` [0]:
+ period of inactivity of an HTTP session before it closes automatically.
+ Duration in seconds, 0 meaning no expiration (or more exactly at the
+ closing of the browser client)
+
+:`main.anonymous-user`, `main.anonymous-password`:
+ login and password to use to connect to the RQL server with
+ HTTP anonymous connection. EUser account should exist.
+
+:`main.base-url`:
+ url base site to be used to generate the urls of web pages
+
+Https configuration
+```````````````````
+It is possible to make a site accessible for anonymous http connections
+and https for authenticated users. This requires to
+use apache (for example) for redirection and the variable `main.https-url`
+of configuration file.
+
+:Example:
+
+ For an apache redirection of a site accessible via `http://localhost/demo`
+ and `https://localhost/demo` and actually running on port 8080, it
+ takes to the http:::
+
+ RewriteCond %(REQUEST_URI) ^/demo
+ RewriteRule ^/demo$ /demo/
+ RewriteRule ^/demo/(.*) http://127.0.0.1:8080/$1 [L,P]
+
+ and for the https:::
+
+ RewriteCond %(REQUEST_URI) ^/ demo
+ RewriteRule ^/demo$/demo/
+ RewriteRule ^/demo/(.*) http://127.0.0.1:8080/https/$1 [L,P]
+
+
+ and we will file in the all-in-one.conf of the instance:::
+
+ base-url = http://localhost/demo
+ https-url = `https://localhost/demo`
+
+Setting up the web
+--------------------------------
+:`web.embed-allowed`:
+ regular expression matching sites which could be "embedded" in
+ the site (controllers 'embed')
+:`web.submit-url`:
+ url where the bugs encountered in the application can be mailed to
+
+
+RQL server configuration
+------------------------
+:`main.host`:
+ host name if it can not be detected correctly
+:`main.pid-file`:
+ file where will be written the server pid
+:`main.uid`:
+ user account to use for launching the server when it is
+ root launched by init
+:`main.session-time [30*60]`:
+ timeout of a RQL session
+:`main.query-log-file`:
+ file where all requests RQL executed by the server are written
+
+
+Pyro configuration for the instance
+-----------------------------------
+Web server side:
+
+:`pyro-client.pyro-application-id`:
+ pyro identifier of RQL server (e.g. the instance name)
+
+RQL server side:
+
+:`pyro-server.pyro-port`:
+ pyro port number. If none is specified, a port is assigned
+ automatically.
+
+RQL and web servers side:
+
+:`pyro-name-server.pyro-ns-host`:
+ hostname hosting pyro server name. If no value is
+ specified, it is located by a request from broadcast
+:`pyro-name-server.pyro-ns-group` [cubicweb]:
+ pyro group in which to save the application
+
+
+Configuring e-mail
+------------------
+RQL and web server side:
+
+:`email.mangle-mails [no]`:
+ indicates whether the email addresses must be displayed as is or
+ transformed
+
+RQL server side:
+
+:`email.smtp-host [mail]`:
+ hostname hosting the SMTP server to use for outgoing mail
+:`email.smtp-port [25]`:
+ SMTP server port to use for outgoing mail
+:`email.sender-name`:
+ name to use for outgoing mail of the application
+:`email.sender-addr`:
+ address for outgoing mail of the application
+:`email.default dest-addrs`:
+ destination addresses by default, if used by the configuration of the
+ dissemination of the model (separated by commas)
+:`email.supervising-addrs`:
+ destination addresses of e-mails of supervision (separated by
+ commas)
+
+
+Configuring logging
+-------------------
+:`main.log-threshold`:
+ level of filtering messages (DEBUG, INFO, WARNING, ERROR)
+:`main.log-file`:
+ file to write messages
+
+
+Configuring Eproperties
+-----------------------
+Other configuration settings are in the form of entities `EProperty`
+in the database. It must be edited via the web interface or by
+RQL queries.
+
+:`ui.encoding`:
+ Character encoding to use for the web
+:`navigation.short-line-size`: # XXX should be in ui
+ number of characters for "short" display
+:`navigation.page-size`:
+ maximum number of entities to show per results page
+:`navigation.related-limit`:
+ number of related entities to show up on primary entity view
+:`navigation.combobox-limit`:
+ number of entities unrelated to show up on the drop-down lists of
+ the sight on an editing entity view
--- a/doc/book/en/C040-rql.en.txt Mon Apr 27 10:02:58 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,655 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _RQL:
-
-======================================
-RQL language (Relation Query Language)
-======================================
-
-Introduction
-============
-
-Goals of RQL
-------------
-
-The goal is to have a language emphasizing the way of browsing
-relations. As such, attributes will be regarded as cases of
-special relations (in terms of implementation, the language
-user should see virtually no difference between an attribute and a
-relation).
-
-RQL is inspired by SQL but is the highest level. A knowledge of the
-`CubicWeb` schema defining the application is necessary.
-
-Comparison with existing languages
-----------------------------------
-
-SQL
-```
-RQL builds on the features of SQL but is at a higher level
-(the current implementation of RQL generates SQL). For that it is limited
-to the way of browsing relations and introduces variables.
-The user does not need to know the model underlying SQL, but the `CubicWeb`
-schema defining the application.
-
-Versa
-`````
-We should look in more detail, but here are already some ideas for
-the moment ... Versa_ is the language most similar to what we wanted
-to do, but the model underlying data being RDF, there is some
-number of things such as namespaces or handling of the RDF types which
-does not interest us. On the functionality level, Versa_ is very comprehensive
-including through many functions of conversion and basic types manipulation,
-which may need to be guided at one time or another.
-Finally, the syntax is a little esoteric.
-
-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`)
- Extract entities and attributes of entities.
-
-Insert entities (`INSERT`)
- Insert new entities or relations in the database.
- It can also directly create relationships for the newly created entities.
-
-Update entities, create relations (`SET`)
- Update existing entities in the database,
- or create relations between existing entities.
-
-Delete entities or relationship (`DELETE`)
- Remove entities or relations existing in the database.
-
-Search Query
-------------
-
- [ `DISTINCT`] <entity type> V1 (V2) \ *
- [ `GROUPBY` V1 (V2) \*] [ `ORDERBY` <orderterms>]
- [ `WHERE` <restriction>]
- [ `LIMIT` <value>] [ `OFFSET` <value>]
-
-:entity type:
- Type of selected variables.
- The special type `Any` is equivalent to not specify a type.
-:restriction:
- list of conditions to test successively
- `V1 relation V2 | <static value>`
-:orderterms:
- Definition of the selection order: variable or column number followed by
- sorting method ( `ASC`, `DESC`), ASC is the default.
-:note for grouped queries:
- For grouped queries (e.g., a clause `GROUPBY`), all
- selected variables must be aggregated or grouped.
-
-
-
-- *Search for the object of identifier 53*
- ::
-
- Any WHERE X
- X eid 53
-
-- *Search material such as comics, owned by syt and available*
- ::
-
- WHERE X Document
- X occurence_of F, F class C, C name 'Comics'
- X owned_by U, U login 'syt'
- X available true
-
-- *Looking for people working for eurocopter interested in training*
- ::
-
- Any P WHERE
- P is Person, P work_for S, S name 'Eurocopter'
- P interested_by T, T name 'training'
-
-- *Search note less than 10 days old written by jphc or ocy*
- ::
-
- Any N WHERE
- N is Note, N written_on D, D day> (today -10),
- N written_by P, P name 'jphc' or P name 'ocy'
-
-- *Looking for people interested in training or living in Paris*
- ::
-
- Any P WHERE
- P is Person, (P interested_by T, T name 'training') OR
- (P city 'Paris')
-
-- *The name and surname of all people*
- ::
-
- Any N, P WHERE
- X is Person, X name N, X first_name P
-
- Note that the selection of several entities generally force
- the use of "Any" because the type specification applies otherwise
- to all the selected variables. We could write here
- ::
-
- String N, P WHERE
- X is Person, X name N, X first_name P
-
-
- Note: You can not specify several types with * ... where X is FirstType or X is SecondType*.
- To specify several types explicitely, you have to do
-
- ::
-
- Any X where X is in (FirstType, SecondType)
-
-
-Insertion query
----------------
-
- `INSERT` <entity type> V1 (, <entity type> V2) \ * `:` <assignments>
- [ `WHERE` <restriction>]
-
-:assignments:
- list of relations to assign in the form `V1 relationship V2 | <static value>`
-
-The restriction can define variables used in assignments.
-
-Caution, if a restriction is specified, the insertion is done for
-*each line result returned by the restriction*.
-
-- *Insert a new person named 'foo'*
- ::
-
- INSERT Person X: X name 'foo'
-
-- *Insert a new person named 'foo', another called 'nice' and a 'friend' relation
- between them*
- ::
-
- INSERT Person X, Person Y: X name 'foo', Y name 'nice', X friend Y
-
-- *Insert a new person named 'foo' and a 'friend' relation with an existing
- person called 'nice'*
- ::
-
- INSERT Person X: X name 'foo', X friend Y WHERE name 'nice'
-
-Update and relation creation queries
-------------------------------------
- `SET` <assignements>
- [ `WHERE` <restriction>]
-
-Caution, if a restriction is specified, the update is done *for
-each result line returned by the restriction*.
-
-- *Renaming of the person named 'foo' to 'bar' with the first name changed*
- ::
-
- SET X name 'bar', X first_name 'original' WHERE X is Person, X name 'foo'
-
-- *Insert a relation of type 'know' between objects linked by
- the relation of type 'friend'*
- ::
-
- SET X know Y WHERE X friend Y
-
-
-Deletion query
---------------
- `DELETE` (<entity type> V) | (V1 relation v2 ),...
- [ `WHERE` <restriction>]
-
-Caution, if a restriction is specified, the deletion is made *for
-each line result returned by the restriction*.
-
-- *Deletion of the person named 'foo'*
- ::
-
- DELETE Person X WHERE X name 'foo'
-
-- *Removal of all relations of type 'friend' from the person named 'foo'*
- ::
-
- DELETE X friend Y WHERE X is Person, X name 'foo'
-
-
-(yet) Undocumented types of queries
------------------------------------
-
-**Limit / offset**
-::
-
- Any P ORDERBY N LIMIT 5 OFFSET 10 WHERE P is Person, P firstname N
-
-**Function calls**
-::
-
- Any UPPER(N) WHERE P firstname N
-
-**Exists**
-::
-
- Any X ORDERBY PN,N
- WHERE X num N, X version_of P, P name PN,
- EXISTS(X in_state S, S name IN ("dev", "ready"))
- OR EXISTS(T tags X, T name "priority")
-
-**Left outer join**
-::
-
- Any T,P,V WHERE T is Ticket, T concerns P, T done_in V?
-
-
-**Having**
-::
-
- Any X GROUPBY X WHERE X knows Y HAVING COUNT(Y) > 10
-
-**Simple union**
-::
-
- (Any X WHERE X is Person) UNION (Any X WHERE X is Company)
-
-**Complex union**
-::
-
- DISTINCT Any W, REF
- WITH W, REF BEING
- (
- (Any W, REF WHERE W is Workcase, W ref REF,
- W concerned_by D, D name "Logilab")
- UNION
- (Any W, REF WHERE W is Workcase, W ref REF, '
- W split_into WP, WP name "WP1")
- )
-
-
-Language definition
-===================
-
-Reserved keywords
------------------
-The keywords are not case sensitive.
-
-::
-
- DISTINCT, INSERT, SET, DELETE,
- WHERE, AND, OR, NOT, EXISTS,
- IN, LIKE, UNION, WITH, BEING,
- TRUE, FALSE, NULL, TODAY, NOW,
- LIMIT, OFFSET,
- HAVING, GROUPBY, ORDERBY, ASC, DESC
-
-
-Variables and Typing
---------------------
-
-With RQL, we do not distinguish between entities and attributes. The
-value of an attribute is considered an entity of a particular type (see
-below), linked to one (real) entity by a relation called the name of
-the attribute.
-
-Entities and values to browse and/or select are represented in
-the query by *variables* that must be written in capital letters.
-
-There is a special type **Any**, referring to a non specific type.
-
-We can restrict the possible types for a variable using the
-special relation **is**.
-The possible type(s) for each variable is derived from the schema
-according to the constraints expressed above and thanks to the relations between
-each variable.
-
-Built-in types
-``````````````
-
-The base types supported are string (between double or single quotes),
-integers or floats (the separator is '.'), dates and
-boolean. We expect to receive a schema in which types String,
-Int, Float, Date and Boolean are defined.
-
-* `String` (literal: between double or single quotes).
-* `Int`, `Float` (separator being'.').
-* `Date`, `Datetime`, `Time` (literal: string YYYY/MM/DD [hh:mm] or keywords
- `TODAY` and `NOW`).
-* `Boolean` (keywords `TRUE` and `FALSE`).
-* `Keyword` NULL.
-
-
-Operators
----------
-
-Logical Operators
-`````````````````
-::
-
- AND, OR, NOT, ','
-
-',' is equivalent to 'AND' but with the smallest among the priority
-of logical operators (see :ref:`PriorityOperators`).
-
-Mathematical Operators
-``````````````````````
-::
-
- +, -, *, /
-
-Comparison operators
-````````````````````
-::
-
- =, <, <=, >=, >, ~=, IN, LIKE
-
-* The operator `=` is the default operator.
-
-* The operator `LIKE` equivalent to `~=` can be used with the
- special character `%` in a string to indicate that the chain
- must start or finish by a prefix/suffix:
- ::
-
- Any X WHERE X name ~= 'Th%'
- Any X WHERE X name LIKE '%lt'
-
-* The operator `IN` provides a list of possible values:
- ::
-
- Any X WHERE X name IN ( 'chauvat', 'fayolle', 'di mascio', 'thenault')
-
-
-XXX nico: "A trick <> 'bar'" wouldn't it be more convenient than
-"NOT A trick 'bar'" ?
-
-.. _PriorityOperators:
-
-Operator priority
-`````````````````
-
-1. '*', '/'
-
-2. '+', '-'
-
-3. 'not'
-
-4 'and'
-
-5 'or'
-
-6 ','
-
-
-Advanced Features
------------------
-
-Aggregate Functions
-```````````````````
-::
-
- COUNT, MIN, MAX, AVG, SUM
-
-Functions on string
-```````````````````
-::
-
- UPPER, LOWER
-
-Optional relations
-``````````````````
-
-* They allow you to select entities related or not to another.
-
-* You must use the `?` behind the variable to specify that the relation
- toward it is optional:
-
- - Anomalies of a project attached or not to a version ::
-
- Any X, V WHERE X concerns P, P eid 42, X corrected_in V?
-
- - All cards and the project they document if necessary ::
-
- Any C, P WHERE C is Card, P? documented_by C
-
-
-
-BNF grammar
------------
-
-The terminal elements are in capital letters, non-terminal in lowercase.
-The value of the terminal elements (between quotes) is a Python regular
-expression.
-::
-
- statement:: = (select | delete | insert | update) ';'
-
-
- # select specific rules
- select ::= 'DISTINCT'? E_TYPE selected_terms restriction? group? sort?
-
- selected_terms ::= expression ( ',' expression)*
-
- group ::= 'GROUPBY' VARIABLE ( ',' VARIABLE)*
-
- sort ::= 'ORDERBY' sort_term ( ',' sort_term)*
-
- sort_term ::= VARIABLE sort_method =?
-
- sort_method ::= 'ASC' | 'DESC'
-
-
- # delete specific rules
- delete ::= 'DELETE' (variables_declaration | relations_declaration) restriction?
-
-
- # insert specific rules
- insert ::= 'INSERT' variables_declaration ( ':' relations_declaration)? restriction?
-
-
- # update specific rules
- update ::= 'SET' relations_declaration restriction
-
-
- # common rules
- variables_declaration ::= E_TYPE VARIABLE (',' E_TYPE VARIABLE)*
-
- relations_declaration ::= simple_relation (',' simple_relation)*
-
- simple_relation ::= VARIABLE R_TYPE expression
-
- restriction ::= 'WHERE' relations
-
- relations ::= relation (LOGIC_OP relation)*
- | '(' relations')'
-
- relation ::= 'NOT'? VARIABLE R_TYPE COMP_OP? expression
- | 'NOT'? R_TYPE VARIABLE 'IN' '(' expression (',' expression)* ')'
-
- expression ::= var_or_func_or_const (MATH_OP var_or_func_or_const) *
- | '(' expression ')'
-
- var_or_func_or_const ::= VARIABLE | function | constant
-
- function ::= FUNCTION '(' expression ( ',' expression) * ')'
-
- constant ::= KEYWORD | STRING | FLOAT | INT
-
- # tokens
- LOGIC_OP ::= ',' | 'OR' | 'AND'
- MATH_OP ::= '+' | '-' | '/' | '*'
- COMP_OP ::= '>' | '>=' | '=' | '<=' | '<' | '~=' | 'LIKE'
-
- FUNCTION ::= 'MIN' | 'MAX' | 'SUM' | 'AVG' | 'COUNT' | 'UPPER' | 'LOWER'
-
- VARIABLE ::= '[A-Z][A-Z0-9]*'
- E_TYPE ::= '[A-Z]\w*'
- R_TYPE ::= '[a-z_]+'
-
- KEYWORD ::= 'TRUE' | 'FALSE' | 'NULL' | 'TODAY' | 'NOW'
- STRING ::= "'([^'\]|\\.)*'" |'"([^\"]|\\.)*\"'
- FLOAT ::= '\d+\.\d*'
- INT ::= '\d+'
-
-
-Remarks
--------
-
-Sorting and groups
-``````````````````
-
-- For grouped queries (e.g. with a GROUPBY clause), all
- selected variables should be grouped.
-
-- To group and/or sort by attributes, we can do: "X,L user U, U
- login L GROUPBY L, X ORDERBY L"
-
-- If the sorting method (SORT_METHOD) is not specified, then the sorting is
- ascendant.
-
-Negation
-````````
-
-* A query such as `Document X WHERE NOT X owned_by U` means "the
- documents have no relation `owned_by`".
-* But the query `Document X WHERE NOT X owned_by U, U login "syt"`
- means "the documents have no relation `owned_by` with the user
- syt". They may have a relation "owned_by" with another user.
-
-Identity
-````````
-
-You can use the special relation `identity` in a query to
-add an identity constraint between two variables. This is equivalent
-to ``is`` in python::
-
- Any A WHERE A comments B, A identity B
-
-return all objects that comment themselves. The relation
-`identity` is especially useful when defining the rules for securities
-with `RQLExpressions`.
-
-Implementation
-==============
-
-Internal representation (syntactic tree)
-----------------------------------------
-
-The tree research does not contain the selected variables
-(e.g. there is only what follows "WHERE").
-
-The insertion tree does not contain the variables inserted or relations
-defined on these variables (e.g. there is only what follows "WHERE").
-
-The removal tree does not contain the deleted variables and relations
-(e.g. there is only what follows the "WHERE").
-
-The update tree does not contain the variables and relations updated
-(e.g. there is only what follows the "WHERE").
-
-::
-
- Select ((Relationship | And | Or)?, Group?, Sort?)
- Insert (Relations | And | Or)?
- Delete (Relationship | And | Or)?
- Update (Relations | And | Or)?
-
- And ((Relationship | And | Or), (Relationship | And | Or))
- Or ((Relationship | And | Or), (Relationship | And | Or))
-
- Relationship ((VariableRef, Comparison))
-
- Comparison ((Function | MathExpression | Keyword | Constant | VariableRef) +)
-
- Function (())
- MathExpression ((MathExpression | Keyword | Constant | VariableRef), (MathExpression | Keyword | Constant | VariableRef))
-
- Group (VariableRef +)
- Sort (SortTerm +)
- SortTerm (VariableRef +)
-
- VariableRef ()
- Variable ()
- Keyword ()
- Constant ()
-
-
-Remarks
--------
-
-- The current implementation does not support linking two relations of type
- 'is' with a OR. I do not think that the negation is supported on this type
- of relation (XXX FIXME to be confirmed).
-
-- Relations defining the variables must be left to those using them.
- For example::
-
- Point P where P abs X, P ord Y, P value X+Y
-
- is valid, but::
-
- Point P where P abs X, P value X+Y, P ord Y
-
- is not.
-
-RQL logs
---------
-
-You can configure the `CubicWeb` application to keep a log
-of the queries executed against your database. To do so,
-edit the configuration file of your application
-``.../etc/cubicweb.d/myapp/all-in-one.conf`` and uncomment the
-variable ``query-log-file``::
-
- # web application query log file
- query-log-file=/tmp/rql-myapp.log
-
-
-Conclusion
-==========
-
-Limitations
------------
-
-It lacks at the moment:
-
-- COALESCE
-
-- restrictions on groups (HAVING)
-
-and certainly other things ...
-
-A disadvantage is that to use this language we must know the
-format used (with real relation names and entities, not those viewing
-in the user interface). On the other hand, we can not really bypass
-that, and it is the job of a user interface to hide the RQL.
-
-
-Topics
-------
-
-It would be convenient to express the schema matching
-relations (non-recursive rules)::
-
- Document class Type <-> Document occurence_of Fiche class Type
- Sheet class Type <-> Form collection Collection class Type
-
-Therefore 1. becomes::
-
- Document X where
- X class C, C name 'Cartoon'
- X owned_by U, U login 'syt'
- X available true
-
-I'm not sure that we should handle this at RQL level ...
-
-There should also be a special relation 'anonymous'.
-
-
-
-.. _Versa: http://uche.ogbuji.net/tech/rdf/versa/
-.. _SPARQL: http://www.w3.org/TR/rdf-sparql-query/
-
-
-[FIXME] see also RQL documentation in source rql/doc.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/C050-rql.en.txt Mon Apr 27 10:48:21 2009 +0200
@@ -0,0 +1,655 @@
+.. -*- coding: utf-8 -*-
+
+.. _RQL:
+
+======================================
+RQL language (Relation Query Language)
+======================================
+
+Introduction
+============
+
+Goals of RQL
+------------
+
+The goal is to have a language emphasizing the way of browsing
+relations. As such, attributes will be regarded as cases of
+special relations (in terms of implementation, the language
+user should see virtually no difference between an attribute and a
+relation).
+
+RQL is inspired by SQL but is the highest level. A knowledge of the
+`CubicWeb` schema defining the application is necessary.
+
+Comparison with existing languages
+----------------------------------
+
+SQL
+```
+RQL builds on the features of SQL but is at a higher level
+(the current implementation of RQL generates SQL). For that it is limited
+to the way of browsing relations and introduces variables.
+The user does not need to know the model underlying SQL, but the `CubicWeb`
+schema defining the application.
+
+Versa
+`````
+We should look in more detail, but here are already some ideas for
+the moment ... Versa_ is the language most similar to what we wanted
+to do, but the model underlying data being RDF, there is some
+number of things such as namespaces or handling of the RDF types which
+does not interest us. On the functionality level, Versa_ is very comprehensive
+including through many functions of conversion and basic types manipulation,
+which may need to be guided at one time or another.
+Finally, the syntax is a little esoteric.
+
+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`)
+ Extract entities and attributes of entities.
+
+Insert entities (`INSERT`)
+ Insert new entities or relations in the database.
+ It can also directly create relationships for the newly created entities.
+
+Update entities, create relations (`SET`)
+ Update existing entities in the database,
+ or create relations between existing entities.
+
+Delete entities or relationship (`DELETE`)
+ Remove entities or relations existing in the database.
+
+Search Query
+------------
+
+ [ `DISTINCT`] <entity type> V1 (V2) \ *
+ [ `GROUPBY` V1 (V2) \*] [ `ORDERBY` <orderterms>]
+ [ `WHERE` <restriction>]
+ [ `LIMIT` <value>] [ `OFFSET` <value>]
+
+:entity type:
+ Type of selected variables.
+ The special type `Any` is equivalent to not specify a type.
+:restriction:
+ list of conditions to test successively
+ `V1 relation V2 | <static value>`
+:orderterms:
+ Definition of the selection order: variable or column number followed by
+ sorting method ( `ASC`, `DESC`), ASC is the default.
+:note for grouped queries:
+ For grouped queries (e.g., a clause `GROUPBY`), all
+ selected variables must be aggregated or grouped.
+
+
+
+- *Search for the object of identifier 53*
+ ::
+
+ Any WHERE X
+ X eid 53
+
+- *Search material such as comics, owned by syt and available*
+ ::
+
+ WHERE X Document
+ X occurence_of F, F class C, C name 'Comics'
+ X owned_by U, U login 'syt'
+ X available true
+
+- *Looking for people working for eurocopter interested in training*
+ ::
+
+ Any P WHERE
+ P is Person, P work_for S, S name 'Eurocopter'
+ P interested_by T, T name 'training'
+
+- *Search note less than 10 days old written by jphc or ocy*
+ ::
+
+ Any N WHERE
+ N is Note, N written_on D, D day> (today -10),
+ N written_by P, P name 'jphc' or P name 'ocy'
+
+- *Looking for people interested in training or living in Paris*
+ ::
+
+ Any P WHERE
+ P is Person, (P interested_by T, T name 'training') OR
+ (P city 'Paris')
+
+- *The name and surname of all people*
+ ::
+
+ Any N, P WHERE
+ X is Person, X name N, X first_name P
+
+ Note that the selection of several entities generally force
+ the use of "Any" because the type specification applies otherwise
+ to all the selected variables. We could write here
+ ::
+
+ String N, P WHERE
+ X is Person, X name N, X first_name P
+
+
+ Note: You can not specify several types with * ... where X is FirstType or X is SecondType*.
+ To specify several types explicitely, you have to do
+
+ ::
+
+ Any X where X is in (FirstType, SecondType)
+
+
+Insertion query
+---------------
+
+ `INSERT` <entity type> V1 (, <entity type> V2) \ * `:` <assignments>
+ [ `WHERE` <restriction>]
+
+:assignments:
+ list of relations to assign in the form `V1 relationship V2 | <static value>`
+
+The restriction can define variables used in assignments.
+
+Caution, if a restriction is specified, the insertion is done for
+*each line result returned by the restriction*.
+
+- *Insert a new person named 'foo'*
+ ::
+
+ INSERT Person X: X name 'foo'
+
+- *Insert a new person named 'foo', another called 'nice' and a 'friend' relation
+ between them*
+ ::
+
+ INSERT Person X, Person Y: X name 'foo', Y name 'nice', X friend Y
+
+- *Insert a new person named 'foo' and a 'friend' relation with an existing
+ person called 'nice'*
+ ::
+
+ INSERT Person X: X name 'foo', X friend Y WHERE name 'nice'
+
+Update and relation creation queries
+------------------------------------
+ `SET` <assignements>
+ [ `WHERE` <restriction>]
+
+Caution, if a restriction is specified, the update is done *for
+each result line returned by the restriction*.
+
+- *Renaming of the person named 'foo' to 'bar' with the first name changed*
+ ::
+
+ SET X name 'bar', X first_name 'original' WHERE X is Person, X name 'foo'
+
+- *Insert a relation of type 'know' between objects linked by
+ the relation of type 'friend'*
+ ::
+
+ SET X know Y WHERE X friend Y
+
+
+Deletion query
+--------------
+ `DELETE` (<entity type> V) | (V1 relation v2 ),...
+ [ `WHERE` <restriction>]
+
+Caution, if a restriction is specified, the deletion is made *for
+each line result returned by the restriction*.
+
+- *Deletion of the person named 'foo'*
+ ::
+
+ DELETE Person X WHERE X name 'foo'
+
+- *Removal of all relations of type 'friend' from the person named 'foo'*
+ ::
+
+ DELETE X friend Y WHERE X is Person, X name 'foo'
+
+
+(yet) Undocumented types of queries
+-----------------------------------
+
+**Limit / offset**
+::
+
+ Any P ORDERBY N LIMIT 5 OFFSET 10 WHERE P is Person, P firstname N
+
+**Function calls**
+::
+
+ Any UPPER(N) WHERE P firstname N
+
+**Exists**
+::
+
+ Any X ORDERBY PN,N
+ WHERE X num N, X version_of P, P name PN,
+ EXISTS(X in_state S, S name IN ("dev", "ready"))
+ OR EXISTS(T tags X, T name "priority")
+
+**Left outer join**
+::
+
+ Any T,P,V WHERE T is Ticket, T concerns P, T done_in V?
+
+
+**Having**
+::
+
+ Any X GROUPBY X WHERE X knows Y HAVING COUNT(Y) > 10
+
+**Simple union**
+::
+
+ (Any X WHERE X is Person) UNION (Any X WHERE X is Company)
+
+**Complex union**
+::
+
+ DISTINCT Any W, REF
+ WITH W, REF BEING
+ (
+ (Any W, REF WHERE W is Workcase, W ref REF,
+ W concerned_by D, D name "Logilab")
+ UNION
+ (Any W, REF WHERE W is Workcase, W ref REF, '
+ W split_into WP, WP name "WP1")
+ )
+
+
+Language definition
+===================
+
+Reserved keywords
+-----------------
+The keywords are not case sensitive.
+
+::
+
+ DISTINCT, INSERT, SET, DELETE,
+ WHERE, AND, OR, NOT, EXISTS,
+ IN, LIKE, UNION, WITH, BEING,
+ TRUE, FALSE, NULL, TODAY, NOW,
+ LIMIT, OFFSET,
+ HAVING, GROUPBY, ORDERBY, ASC, DESC
+
+
+Variables and Typing
+--------------------
+
+With RQL, we do not distinguish between entities and attributes. The
+value of an attribute is considered an entity of a particular type (see
+below), linked to one (real) entity by a relation called the name of
+the attribute.
+
+Entities and values to browse and/or select are represented in
+the query by *variables* that must be written in capital letters.
+
+There is a special type **Any**, referring to a non specific type.
+
+We can restrict the possible types for a variable using the
+special relation **is**.
+The possible type(s) for each variable is derived from the schema
+according to the constraints expressed above and thanks to the relations between
+each variable.
+
+Built-in types
+``````````````
+
+The base types supported are string (between double or single quotes),
+integers or floats (the separator is '.'), dates and
+boolean. We expect to receive a schema in which types String,
+Int, Float, Date and Boolean are defined.
+
+* `String` (literal: between double or single quotes).
+* `Int`, `Float` (separator being'.').
+* `Date`, `Datetime`, `Time` (literal: string YYYY/MM/DD [hh:mm] or keywords
+ `TODAY` and `NOW`).
+* `Boolean` (keywords `TRUE` and `FALSE`).
+* `Keyword` NULL.
+
+
+Operators
+---------
+
+Logical Operators
+`````````````````
+::
+
+ AND, OR, NOT, ','
+
+',' is equivalent to 'AND' but with the smallest among the priority
+of logical operators (see :ref:`PriorityOperators`).
+
+Mathematical Operators
+``````````````````````
+::
+
+ +, -, *, /
+
+Comparison operators
+````````````````````
+::
+
+ =, <, <=, >=, >, ~=, IN, LIKE
+
+* The operator `=` is the default operator.
+
+* The operator `LIKE` equivalent to `~=` can be used with the
+ special character `%` in a string to indicate that the chain
+ must start or finish by a prefix/suffix:
+ ::
+
+ Any X WHERE X name ~= 'Th%'
+ Any X WHERE X name LIKE '%lt'
+
+* The operator `IN` provides a list of possible values:
+ ::
+
+ Any X WHERE X name IN ( 'chauvat', 'fayolle', 'di mascio', 'thenault')
+
+
+XXX nico: "A trick <> 'bar'" wouldn't it be more convenient than
+"NOT A trick 'bar'" ?
+
+.. _PriorityOperators:
+
+Operator priority
+`````````````````
+
+1. '*', '/'
+
+2. '+', '-'
+
+3. 'not'
+
+4 'and'
+
+5 'or'
+
+6 ','
+
+
+Advanced Features
+-----------------
+
+Aggregate Functions
+```````````````````
+::
+
+ COUNT, MIN, MAX, AVG, SUM
+
+Functions on string
+```````````````````
+::
+
+ UPPER, LOWER
+
+Optional relations
+``````````````````
+
+* They allow you to select entities related or not to another.
+
+* You must use the `?` behind the variable to specify that the relation
+ toward it is optional:
+
+ - Anomalies of a project attached or not to a version ::
+
+ Any X, V WHERE X concerns P, P eid 42, X corrected_in V?
+
+ - All cards and the project they document if necessary ::
+
+ Any C, P WHERE C is Card, P? documented_by C
+
+
+
+BNF grammar
+-----------
+
+The terminal elements are in capital letters, non-terminal in lowercase.
+The value of the terminal elements (between quotes) is a Python regular
+expression.
+::
+
+ statement:: = (select | delete | insert | update) ';'
+
+
+ # select specific rules
+ select ::= 'DISTINCT'? E_TYPE selected_terms restriction? group? sort?
+
+ selected_terms ::= expression ( ',' expression)*
+
+ group ::= 'GROUPBY' VARIABLE ( ',' VARIABLE)*
+
+ sort ::= 'ORDERBY' sort_term ( ',' sort_term)*
+
+ sort_term ::= VARIABLE sort_method =?
+
+ sort_method ::= 'ASC' | 'DESC'
+
+
+ # delete specific rules
+ delete ::= 'DELETE' (variables_declaration | relations_declaration) restriction?
+
+
+ # insert specific rules
+ insert ::= 'INSERT' variables_declaration ( ':' relations_declaration)? restriction?
+
+
+ # update specific rules
+ update ::= 'SET' relations_declaration restriction
+
+
+ # common rules
+ variables_declaration ::= E_TYPE VARIABLE (',' E_TYPE VARIABLE)*
+
+ relations_declaration ::= simple_relation (',' simple_relation)*
+
+ simple_relation ::= VARIABLE R_TYPE expression
+
+ restriction ::= 'WHERE' relations
+
+ relations ::= relation (LOGIC_OP relation)*
+ | '(' relations')'
+
+ relation ::= 'NOT'? VARIABLE R_TYPE COMP_OP? expression
+ | 'NOT'? R_TYPE VARIABLE 'IN' '(' expression (',' expression)* ')'
+
+ expression ::= var_or_func_or_const (MATH_OP var_or_func_or_const) *
+ | '(' expression ')'
+
+ var_or_func_or_const ::= VARIABLE | function | constant
+
+ function ::= FUNCTION '(' expression ( ',' expression) * ')'
+
+ constant ::= KEYWORD | STRING | FLOAT | INT
+
+ # tokens
+ LOGIC_OP ::= ',' | 'OR' | 'AND'
+ MATH_OP ::= '+' | '-' | '/' | '*'
+ COMP_OP ::= '>' | '>=' | '=' | '<=' | '<' | '~=' | 'LIKE'
+
+ FUNCTION ::= 'MIN' | 'MAX' | 'SUM' | 'AVG' | 'COUNT' | 'UPPER' | 'LOWER'
+
+ VARIABLE ::= '[A-Z][A-Z0-9]*'
+ E_TYPE ::= '[A-Z]\w*'
+ R_TYPE ::= '[a-z_]+'
+
+ KEYWORD ::= 'TRUE' | 'FALSE' | 'NULL' | 'TODAY' | 'NOW'
+ STRING ::= "'([^'\]|\\.)*'" |'"([^\"]|\\.)*\"'
+ FLOAT ::= '\d+\.\d*'
+ INT ::= '\d+'
+
+
+Remarks
+-------
+
+Sorting and groups
+``````````````````
+
+- For grouped queries (e.g. with a GROUPBY clause), all
+ selected variables should be grouped.
+
+- To group and/or sort by attributes, we can do: "X,L user U, U
+ login L GROUPBY L, X ORDERBY L"
+
+- If the sorting method (SORT_METHOD) is not specified, then the sorting is
+ ascendant.
+
+Negation
+````````
+
+* A query such as `Document X WHERE NOT X owned_by U` means "the
+ documents have no relation `owned_by`".
+* But the query `Document X WHERE NOT X owned_by U, U login "syt"`
+ means "the documents have no relation `owned_by` with the user
+ syt". They may have a relation "owned_by" with another user.
+
+Identity
+````````
+
+You can use the special relation `identity` in a query to
+add an identity constraint between two variables. This is equivalent
+to ``is`` in python::
+
+ Any A WHERE A comments B, A identity B
+
+return all objects that comment themselves. The relation
+`identity` is especially useful when defining the rules for securities
+with `RQLExpressions`.
+
+Implementation
+==============
+
+Internal representation (syntactic tree)
+----------------------------------------
+
+The tree research does not contain the selected variables
+(e.g. there is only what follows "WHERE").
+
+The insertion tree does not contain the variables inserted or relations
+defined on these variables (e.g. there is only what follows "WHERE").
+
+The removal tree does not contain the deleted variables and relations
+(e.g. there is only what follows the "WHERE").
+
+The update tree does not contain the variables and relations updated
+(e.g. there is only what follows the "WHERE").
+
+::
+
+ Select ((Relationship | And | Or)?, Group?, Sort?)
+ Insert (Relations | And | Or)?
+ Delete (Relationship | And | Or)?
+ Update (Relations | And | Or)?
+
+ And ((Relationship | And | Or), (Relationship | And | Or))
+ Or ((Relationship | And | Or), (Relationship | And | Or))
+
+ Relationship ((VariableRef, Comparison))
+
+ Comparison ((Function | MathExpression | Keyword | Constant | VariableRef) +)
+
+ Function (())
+ MathExpression ((MathExpression | Keyword | Constant | VariableRef), (MathExpression | Keyword | Constant | VariableRef))
+
+ Group (VariableRef +)
+ Sort (SortTerm +)
+ SortTerm (VariableRef +)
+
+ VariableRef ()
+ Variable ()
+ Keyword ()
+ Constant ()
+
+
+Remarks
+-------
+
+- The current implementation does not support linking two relations of type
+ 'is' with a OR. I do not think that the negation is supported on this type
+ of relation (XXX FIXME to be confirmed).
+
+- Relations defining the variables must be left to those using them.
+ For example::
+
+ Point P where P abs X, P ord Y, P value X+Y
+
+ is valid, but::
+
+ Point P where P abs X, P value X+Y, P ord Y
+
+ is not.
+
+RQL logs
+--------
+
+You can configure the `CubicWeb` application to keep a log
+of the queries executed against your database. To do so,
+edit the configuration file of your application
+``.../etc/cubicweb.d/myapp/all-in-one.conf`` and uncomment the
+variable ``query-log-file``::
+
+ # web application query log file
+ query-log-file=/tmp/rql-myapp.log
+
+
+Conclusion
+==========
+
+Limitations
+-----------
+
+It lacks at the moment:
+
+- COALESCE
+
+- restrictions on groups (HAVING)
+
+and certainly other things ...
+
+A disadvantage is that to use this language we must know the
+format used (with real relation names and entities, not those viewing
+in the user interface). On the other hand, we can not really bypass
+that, and it is the job of a user interface to hide the RQL.
+
+
+Topics
+------
+
+It would be convenient to express the schema matching
+relations (non-recursive rules)::
+
+ Document class Type <-> Document occurence_of Fiche class Type
+ Sheet class Type <-> Form collection Collection class Type
+
+Therefore 1. becomes::
+
+ Document X where
+ X class C, C name 'Cartoon'
+ X owned_by U, U login 'syt'
+ X available true
+
+I'm not sure that we should handle this at RQL level ...
+
+There should also be a special relation 'anonymous'.
+
+
+
+.. _Versa: http://uche.ogbuji.net/tech/rdf/versa/
+.. _SPARQL: http://www.w3.org/TR/rdf-sparql-query/
+
+
+[FIXME] see also RQL documentation in source rql/doc.
--- a/doc/book/en/D020-cookbook.txt Mon Apr 27 10:02:58 2009 +0200
+++ b/doc/book/en/D020-cookbook.txt Mon Apr 27 10:48:21 2009 +0200
@@ -9,7 +9,7 @@
* How to import LDAP users in `CubicWeb`?
- Here is a very usefull script which enables you to import LDAP users
+ Here is a very useful script which enables you to import LDAP users
into your `CubicWeb` application by running the following: ::
--- a/doc/book/en/Z010-beginners.en.txt Mon Apr 27 10:02:58 2009 +0200
+++ b/doc/book/en/Z010-beginners.en.txt Mon Apr 27 10:48:21 2009 +0200
@@ -2,11 +2,10 @@
.. _QuickInstall:
-===========================================
Quick Installation of a `CubicWeb` instance
===========================================
-.. include:: C011-installation.en.txt
+.. include:: C010-setup.en.txt
.. include:: Z012-create-instance.en.txt
--- a/doc/book/en/Z012-create-instance.en.txt Mon Apr 27 10:02:58 2009 +0200
+++ b/doc/book/en/Z012-create-instance.en.txt Mon Apr 27 10:48:21 2009 +0200
@@ -1,5 +1,6 @@
.. -*- coding: utf-8 -*-
+===============================
Creation of your first instance
===============================
--- a/web/views/startup.py Mon Apr 27 10:02:58 2009 +0200
+++ b/web/views/startup.py Mon Apr 27 10:48:21 2009 +0200
@@ -187,8 +187,9 @@
if section:
self.wview(section, None)
self.w(u'</div>')
+
-class SchemaPermissionsView(SchemaPermissionsView, SecurityViewMixIn):
+class ManagerSchemaPermissionsView(StartupView, SecurityViewMixIn):
id = 'schema_security'
require_groups = ('managers',)
__selectors__ = StartupView.__selectors__ + (match_user_group,)