[gtk-doc] common: add a conditinal tracing system

[Stefan Kost <stefkost src gnome org>]

commit 615851b41bf3e7fd7724b05df7b278148525952e
Author: Stefan Kost <ensonic users sf net>
Date:   Tue Mar 29 12:35:16 2011 +0300

    common: add a conditinal tracing system
    
    We can now sprinkle the code with @TRACE@("info");. The tracing is by default
    disabled. It can be enabled by passing --enable-debug to configure and setting
    GTKDOC_TRACE=1 in the environment at run-time.

 TODO                |   10 +---------
 configure.ac        |    8 ++++++--
 gtkdoc-common.pl.in |   11 +++++++++++
 3 files changed, 18 insertions(+), 11 deletions(-)
---
diff --git a/TODO b/TODO
index 2888b50..337b358 100644
--- a/TODO
+++ b/TODO
@@ -17,14 +17,6 @@ and join discussion about future features.
 Developers can also add items here :)
 
 = Cleanups =
-== Tracing ==
-* there is a bunch of #print statements for tracing
-  => add a sub Trace() to gtkdoc-common.pl
-  => use @TRACE@ "..." and depending on configure flag
-     turn that into
-       [print __FILE__ . ":" . __LINE__ . ":" . ] or [#]
-     should be a function and the function should support loglevels and an
-       envar to enable/disable conditionally;
 == Files ==
 * can we deprecate title in the sectionfile and request people to have this in
   the SECTION comment?
@@ -148,7 +140,7 @@ more warnings:
   * we might need yet another makefile flavour to use gir files
 * perl and xml
   * http://www.xml.com/pub/a/2001/04/18/perlxmlqstart1.html
- 
+
 == binding docs ==
 * simmillar workflow to gettext
 * add gtkdoc-mk??? to generate binding doc templates
diff --git a/configure.ac b/configure.ac
index 3c652d9..30fe622 100644
--- a/configure.ac
+++ b/configure.ac
@@ -203,8 +203,8 @@ AC_ARG_ENABLE([debug],
 	[enable_debug="no"])
 AC_MSG_RESULT($enable_debug)
 
-if test "$enable_debug" = "yes"; then
-	TRACE="print __FILE__ . \":\" . __LINE__ . \":\" ."
+if test "x$enable_debug" != "xno"; then
+	TRACE="LogTrace"
 else
 	TRACE="#"
 fi
@@ -281,3 +281,7 @@ test -n "$HIGHLIGHT" \
 test "x$build_tests" != "xno" \
     && AC_MSG_NOTICE([** Building regression tests]) \
     || AC_MSG_NOTICE([   Skipping regression tests])
+test "x$enable_debug" != "xno" \
+    && AC_MSG_NOTICE([** Debug tracing enabled]) \
+    || AC_MSG_NOTICE([   Debug tracing disabled])
+
diff --git a/gtkdoc-common.pl.in b/gtkdoc-common.pl.in
index 4e5670d..41385bb 100644
--- a/gtkdoc-common.pl.in
+++ b/gtkdoc-common.pl.in
@@ -483,6 +483,17 @@ sub LogWarning {
     print "$file:$line: warning: $message\n"
 }
 
+sub LogTrace {
+    my ($message) = @_;
+
+    if (defined($ENV{"GTKDOC_TRACE"})) {
+        my (undef, $file, $line) = caller;
+
+        chomp($message);
+        print "$file:$line: trace: $message\n"
+    }
+}
+
 
 #############################################################################
 # Function    : CreateValidSGMLID