Re: named diversions

[Eric Blake]

On 03/16/2015 06:12 PM, Matěj Týč wrote:

>> According to the manual, m4sugar defines KILL and GROW as named
>> diversions; m4sh (if you use AS_INIT instead of m4_init) also adds
>> BINSH, several HEADER-*, M4SH-SANITIZE, M4SH-INIT, and BODY.  That is,
>> if you are using autom4te to generate a shell script, then you
>> eventually want to m4_divert_push([BODY]) (although you get it free by
>> using AS_INIT).
>>
>> As for creating new named diversions, they are not documented in the
>> manual, but you can learn about them in the m4sugar source code
>> (basically, m4_define([_m4_divert(NAME)], NUMBER) will define
>> m4_divert_push(NAME) to use that diversion number).
> Thank you for your reply!
> I use m4sugar to create a file (a DB schema, a .dot file, ... - not a
> bash script), so I don't want to involve m4sh.I simply manually call
> autom4te -l m4sugar on definition files.

Interesting.  I'm not aware of any other major clients of just m4sugar
outside of autoconf (I do know that libtool uses m4sh outside of
autoconf, but that's higher than m4sugar); but I also agree that
avoiding m4sh makes sense in your use.

> The GROW diversion seems to work nicely, but the documentation somehow
> discourages using it in that way since it has another purpose (... is
> used behind the scenes by topological sorting ...).

Correct (in particular, m4_require and friends make use of it).

> However, your advice works, one can register new diversions exactly in
> the way you have described, I have defined a new diversion No. 1 as
> STDOUT. Wouldn't make such diversion sense in m4sugar?

I wouldn't want it in m4sugar, as none of the other layers on top of it
would use it; but just as m4sh, autotest, and autoconf have each added
named diversions, I see no issue with you adding it in your layer.

> Anyway, I would like to add the documentation about this diversion stuff
> too. Are you OK with that?

I'm not sure how much documentation we need (most of this won't be used
by the common configure.ac writer) vs. better comments in m4sugar.m4 but
out of the manual.  As it is, I think that documenting anything in the
'_m4_' namespace (such as _m4_divert(NAME)) in the manual is unwise, and
that if we really wanted to document creating new defined names, we'd
need to rework the code to avoid the internal namespace.  But you're
certainly welcome to submit patches if you think it would be useful for
the next person trying the same task (maybe even by defining some sort
of wrapper of m4_create_named_divert([name], [number]) which defines the
internal _m4_divert(NAME) under the hood).

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

signature.asc
Description: OpenPGP digital signature