--- a/doc/book/annexes/rql/index.rst	Tue Dec 03 17:44:28 2019 +0100
+++ b/doc/book/annexes/rql/index.rst	Fri Dec 06 13:21:18 2019 +0100
@@ -11,4 +11,5 @@
    intro
    language
    debugging
+   usecases
    implementation

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/annexes/rql/usecases.rst	Fri Dec 06 13:21:18 2019 +0100
@@ -0,0 +1,78 @@
+.. _rql_usecases:
+
+RQL usecases
+------------
+
+Search bar
+~~~~~~~~~~
+
+The search bar is available on a CubicWeb instance to use RQL and it's use and
+configuration is described in `:doc:_searchbar`
+
+Use of RQL in Card documents - ReST
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+With a CubicWeb instance supporting object types with ReST content (for example
+`Card <https://www.cubicweb.org/project/cubicweb-card>`_), one can build content
+based on RQL queries as dynamic documents.
+
+For this, use the `rql` and `rql-table` ReST directive, for more information
+about custom ReST directives `head over to the sphinx documentation
+<https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html>`_
+which uses them extensivelly.
+
+rql directive
+~~~~~~~~~~~~~
+
+The `rql` directive takes as input an RQL expression and a view to apply to the
+result.
+
+For example, create a Card content by opening
+http://cubicweb_example.org/add/Card and add the following content, as an
+example : a table of blog entries (10 most recent blog entries table with user
+and date information) ::
+
+   Recent blog entries
+   -------------------
+
+   :rql:`Any B,U,D ORDERBY D DESC LIMIT 10 WHERE B is BlogEntry, B title T, B creation_date D, B created_by U:table`
+
+.. image:: ../../images/example-card-with-rql-directive.png
+
+rql-table directive
+~~~~~~~~~~~~~~~~~~~
+
+`rql-table` enables more customization, enabling you to modify the column
+(`header`) contents, and the view applied for a specific column (`colvids`).
+
+For example, create a Card content by openning http://cubicweb_example.org/add/Card and add the following content ::
+
+        Blog entries with rql-table
+        -----------------------------
+
+        .. rql-table::
+           :vid: table
+           :headers: Title with link, who wrote it, at what date
+           :colvids: 1=sameetypelist
+
+           Any B,U,D ORDERBY D DESC LIMIT 10 WHERE B is BlogEntry, B title T, B creation_date D, B created_by U
+
+All fields but the RQL string are optionnal. The ``:headers:`` option can
+contain empty column names.
+
+.. image:: ../../images/example-card-with-rql-table-directive.png
+
+Use in python projects and CLI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`cwclientlib <https://pypi.org/project/cwclientlib/>` enables you to use RQL
+in your python projects using only web requests. This project also provides a
+remote command line interface (CLI) you can use to replace a server side
+`cubicweb-ctl shell`.
+
+Use in JavaScript/React components
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`cwclientelements <https://forge.extranet.logilab.fr/open-source/cwclientelements>`
+is a library of reusable React components for building web application with
+cubicweb and RQL.

Binary file doc/images/example-card-with-rql-directive.png has changed

Binary file doc/images/example-card-with-rql-table-directive.png has changed