named diversions

[Matěj Týč]

Hello again,
In my m4 project where I use autom4te and m4sugar (for those who are
curious - https://github.com/matejak/d8 ),
in order to be able to output anything, one has to call
m4_divert_push(1) (or something similar) at certain point. However,
every time I do that, I get the
warning: prefer named diversions
warning. I know that I can use m4_divert_push(KILL) in place of
m4_divert_push(0), but a trivial diversion e.g. for stdout is not
available (or documented). There is also a lack of documentation on how
to register a named diversion, using a macro instead of a number isn't
the right way how to make a named diversion.
Do you have any solution to this in mind? Telling autom4te to suppress
warnings doesn't feel right.

[Eric Blake]

Post by Matěj Týč
Hello again,
In my m4 project where I use autom4te and m4sugar (for those who are
curious - https://github.com/matejak/d8 ),
in order to be able to output anything, one has to call
m4_divert_push(1) (or something similar) at certain point. However,
every time I do that, I get the
warning: prefer named diversions
warning. I know that I can use m4_divert_push(KILL) in place of
m4_divert_push(0), but a trivial diversion e.g. for stdout is not
available (or documented). There is also a lack of documentation on how
to register a named diversion, using a macro instead of a number isn't
the right way how to make a named diversion.
Do you have any solution to this in mind? Telling autom4te to suppress
warnings doesn't feel right.

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).

[Matěj Týč]

Post by Eric Blake

Post by Matěj Týč
Hello again,
In my m4 project where I use autom4te and m4sugar (for those who are
curious - https://github.com/matejak/d8 ),
in order to be able to output anything, one has to call
m4_divert_push(1) (or something similar) at certain point. However,
every time I do that, I get the
warning: prefer named diversions
warning. I know that I can use m4_divert_push(KILL) in place of
m4_divert_push(0), but a trivial diversion e.g. for stdout is not
available (or documented). There is also a lack of documentation on how
to register a named diversion, using a macro instead of a number isn't
the right way how to make a named diversion.
Do you have any solution to this in mind? Telling autom4te to suppress
warnings doesn't feel right.

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.
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 ...).
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?
Anyway, I would like to add the documentation about this diversion stuff
too. Are you OK with that?
BR,
Matej

[Eric Blake]

Post by Matěj Týč

Post by Eric Blake
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.

Post by Matěj Týč
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).

Post by Matěj Týč
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.

Post by Matěj Týč
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).