[doc] fix FAQ layout
authorNicolas Chauvat <nicolas.chauvat@logilab.fr>
Wed, 29 Jul 2009 00:12:43 +0200
changeset 2547 f32af375339d
parent 2546 df456fa1b053
child 2548 6e9d58e04ef9
[doc] fix FAQ layout
doc/book/en/annexes/faq.rst
--- a/doc/book/en/annexes/faq.rst	Tue Jul 28 23:55:56 2009 +0200
+++ b/doc/book/en/annexes/faq.rst	Wed Jul 29 00:12:43 2009 +0200
@@ -14,79 +14,79 @@
 Why does not CubicWeb have a template language ?
 ------------------------------------------------
 
-  There are enough template languages out there. You can use your
-  preferred template language if you want. [explain how to use a
-  template language]
+There are enough template languages out there. You can use your
+preferred template language if you want. [explain how to use a
+template language]
 
-  *CubicWeb* does not define its own templating language as this was
-  not our goal. Based on our experience, we realized that
-  we could gain productivity by letting designers use design tools
-  and developpers develop without the use of the templating language
-  as an intermediary that could not be anyway efficient for both parties.
-  Python is the templating language that we use in *CubicWeb*, but again,
-  it does not prevent you from using a templating language.
+*CubicWeb* does not define its own templating language as this was
+not our goal. Based on our experience, we realized that
+we could gain productivity by letting designers use design tools
+and developpers develop without the use of the templating language
+as an intermediary that could not be anyway efficient for both parties.
+Python is the templating language that we use in *CubicWeb*, but again,
+it does not prevent you from using a templating language.
 
-  The reason template languages are not used in this book is that
-  experience has proved us that using pure python was less cumbersome.
+The reason template languages are not used in this book is that
+experience has proved us that using pure python was less cumbersome.
 
 Why do you think using pure python is better than using a template language ?
 -----------------------------------------------------------------------------
 
-  Python is an Object Oriented Programming language and as such it
-  already provides a consistent and strong architecture and syntax
-  a templating language would not reach.
+Python is an Object Oriented Programming language and as such it
+already provides a consistent and strong architecture and syntax
+a templating language would not reach.
 
-  When doing development, you need a real language and template
-  languages are not real languages.
+When doing development, you need a real language and template
+languages are not real languages.
 
-  Using Python instead of a template langage for describing the user interface
-  makes it to maintain with real functions/classes/contexts without the need of
-  learning a new dialect. By using Python, we use standard OOP techniques and
-  this is a key factor in a robust application.
+Using Python instead of a template langage for describing the user interface
+makes it to maintain with real functions/classes/contexts without the need of
+learning a new dialect. By using Python, we use standard OOP techniques and
+this is a key factor in a robust application.
 
 Why do you use the LGPL license to prevent me from doing X ?
 ------------------------------------------------------------
 
-  LGPL means that *if* you redistribute your application, you need to
-  redistribute the changes you made to CubicWeb under the LGPL licence.
+LGPL means that *if* you redistribute your application, you need to
+redistribute the changes you made to CubicWeb under the LGPL licence.
 
-  Publishing a web site has nothing to do with redistributing
-  source code. A fair amount of companies use modified LGPL code
-  for internal use. And someone could publish a *CubicWeb* component
-  under a BSD licence for others to plug into a LGPL framework without
-  any problem. The only thing we are trying to prevent here is someone
-  taking the framework and packaging it as closed source to his own
-  clients.
+Publishing a web site has nothing to do with redistributing
+source code. A fair amount of companies use modified LGPL code
+for internal use. And someone could publish a *CubicWeb* component
+under a BSD licence for others to plug into a LGPL framework without
+any problem. The only thing we are trying to prevent here is someone
+taking the framework and packaging it as closed source to his own
+clients.
 
 
 CubicWeb looks pretty recent. Is it stable ?
 --------------------------------------------
 
