[PATCH] HACKING GUIDE entry for SVN_DBG usage in the Debugging Subversion section

Hi,

I created a short SVN_DBG overview for the debugging page in the
HACKING GUIDE.

Please let me know if this can be improved.

Gabriela

[[[
Add section describing usage of the SVN_DBG macro to the Community Guide
page 'Debugging Subversion'.

* publish/docs/community-guide/debugging.part.html
   (svn_dbg): Provide overview, links, hints and sample patches.

* publish/docs/community-guide/debugging.toc.html
   (): Add link to section svn_dbg.

Suggested by: danielsh
]]]

(Just the raw text for ease of reading)
-------------------------------------------------------------------

Debugging with SVN_DBG

The SVN_DBG debugging tool is a C Preprocessor macro that sends
debugging output to stdout (by default) or stderr whilst not
interfering with the SVN test suite.

It provides an alternative to a debugger such as gdb, or
alternatively, extra information to assist in the use of a
debugger. It might be especially useful in situations where a
debugger cannot be used.

The svn_debug module contains two debug aid macros that print the
file:line of the call and printf-like arguments to the
#SVN_DBG_OUTPUT stdio stream (#stdout by default):

SVN_DBG( ( const char *fmt, ...) ) /* double braces are neccessary */

and

SVN_DBG_PROPS( ( apr_hash_t *props, const char *header_fmt, ...) )

Controlling SVN_DBG output:

* SVN_DBG is enabled whenever svn is configured with
--enable-maintainer-mode.

* The SVN test suite turns off SVN_DBG output automatically, to
     suppress the output manually, set the SVN_DBG_QUIET variable
     to 1 in your shell environment.

* When you are done, please be sure to remove any instances of
     the SVN_DBG and SVN_DBG_PROPS macros from any code you are
     committing and from any patch that you send to the
     list. (AKA: Do not forget a scalpel in the patient!)

The SVN_DBG macro definitions and code are located in:

* subversion/include/private/svn_debug.h
* subversion/libsvn_subr/debug.c

Sample patch showing usage of the SVN_DBG macro:

Index: subversion/libsvn_fs_fs/fs_fs.c
===================================================================
--- subversion/libsvn_fs_fs/fs_fs.c (revision 1476635)
+++ subversion/libsvn_fs_fs/fs_fs.c (working copy)
@@ -2303,6 +2303,9 @@ get_node_revision_body(node_revision_t **noderev_p

    /* First, try a cache lookup. If that succeeds, we are done here. */
    SVN_ERR(get_cached_node_revision_body(noderev_p, fs, id, &is_cached,
pool));
+ SVN_DBG(("Getting %s from: %s\n",
+ svn_fs_fs__id_unparse(id),
+ is_cached ? "cache" : "disk"));
    if (is_cached)
      return SVN_NO_ERROR;

Sample patch showing usage of the SVN_DBG_PROPS macro:

Index: subversion/svn/proplist-cmd.c
===================================================================
--- subversion/svn/proplist-cmd.c(revision 1475745)
+++ subversion/svn/proplist-cmd.c(working copy)
@@ -221,6 +221,7 @@ svn_cl__proplist(apr_getopt_t *os,
                                        URL, &(opt_state->start_revision),
                                        &rev, ctx, scratch_pool));
+ /* this can be called with svn proplist --revprop -r <rev> */
+ SVN_DBG_PROPS((proplist,"The variable apr_hash_t *proplist
contains: "));
        if (opt_state->xml)
          {
            svn_stringbuf_t *sb = NULL;