(How guile-snarf works): Updated.

(Writing your own snarfing macros): New.

doc/ref/tools.texi

@@ -60,8 +60,9 @@ generate a file of calls to @code{scm_c_define_gsubr} which you can
 @code{#include} into an initialization function.
 
 @menu
-* How guile-snarf works::          Using @code{guile-snarf}, with example.
+* How guile-snarf works::           Using @code{guile-snarf}, with example.
-* Macros guile-snarf recognizes::  How to mark up code for @code{guile-snarf}.
+* Macros guile-snarf recognizes::   How to mark up code for @code{guile-snarf}.
+* Writing your own snarfing macros:: How to define new things to snarf.
 @end menu
 
 @c ---------------------------------------------------------------------------
@@ -70,28 +71,29 @@ generate a file of calls to @code{scm_c_define_gsubr} which you can
 @cindex guile-snarf invocation
 @cindex guile-snarf example
 
-Usage: guile-snarf [-o OUTFILE] INFILE [CPP-OPTIONS ...]
+Usage: guile-snarf [-o @var{outfile}] [@var{cpp-args} ...]
 
-What @code{guile-snarf} does:
+The @code{guile-snarf} program will extract initialization actions to
+@var{outfile} or to standard output when no @var{outfile} has been
+specified or when @var{outfile} is @code{-}.  The C preprocessor is
+called with @var{cpp-args} (which usually include an input file) and
+the output is filtered to extract the initialization actions.
 
-Process INFILE using the C pre-processor and some other programs.
+If there are errors during processing, @var{outfile} is deleted and the
-Write output to a file named OUTFILE or to the standard output when no
+program exits with non-zero status.
-OUTFILE has been specified or when OUTFILE is @code{-}.
-
-If there are errors during processing, delete OUTFILE and exit with
-non-zero status.
-
-If env var CPP is set, use its value instead of the C pre-processor
-determined at Guile configure-time.
 
 During snarfing, the pre-processor macro @code{SCM_MAGIC_SNARFER} is
-defined.  You can use this to avoid including snarfer output files
+defined.  You could use this to avoid including snarfer output files
 that don't yet exist by writing code like this:
-@example
+
-#ifndef SCM_MAGIC_SNARFER 
+@smallexample
-#include "foo.x" 
+#ifndef SCM_MAGIC_SNARFER
+#include "foo.x"
 #endif
-@end example
+@end smallexample
+
+If the environment variable @code{CPP} is set, use its value instead of the
+C pre-processor determined at Guile configure-time.
 
 @xref{Macros guile-snarf recognizes}, for a list of the special (some would
 say magic) cpp macros you can use, including the list of deprecated macros.
@@ -108,7 +110,7 @@ SCM_DEFINE (clear_image, "clear-image", 1, 0, 0,
             "Clear the image.")
 #define FUNC_NAME s_clear_image
 @{
-  /* C code to clear the image... */
+  /* C code to clear the image in @code{image_smob}... */
 @}
 #undef FUNC_NAME
 
@@ -122,8 +124,8 @@ init_image_type ()
 
 The @code{SCM_DEFINE} declaration says that the C function
 @code{clear_image} implements a Scheme subr called @code{clear-image},
-which takes one required argument (type @code{SCM} named
+which takes one required argument (of type @code{SCM} and named
-@code{image_smob}), no optional arguments, and no tail argument.
+@code{image_smob}), no optional arguments, and no rest argument.
 @xref{Doc Snarfing}, for info on the docstring.
 
 This works in concert with @code{FUNC_NAME} to also define a static
@@ -146,8 +148,9 @@ declarations, and writes to @file{image-type.x} the output:
 scm_c_define_gsubr (s_clear_image, 1, 0, 0, (SCM (*)() ) clear_image);
 @end example
 
-When compiled normally, @code{SCM_DEFINE} is a macro which expands to a
+When compiled normally, @code{SCM_DEFINE} is a macro which expands to
-declaration of the @code{s_clear_image} string.
+a declaration of the @code{s_clear_image} string and the function
+header for @code{clear_image}.
 
 Note that the output file name matches the @code{#include} from the
 input file.  Also, you still need to provide all the same information
@@ -168,11 +171,11 @@ snarfcppopts = $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS)
 This tells make to run @code{guile-snarf} to produce each needed
 @file{.x} file from the corresponding @file{.c} file.
 
-Aside from the required argument INFILE, @code{guile-snarf} passes its
+The program @code{guile-snarf} passes its command-line arguments
-command-line arguments directly to the C preprocessor, which it uses to
+directly to the C preprocessor, which it uses to extract the
-extract the information it needs from the source code. this means you can pass
+information it needs from the source code. this means you can pass
-normal compilation flags to @code{guile-snarf} to define preprocessor symbols,
+normal compilation flags to @code{guile-snarf} to define preprocessor
-add header file directories, and so on.
+symbols, add header file directories, and so on.
 
 @c ---------------------------------------------------------------------------
 @node Macros guile-snarf recognizes
@@ -221,40 +224,46 @@ ARGLIST is an argument list (in parentheses); and lastly, @var{init_val}
 is a expression suitable for initializing a new variable.
 
 For procedures, you can use @code{SCM_DEFINE} for most purposes.  Use
-@code{SCM_PROC} along with @code{SCM_REGISTER_PROC} when you don't want
+@code{SCM_PROC} along with @code{SCM_REGISTER_PROC} when you don't
-to be bothered with docstrings.  Use @code{SCM_GPROC} for generic
+want to be bothered with docstrings.  Use @code{SCM_GPROC} for generic
-functions (@pxref{GOOPS,,,goops}).  All procedures are declared
+functions (@pxref{GOOPS,,,goops}).  All procedures are declared with
-@code{static} with return type @code{SCM}.
+return type @code{SCM}.
 
 For everything else, use the appropriate macro (@code{SCM_SYMBOL} for
-symbols, and so on).  The "_GLOBAL_" variants omit @code{static}
+symbols, and so on).  Without "_GLOBAL_", the declarations are
-declaration.
+@code{static}.
 
 All these macros should be used at top-level, outside function bodies.
 Also, it's a good idea to define @var{FUNC_NAME} immediately after using
 @code{SCM_DEFINE} (and similar), and then the function body, and then
 @code{#undef FUNC_NAME}.
 
-@c Here is the list of deprecated macros:
-
-@c @c reminder: sync w/ libguile/guile-snarf.in var `deprecated_list'
-@c @example
-@c  SCM_CONST_LONG
-@c  SCM_VCELL
-@c  SCM_VCELL_INIT
-@c  SCM_GLOBAL_VCELL
-@c  SCM_GLOBAL_VCELL_INIT
-@c @end example
-
-@c Some versions of guile (and guile-snarf) will continue to recognize them but
-@c at some point they will no longer work.  You can pass either @code{-d} or
-@c @code{-D} option to have guile-snarf warn or signal error, respectively, if
-@c any of these are found in the input file.
-
 @xref{How guile-snarf works}, and also libguile source, for examples.
 @xref{Subrs}, for details on argument passing and how to write C
 functions.
 
+@c ---------------------------------------------------------------------------
+@node Writing your own snarfing macros
+@subsubsection Writing your own snarfing macros
+
+When you want to use the general snarfing machanism, but none of the
+provided macros fits your need, you can use the macro
+@code{SCM_SNARF_INIT}.
+
+For example, the @code{SCM_SYMBOL} macro can be defined like this:
+
+@example
+#define SCM_SYMBOL(c_name, scheme_name) \
+static SCM c_name \
+SCM_SNARF_INIT(c_name = scm_permanent_object (scm_str2symbol (scheme_name)))
+@end example
+
+@defmac SCM_SNARF_INIT (code)
+When processed normally, @code{SCM_SNARF_INIT} expands to nothing;
+when processed by the snarfer, it causes @var{code} to be included in
+the initialization action file, followed by a semicolon.
+@end defmac
+
 @c ---------------------------------------------------------------------------
 @node Doc Snarfing
 @subsection Doc Snarfing