-  It is constantly evolving, piece by piece.  The framework has evolved since
-  2001 and data has been migrated from one schema to the other ever since. There
-  is a well-defined way to handle data and schema migration.
+It is constantly evolving, piece by piece.  The framework has evolved since
+2001 and data has been migrated from one schema to the other ever since. There
+is a well-defined way to handle data and schema migration.
 
 Why is the RQL query language looking similar to X ?
 -----------------------------------------------------
 
-  It may remind you of SQL but it is higher level than SQL, more like
-  SPARQL. Except that SPARQL did not exist when we started the project.
-  Having SPARQL as a query language has been in our backlog for years.
+It may remind you of SQL but it is higher level than SQL, more like
+SPARQL. Except that SPARQL did not exist when we started the project.
+With version 3.4, CubicWeb has support for SPARQL.
 
-  That RQL language is what is going to make a difference with django-
-  like frameworks for several reasons.
+That RQL language is what is going to make a difference with django-
+like frameworks for several reasons.
 
-  1. accessing data is *much* easier with it. One can write complex
-     queries with RQL that would be tedious to define and hard to maintain
-     using an object/filter suite of method calls.
+1. accessing data is *much* easier with it. One can write complex
+   queries with RQL that would be tedious to define and hard to maintain
+   using an object/filter suite of method calls.
 
-  2. it offers an abstraction layer allowing your applications to run
-     on multiple back-ends. That means not only various SQL backends
-     (postgresql, sqlite, mysql), but also multiple databases at the
-     same time, and also non-SQL data stores like LDAP directories and
-     subversion/mercurial repositories (see the `vcsfile`
-     component). Google App Engine is yet another supported target for
-     RQL.
+2. it offers an abstraction layer allowing your applications to run
+   on multiple back-ends. That means not only various SQL backends
+   (postgresql, sqlite, mysql), but also multiple databases at the
+   same time, and also non-SQL data stores like LDAP directories and
+   subversion/mercurial repositories (see the `vcsfile`
+   component). Google App Engine is yet another supported target for
+   RQL.
 
 [copy answer from forum, explain why similar to sparql and why better
   than django and SQL]
@@ -100,7 +100,9 @@
 How is security implemented ?
 ------------------------------
 
-  This is an example of how it works in our framework::
+This is an example of how it works in our framework:
+
+.. sourcecode:: python
 
     class Version(EntityType):
         """a version is defining the content of a particular project's
@@ -110,16 +112,17 @@
                        'update': ('managers', 'logilab', 'owners',),
                        'delete': ('managers', ),
                        'add': ('managers', 'logilab',
-                           ERQLExpression('X version_of PROJ, U in_group G, '
-                                          'PROJ require_permission P, '
-                                          'P name "add_version", P require_group G'),)}
+                               ERQLExpression('X version_of PROJ, U in_group G, '
+                                              'PROJ require_permission P, '
+                                              'P name "add_version", P require_group G'),)}
 
-  The above means that permission to read a Version is granted to any
-  user that is part of one of the groups 'managers', 'users', 'guests'.
-  The 'add' permission is granted to users in group 'managers' or
-  'logilab' and to users in group G, if G is linked by a permission
-  entity named "add_version" to the version's project.
-  ::
+The above means that permission to read a Version is granted to any
+user that is part of one of the groups 'managers', 'users', 'guests'.
+The 'add' permission is granted to users in group 'managers' or
+'logilab' and to users in group G, if G is linked by a permission
+entity named "add_version" to the version's project.
+
+.. sourcecode:: python
 
     class version_of(RelationType):
         """link a version to its project. A version is necessarily linked
@@ -128,20 +131,20 @@
         permissions = {'read': ('managers', 'users', 'guests',),
                        'delete': ('managers', ),
                        'add': ('managers', 'logilab',
-                            RRQLExpression('O require_permission P, P name "add_version",
-                            'U in_group G, P require_group G'),) }
+                               RRQLExpression('O require_permission P, P name "add_version", '
+                               'U in_group G, P require_group G'),) }
 
-  You can find additional information in the section :ref:`security`.
+You can find additional information in the section :ref:`security`.
 
