Re: a debugging trick: how to peek into m4's processing

[Bruno Haible]

Hi Eric,

> > ------------------------------------------------------------------
> > m4_syscmd([cat 1>&2 <<\EOT
> >
> > Here comes the definition of AM_INIT_AUTOMAKE:]
> > m4_defn([AM_INIT_AUTOMAKE])
> > [EOT])
> > ------------------------------------------------------------------
> 
> Very similar to m4_file_append, except that it outputs to stderr rather
> than appending to a file.  For that matter, m4_errprint does that, without
> having to spawn a subprocess.

Glad to see that m4_file_append and m4_errprintn already exist. I did not
know about them.

> Hmm, --trace shows arguments, not definition, but it also has a place.

Yes, I agree documenting --trace by example is good as well.

> +$ @kbd{cat <<\EOF > foo.m4}
> +m4_init
> +m4_errprintn([try one: m4_dquote is ]m4_defn([m4_dquote]))
> +m4_divert([0])dnl
> +m4_errprintn([try two: m4_dquote is ]m4_defn([m4_dquote]))dnl
> +m4_dquote([hi])
> +EOF
> +$ @kbd{autom4te --language=m4sugar foo.m4}
> +try one: m4_dquote is [$@@]
> +try two: m4_dquote is [$@@]
> +$ @kbd{cat foo}
> +[hi]

In this second example, the file 'foo' is never being created, since autom4te
is not being passed the options "-o foo".

More importantly, your example shows m4_errprintn only in the context of
"autom4te --language=m4sugar". But it's more powerful than that: it also
works from inside an 'autoconf' run (with is more often what the user wants
to debug).

Here is a proposed patch to
  - show m4_errprintn in the context of autoconf,
  - separate the two techniques (m4_errprintn and diversions) into separate
    examples,
  - Tweak the output so that it fits in 79 columns (in 'info' output).


2009-07-25  Bruno Haible  <address@hidden>

        Clarify autom4te debugging tips.
        * doc/autoconf.texi (Debugging via autom4te): Clarify that the two
        techniques are independent.

*** doc/autoconf.texi.orig      2009-07-25 16:39:05.000000000 +0200
--- doc/autoconf.texi   2009-07-25 16:36:28.000000000 +0200
***************
*** 12454,12463 ****
  version is 2.63b.95-3963
  @end example
  
! Another trick is using @code{m4_errprintn} to output debugging messages
! to standard error with no further m4 expansion, and without interfering
! with the post-processing done to standard output.  For example, contrast
! these two attempts to learn how @code{m4_dquote} is implemented:
  
  @smallexample
  $ @kbd{cat <<\EOF > foo.m4}
--- 12454,12485 ----
  version is 2.63b.95-3963
  @end example
  
! Another trick is to print out the expansion of various m4 expressions
! to standard error or to a file, with no further m4 expansion, and without
! interfering with the post-processing done to standard output.  There are
! two ways to do this.  One is through @code{m4_errprintn}, the other one
! through diversions in @command{autom4te}.
! 
! @code{m4_errprintn} shows a given expression on standard error.  For
! example, if you want to see the expansion of an autoconf primitive or
! of one of your autoconf macros, you can do it like this:
! 
! @smallexample
! $ @kbd{cat <<\EOF > configure.ac}
! AC_INIT
! m4_errprintn([Here comes the definition of AC_DEFINE_UNQUOTED:])
! m4_errprintn(m4_defn([AC_DEFINE_UNQUOTED]))
! AC_OUTPUT
! EOF
! $ @kbd{autoconf}
! Here comes the definition of AC_DEFINE_UNQUOTED:
! _AC_DEFINE_Q([], $@@)
! @end smallexample
! 
! You can also use diversions.  For example, the following is an attempt
! to learn how @code{m4_dquote} is implemented.  Note that diversion 0
! is standard output, and standard output is being redirected to a file
! through the @samp{-o output} option.
  
  @smallexample
  $ @kbd{cat <<\EOF > foo.m4}
***************
*** 12466,12491 ****
  m4_divert([0])dnl
  try two: [m4_dquote is ]m4_defn([m4_dquote])
  m4_dquote([hi])
  EOF
! $ @kbd{autom4te --language=m4sugar -o foo foo.m4}
  foo.m4:2: error: possibly undefined macro: m4_dquote
!       If this token and others are legitimate, please use m4_pattern_allow.
!       See the Autoconf documentation.
! $ @kbd{cat foo}
! try two: m4_dquote is [$@@]
! [hi]
! $ @kbd{cat <<\EOF > foo.m4}
! m4_init
! m4_errprintn([try one: m4_dquote is ]m4_defn([m4_dquote]))
! m4_divert([0])dnl
! m4_errprintn([try two: m4_dquote is ]m4_defn([m4_dquote]))dnl
! m4_dquote([hi])
! EOF
! $ @kbd{autom4te --language=m4sugar foo.m4}
! try one: m4_dquote is [$@@]
  try two: m4_dquote is [$@@]
- $ @kbd{cat foo}
  [hi]
  @end smallexample
  
  @node Programming in M4sh
--- 12488,12503 ----
  m4_divert([0])dnl
  try two: [m4_dquote is ]m4_defn([m4_dquote])
  m4_dquote([hi])
+ m4_dquote(tic, tac, toe)
  EOF
! $ @kbd{autom4te --language=m4sugar -o output foo.m4}
  foo.m4:2: error: possibly undefined macro: m4_dquote
!      If this token and others are legitimate, please use m4_pattern_allow.
!      See the Autoconf documentation.
! $ @kbd{cat output}
  try two: m4_dquote is [$@@]
  [hi]
+ [tic],[tac],[toe]
  @end smallexample
  
  @node Programming in M4sh