Re: Bug in dumpdef's documentation

[Patrice Dumas]

On Tue, Oct 26, 2021 at 11:21:39AM -0500, Eric Blake wrote:
> On Tue, Oct 26, 2021 at 02:30:26AM +0200, 4dr14n31t0r Th3 G4m3r wrote:
> > The output documented is not what you get from executing the m4 commands as
> > documented. See https://www.gnu.org/software/m4/manual/m4.html#Dumpdef
> 
> Thanks for the report.  More details would have been nice (what you
> think was wrong, and what you were expecting), but I can reproduce
> that where the manual says:
> 
> dumpdef(`foo')
> error→foo: ⇒
> 
> in practice (given the earlier definition of foo in the example), it should 
> be:
> 
> dumpdef(`foo')
> error→foo:    `Hello world.'
> ⇒
> 
> Looking at the source, in doc/m4.texi, there is:
> 
> @example
> $ @kbd{m4 -d}
> define(`foo', `Hello world.')
> @result{}
> dumpdef(`foo')
> @error{}foo:@tabchar{}`Hello world.'
> @result{}
> dumpdef(`define')
> @error{}define:@tabchar{}<define>
> @result{}
> @end example
> 
> My initial guess is that there is a bug in the texi -> html conversion
> where @tabchar{} gets eaten incorrectly, resulting in the html output
> omitting the rest of the intended line.  But checking just now, I see
> the same problem in 'info m4' on the corresponding page, so it is not
> a bug in the conversion, but in the m4.texi source itself.  Earlier in
> the m4.texi, there is:

Is there a true tab character after the @ in the macro?  Or are there
spaces?  I assumed a tab, though it should not change the issue nor the
solution I propose

> @c @tabchar{}
> @c ----------
> @c The testsuite expects literal tab output in some examples, but
> @c literal tabs in texinfo lead to formatting issues.
> @macro tabchar
> @       @c
> @end macro
> 
> So maybe the problem is that the macro expansion is leaving a bare @c
> which then eats the rest of the line when using the macro within
> @example.

It is indeed what happens, the expansion of the texinfo conserves the
@c. (macro expansion can be tested with the -M option).  So `Hello world.'
and <define> disappear:

@example
$ @kbd{m4 -d}
define(`foo', `Hello world.')
@result{}
dumpdef(`foo')
@error{}foo:@   @c`Hello world.'
@result{}
dumpdef(`define')
@error{}define:@        @c<define>
@result{}
@end example

One possibility is to add an end of line in the macro definition, which
should work for texi2any:

@c @tabchar{}
@c ----------
@c The testsuite expects literal tab output in some examples, but
@c literal tabs in texinfo lead to formatting issues.
@macro tabchar
@       @c

@end macro

However, this needs to be tested with texi2pdf, as texi2pdf may need
something else.

-- 
Pat