-  [XXX what does the second example means in addition to the first one?]
+[XXX what does the second example means in addition to the first one?]
 
 
 What is `Error while publishing rest text ...` ?
 ------------------------------------------------
 
-  While modifying the description of an entity, you get an error message in
-  the instance `Error while publishing ...` for Rest text and plain text.
-  The server returns a traceback like as follows ::
+While modifying the description of an entity, you get an error message in
+the instance `Error while publishing ...` for Rest text and plain text.
+The server returns a traceback like as follows ::
 
       2008-10-06 15:05:08 - (cubicweb.rest) ERROR: error while publishing ReST text
       Traceback (most recent call last):
@@ -150,70 +153,69 @@
       file = __builtin__.open(filename, mode, buffering)
       TypeError: __init__() takes at most 3 arguments (4 given)
 
-
-  This can be fixed by applying the patch described in :
-  http://code.google.com/p/googleappengine/issues/detail?id=48
+This can be fixed by applying the patch described in :
+http://code.google.com/p/googleappengine/issues/detail?id=48
 
 What are hooks used for ?
 -------------------------
 
-  Hooks are executed around (actually before or after) events.  The
-  most common events are data creation, update and deletion.  They
-  permit additional constraint checking (those not expressible at the
-  schema level), pre and post computations depending on data
-  movements.
+Hooks are executed around (actually before or after) events.  The
+most common events are data creation, update and deletion.  They
+permit additional constraint checking (those not expressible at the
+schema level), pre and post computations depending on data
+movements.
 
-  As such, they are a vital part of the framework.
+As such, they are a vital part of the framework.
 
-  Other kinds of hooks, called Operations, are available
-  for execution just before commit.
+Other kinds of hooks, called Operations, are available
+for execution just before commit.
 
 When should you define an HTML template rather than define a graphical component ?
 ----------------------------------------------------------------------------------
 
-  An HTML template cannot contain code, hence it is only about static
-  content.  A component is made of code and operations that apply on a
-  well defined context (request, result set). It enables much more
-  dynamic views.
+An HTML template cannot contain code, hence it is only about static
+content.  A component is made of code and operations that apply on a
+well defined context (request, result set). It enables much more
+dynamic views.
 
 What is the difference between `AppRsetObject` and `AppObject` ?
 ----------------------------------------------------------------
 
-  `AppRsetObject` instances are selected on a request and a result
-  set. `AppObject` instances are directly selected by id.
+`AppRsetObject` instances are selected on a request and a result
+set. `AppObject` instances are directly selected by id.
 
 How to update a database after a schema modification ?
 ------------------------------------------------------
 
-  It depends on what has been modified in the schema.
+It depends on what has been modified in the schema.
 
-  * Update the permissions and properties of an entity or a relation:
-    ``sync_schema_props_perms('MyEntityOrRelation')``.
+* Update the permissions and properties of an entity or a relation:
+  ``sync_schema_props_perms('MyEntityOrRelation')``.
 
-  * Add an attribute: ``add_attribute('MyEntityType', 'myattr')``.
+* Add an attribute: ``add_attribute('MyEntityType', 'myattr')``.
 
-  * Add a relation: ``add_relation_definition('SubjRelation', 'MyRelation', 'ObjRelation')``.
+* Add a relation: ``add_relation_definition('SubjRelation', 'MyRelation', 'ObjRelation')``.
 
 
 How to create an anonymous user ?
 ---------------------------------
 
-  This allows to bypass authentication for your site. In the
-  ``all-in-one.conf`` file of your instance, define the anonymous user
-  as follows ::
+This allows to bypass authentication for your site. In the
+``all-in-one.conf`` file of your instance, define the anonymous user
+as follows ::
 
-    # login of the CubicWeb user account to use for anonymous user (if you want to
-    # allow anonymous)
-    anonymous-user=anon
+  # login of the CubicWeb user account to use for anonymous user (if you want to
+  # allow anonymous)
+  anonymous-user=anon
 
-    # password of the CubicWeb user account matching login
-    anonymous-password=anon
+  # password of the CubicWeb user account matching login
+  anonymous-password=anon
 
