From c405dadc1b0aa7ec012743d83803bb50ff0a683e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?G=C3=A9ry=20Debongnie?= <ged@odoo.com>
Date: Thu, 25 Apr 2019 17:24:39 +0200
Subject: [PATCH] [DOC] doc: improve qweb documentation

---
 doc/component.md |  3 +++
 doc/qweb.md      | 51 ++++++++++++++++++++++++++----------------------
 2 files changed, 31 insertions(+), 23 deletions(-)

diff --git a/doc/component.md b/doc/component.md
index 899c458e..6dc63d43 100644
--- a/doc/component.md
+++ b/doc/component.md
@@ -82,6 +82,9 @@ widgets:
 In this example, the template create a widget MyWidget just after the span. See
 the [QWeb](qweb.md) documentation for more information on the `t-widget` directive.
 
+Note that the rendering context for the template is the widget itself.  This means
+that the template can access `state`, `props`, `env`, or any methods defined in the widget.
+
 ## Reference
 
 An Owl component is a small class which represent a widget or some UI element.
diff --git a/doc/qweb.md b/doc/qweb.md
index 1cb5153b..0646589f 100644
--- a/doc/qweb.md
+++ b/doc/qweb.md
@@ -1,35 +1,40 @@
 # 🦉 QWeb 🦉
 
-QWeb is a template specification. The QWeb class in this repository is:
+## Content
+
+- [Overview](#overview)
+- [Base Specification](#qweb-specification)
+- [OWL Specific Extensions](#owl-specific-extensions)
+
+
+## Overview
+
+[QWeb](https://www.odoo.com/documentation/12.0/reference/qweb.html) is the primary templating engine used by Odoo. It is based on the XML format, and used
+mostly to generate html.
+
+Template directives are specified as XML attributes prefixed with `t-`, for instance `t-if` for conditionals, with elements and other attributes being rendered directly.
+
+To avoid element rendering, a placeholder element `<t>` is also available, which executes its directive but doesn’t generate any output in and of itself.
+
+The QWeb implementation in the OWL project is slightly different.  It compiles
+templates into functions that output a virtual DOM instead of a string. This is
+necessary for the component system.  In addition, it has a few extra directives
+(see [OWL Specific Extensions](#owlspecificextensions))
+
+**Note on white spaces:** white spaces in a templates are handled in a special way:
+
+- consecutive whitespaces are always condensed to a single whitespace
+- if a whitespace-only text node contains a linebreak, it is ignored
+- the previous rules do not apply if we are in a `<pre>` tag
 
-- an implementation of the QWeb specification
-- which outputs a virtual dom instead of a string
-- and extended with a few extra directives
 
 ## QWeb Specification
 
-add here a full description of what QWeb is supposed to be, with some examples
+Todo
 
-## QWeb Implementation
-
-```javascript
-var qweb = new QWeb();
-qweb.addTemplate("sometemplate", '<div>hello <t t-esc="name"/></div>');
-
-// result is a vnode which represent <div>hello world</div>
-result = qweb.render("sometemplate", { name: "world" });
-```
-
-## QWeb extensions
+## OWL Specific Extensions
 
 - t-on directive
 - t-widget, t-props, t-key
 - t-ref
 
-## Note on white spaces
-
-White spaces in a templates are handled in a special way:
-
-- consecutive whitespaces are always condensed to a single whitespace
-- if a whitespace-only text node contains a linebreak, it is ignored
-- the previous rules do not apply if we are in a `<pre>` tag