From ef27013bab8ce027cce1c3efe4acafb8aef9d2e3 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Fri, 19 Sep 2014 14:35:46 +0200
Subject: Add stderr_full_tracer that additionally traces statement preparation

---
 NEWS             |  7 +++++++
 doc/manual.xhtml | 13 ++++++++++---
 2 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/NEWS b/NEWS
index 7e4e8ee..0e2d50f 100644
--- a/NEWS
+++ b/NEWS
@@ -9,6 +9,13 @@ Version 2.4.0
    Section 15.2, "Persistent Class Template Instantiations" in the ODB
    manual.
 
+ * Besides odb::stderr_tracer there is now odb::stderr_full_tracer that
+   traces statement preparations and deallocations in addition to their
+   executions. This new implementation can be useful when you want to
+   see text of a statement that contains a syntax error and therefore
+   will not actually be executed. For more information, refer to Section
+   3.13, "Tracing SQL Statement Execution" in the ODB manual.
+
  * User-supplied prologues and epilogues are now generated outside the
    pre.hxx/post.hxx includes. This allows the use of precompiled headers
    with the generated files.
diff --git a/doc/manual.xhtml b/doc/manual.xhtml
index 6a12f57..13203f0 100644
--- a/doc/manual.xhtml
+++ b/doc/manual.xhtml
@@ -4139,9 +4139,16 @@ t.commit ();
 
   <p>The <code>odb::tracer</code> class defines a callback interface
      that can be used to create custom tracer implementations. The
-     <code>odb::stderr_tracer</code> is a built-in tracer implementation
-     provided by the ODB runtime. It prints each executed SQL statement
-     to the standard error stream.</p>
+     <code>odb::stderr_tracer</code> and <code>odb::stderr_full_tracer</code>
+     are built-in tracer implementations provided by the ODB runtime.
+     They both print SQL statements being executed to the standard error
+     stream. The full tracer, in addition to tracing statement executions,
+     also traces their preparations and deallocations. One situation where
+     the full tracer can be particularly useful is if a statement (for
+     example a custom query) contains a syntax error. In this case the
+     error will be detected during preparation and, as a result, the
+     statement will never be executed. The only way to see such a statement
+     is by using the full tracing.</p>
 
   <p>The <code>odb::tracer</code> class is defined in the
      <code>&lt;odb/tracer.hxx></code> header file which you will need to
-- 
cgit v1.1