-  You also must ensure that this `anon` user is a registered user of
-  the DB backend. If not, you can create through the administation
-  interface of your instance by adding a user with the role `guests`.
-  This could be the admin account (for development
-  purposes, of course).
+You also must ensure that this `anon` user is a registered user of
+the DB backend. If not, you can create through the administation
+interface of your instance by adding a user with the role `guests`.
+This could be the admin account (for development
+purposes, of course).
 
 .. note::
     While creating a new instance, you can decide to allow access
@@ -224,55 +226,57 @@
 How to change the instance logo ?
 ------------------------------------
 
-  There are two ways of changing the logo.
+There are two ways of changing the logo.
 
-  1. 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 instance will look for a ``logo.png`` to be
-     rendered in the logo section.
+1. 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 instance will look for a ``logo.png`` to be
+   rendered in the logo section.
 
-     .. image:: ../images/lax-book.06-main-template-logo.en.png
+   .. image:: ../images/lax-book.06-main-template-logo.en.png
 
-  2. In your cube directory, you can specify which file to use for the logo.
-     This is configurable in ``mycube/data/external_resources``: ::
+2. In your cube directory, you can specify which file to use for the logo.
+   This is configurable in ``mycube/data/external_resources``: ::
 
-       LOGO = DATADIR/path/to/mylogo.gif
+     LOGO = DATADIR/path/to/mylogo.gif
 
-     where DATADIR is ``mycube/data``.
+   where DATADIR is ``mycube/data``.
 
 
 How to configure a LDAP source ?
 --------------------------------
 
-  Your instance's sources are defined in ``/etc/cubicweb.d/myapp/sources``.
-  Configuring an LDAP source is about declaring that source in your
-  instance configuration file such as: ::
+Your instance's sources are defined in ``/etc/cubicweb.d/myapp/sources``.
+Configuring an LDAP source is about declaring that source in your
+instance configuration file such as: ::
 
-    [ldapuser]
-    adapter=ldapuser
-    # ldap host
-    host=myhost
-    # base DN to lookup for usres
-    user-base-dn=ou=People,dc=mydomain,dc=fr
-    # user search scope
-    user-scope=ONELEVEL
-    # classes of user
-    user-classes=top,posixAccount
-    # attribute used as login on authentication
-    user-login-attr=uid
-    # name of a group in which ldap users will be by default
-    user-default-group=users
-    # map from ldap user attributes to cubicweb attributes
-    user-attrs-map=gecos:email,uid:login
+  [ldapuser]
+  adapter=ldapuser
+  # ldap host
+  host=myhost
+  # base DN to lookup for usres
+  user-base-dn=ou=People,dc=mydomain,dc=fr
+  # user search scope
+  user-scope=ONELEVEL
+  # classes of user
+  user-classes=top,posixAccount
+  # attribute used as login on authentication
+  user-login-attr=uid
+  # name of a group in which ldap users will be by default
+  user-default-group=users
+  # map from ldap user attributes to cubicweb attributes
+  user-attrs-map=gecos:email,uid:login
 
-  Any change applied to configuration file requires to restart your
-  instance.
+Any change applied to configuration file requires to restart your
+instance.
 
 I get NoSelectableObject exceptions, how do I debug selectors ?
 ---------------------------------------------------------------
 
