16. Correct version of some examples

Some of the examples in this manuals are buggy, for demonstration purposes. Correctly working macros are presented here.

The exch macro (see section Arguments to macros) as presented requires clients to double quote their arguments. A nicer definition, which lets clients follow the rule of thumb of one level of quoting per level of parentheses, involves adding quotes in the definition of exch, as follows:

define(`exch', ``$2', `$1'')
⇒
define(exch(`expansion text', `macro'))
⇒
macro
⇒expansion text

The cleardivert macro (see section Discarding diverted text) cannot, as it stands, be called without arguments to clear all pending diversions. That is because using undivert with an empty string for an argument is different than using it with no arguments at all. Compare the earlier definition with one that takes the number of arguments into account:

define(`cleardivert',
  `pushdef(`_n', divnum)divert(`-1')undivert($@)divert(_n)popdef(`_n')')
⇒
divert(`1')one
divert
⇒
cleardivert
⇒
undivert
⇒one
⇒
define(`cleardivert',
  `pushdef(`_num', divnum)divert(`-1')ifelse(`$#', `0',
    `undivert`'', `undivert($@)')divert(_num)popdef(`_num')')
⇒
divert(`2')two
divert
⇒
cleardivert
⇒
undivert
⇒

The fatal_error macro (see section Exiting from m4) does not quite match the format of internal error messages when invoked inside wrapped text, due to the current limitations of __file__ (see section Printing current location) when invoked inside m4wrap. Since m4 omits the file and line number from its warning messages when there is no current file (or equivalently, when the current line is 0, since all files start at line 1), a better implementation would be:

define(`fatal_error',
  `errprint(__program__:ifelse(__line__, `0', `',
    `__file__:__line__:')` fatal error: $*
')m4exit(`1')')
⇒
m4wrap(`divnum(`demo of internal message')
fatal_error(`inside wrapped text')')
⇒
^D
error-->m4: Warning: excess arguments to builtin `divnum' ignored
⇒0
error-->m4: fatal error: inside wrapped text

This document was generated by System Administrator on September, 23 2007 using texi2html 1.70.