Things to watch out for with htm4l

Unfortunately, there are some rather nasty gotchas that can pop up when using htm4l. M4 can be obscure, stubborn, and difficult to understand (and that's putting it lightly). You would do well to read (at some point) whatever m4 documentation you have, or find HTML m4 documentation by following links on my m4 page.

1. One of the problems with using m4 and html is that the programs that process your .htm4l file (and its .html product) are often very quiet about errors. M4 will sometimes go silently nuts when it finds unmatched single quotes and if you don't look at your output carefully you may never notice. Likewise, your browser can probably deal with all sorts of crud and not complain. It will display something and simply toss away anything that looks like rubbish.

2. As I said, be careful with single quotes inside arguments to m4 macros. The best policy is to use the html escape codes for them. The grave quote (top left to bottom right) "`" can always be specified as ` and the acute accent (bottom left to top right) "'" as '. Trying to avoid quoting problems using m4's changequote command may cause you more problems than you expect.

3. Commas can also create problems sometimes. Occasionally you will put a comma into the text of a macro argument and m4 will interpret it as an argument separator. You can always avoid this by quoting the comma (putting it inside an grave/acute accent pair): `,'.

4. Be careful with the # character. M4 treats this as indicating the start of an m4 comment and ignores everything else on the line. M4 does not strip out comments, and so the # and everything following it is simply passed to the output stream verbatim. Macro calls following the # will simply not be seen. Again, you can always get around `#' problems by quoting it in a grave/acute pair: `#'.

5. Finally, unless you already know lots about m4 and its keywords, you will eventually unwittingly use an m4 keyword in a document and it will be interpreted as a macro call (with no arguments) by m4 and simply disappear. The GNU m4 tries to minimize this by not calling a macro that requires arguments, but there are still plenty of ways to get caught. The following table shows macro names that (if not quote with grave and acute accents) will simply be swallowed silently by m4. This data is accurate for GNU m4 version 1.4.

Macro Name Produces on stdout Produces on stderr GNU only?
__file__ current file name nothing yes
__line__ current line # nothing yes
changecom nothing nothing no
changequote nothing nothing no
debugfile nothing nothing no
debugmode nothing nothing no
divert nothing nothing no
divnum 0 nothing no
dnl nothing nothing no
dumpdef nothing nothing no
dumpdef nothing various macro definitions no
errprint nothing nothing no
format nothing nothing yes
indir nothing NONE:0: m4: Undefined macro `' yes
m4exit nothing nothing no
m4wrap nothing nothing no
shift nothing nothing no
sysval nothing 0 no
traceoff nothing nothing no
traceon nothing nothing no
undivert nothing nothing no

If you have GNU m4 and you're really concerned about not getting caught by this last kind of problem, I suggest you look at the -P option to m4. Note though that if you use this, your macros will probably not be usable by people who do not have GNU m4.

Apart from these few things, I don't know of any problems. If you use htm4l, you will soon get used to watching for these possible errors and dealing with them before they bite. If you do get bitten, there's a good chance you'll learn something about m4, which can only be a good thing.

Back to the htm4l home page.
© Terry Jones (terry <AT> Last modified: Mon Oct 2 02:22:03 CEST 2006