-  You just need to put the appropriate context manager around view/component
-  selection (one standard place in in vreg.py) : ::
+You just need to put the appropriate context manager around view/component
+selection (one standard place in in vreg.py):
+
+.. sourcecode:: python
 
     def possible_objects(self, registry, *args, **kwargs):
         """return an iterator on possible objects in a registry for this result set
@@ -287,40 +291,43 @@
                 except NoSelectableObject:
                     continue
 
-  Don't forget the 'from __future__ improt with_statement' at the
-  module top-level.
+Don't forget the 'from __future__ import with_statement' at the module
+top-level.
 
-  This will yield additional WARNINGs, like this:
-  ::
+This will yield additional WARNINGs, like this::
 
     2009-01-09 16:43:52 - (cubicweb.selectors) WARNING: selector one_line_rset returned 0 for <class 'cubicweb.web.views.basecomponents.WFHistoryVComponent'>
 
 How to format an entity date attribute ?
 ----------------------------------------
 
-  If your schema has an attribute of type Date or Datetime, you might
-  want to format it. First, you should define your preferred format using
-  the site configuration panel ``http://appurl/view?vid=systempropertiesform``
-  and then set ``ui.date`` and/or ``ui.datetime``.
-  Then in the view code, use::
+If your schema has an attribute of type Date or Datetime, you might
+want to format it. First, you should define your preferred format using
+the site configuration panel ``http://appurl/view?vid=systempropertiesform``
+and then set ``ui.date`` and/or ``ui.datetime``.
+Then in the view code, use:
+
+.. sourcecode:: python
 
     self.format_date(entity.date_attribute)
 
 Can PostgreSQL and CubicWeb authentication work with kerberos ?
 ----------------------------------------------------------------
 
-  If you have PostgreSQL set up to accept kerberos authentication, you can set
-  the db-host, db-name and db-user parameters in the `sources` configuration
-  file while leaving the password blank. It should be enough for your
-  instance to connect to postgresql with a kerberos ticket.
+If you have PostgreSQL set up to accept kerberos authentication, you can set
+the db-host, db-name and db-user parameters in the `sources` configuration
+file while leaving the password blank. It should be enough for your
+instance to connect to postgresql with a kerberos ticket.
 
 
 How to load data from a script ?
 --------------------------------
 
-  The following script aims at loading data within a script assuming pyro-nsd is
-  running and your instance is configured with ``pyro-server=yes``, otherwise
-  you would not be able to use dbapi. ::
+The following script aims at loading data within a script assuming pyro-nsd is
+running and your instance is configured with ``pyro-server=yes``, otherwise
+you would not be able to use dbapi.
+
+.. sourcecode:: python
 
     from cubicweb import dbapi
 
@@ -333,24 +340,30 @@
 What is the CubicWeb datatype corresponding to GAE datastore's UserProperty ?
 -----------------------------------------------------------------------------
 
-  If you take a look at your instance schema and
-  click on "display detailed view of metadata" you will see that there
-  is a Euser entity in there. That's the one that is modeling users. The
-  thing that corresponds to a UserProperty is a relationship between
-  your entity and the Euser entity. As in ::
+If you take a look at your instance schema and
+click on "display detailed view of metadata" you will see that there
+is a Euser entity in there. That's the one that is modeling users. The
+thing that corresponds to a UserProperty is a relationship between
+your entity and the Euser entity. As in:
+
+.. sourcecode:: python
 
     class TodoItem(EntityType):
        text = String()
        todo_by = SubjectRelation('Euser')
 
-  [XXX check that cw handle users better by
-  mapping Google Accounts to local Euser entities automatically]
+[XXX check that cw handle users better by mapping Google Accounts to local Euser
+entities automatically]
 
 
 How to reset the password for user joe ?
 ----------------------------------------
 
-  You need to generate a new encrypted password::
+If you want to reset the admin password for ``myinstance``, do::
+
+    $ cubicweb-ctl reset-admin-pwd myinstance
+
+You need to generate a new encrypted password::
 
     $ python
     >>> from cubicweb.server.utils import crypt_password
@@ -358,7 +371,7 @@
     'qHO8282QN5Utg'
     >>>
 
-  and paste it in the database::
+and paste it in the database::
 
     $ psql mydb
     mydb=> update cw_cwuser set cw_upassword='qHO8282QN5Utg' where cw_login='joe';
@@ -369,6 +382,6 @@
 
 You are probably getting errors such as ::
 
-  remove {'PR': 'Project', 'C': 'CWUser'} from solutions since your_user has no read access to cost  
+  remove {'PR': 'Project', 'C': 'CWUser'} from solutions since your_user has no read access to cost
 
-This is because you have to put your user in the "users" group. The user has to be in both groups.  
+This is because you have to put your user in the "users" group. The user has to be in both groups.