Quoting Text for Autoconf

[Bruce Korb]

I wrote this up.  Akim (or anyone else), have you a moment
to tell me if I am lying here?

  http://autogen.sourceforge.net/acquoting.html

Thanks!  :-)

---

Quoting Text for Autoconf

Autoconf is primarily a collection of M4 macros that are used to permute your supplied text into the desired result. This alleviates the need for you to type in all the repetitive text necessary for doing configure tests and it also makes it possible to fix bugs and change implementation without going back and fixing all the scripts that use the algorithms.

The issue with quoting evolves mostly as follows:

• To work, M4 needs to be able to determine where the start and end of text are for each of its macro arguments. It does this by collecting text between the "(", "," and ")" characters.

• Sometimes, however, you need these characters as part of the macro argument string. Therefore, M4 adds the notion of quoting a string. You can quote a string by surrounding the text with "`" and "'" characters.

• In order to include these characters, you simply have to make sure they are properly ordered and nested. M4 will keep track of the depth and preserve the nested quotation characters.

• Autoconf has a problem with this. In programming, these two quoting characters are used often and used for different purposes. Consequently, they will rarely happen to match. M4 provides a feature that Autoconf takes advantage of: changequote().

  With that special built-in macro, you can change the quoting characters to another pair of tokens that may, in fact, be several characters long. Autoconf did not take advantage of that, it changed it to "[" and "]" instead.

• That mostly works in the programming world. That is because square brackets are generally used in pairs and so they behave as properly nested quotes in Autoconf's m4 files. The problem is the "mostly" part, of course.

Autoconf's solution for this is ``quadrigraphs''. These are very ugly four-character improbable sequences that get replaced in a final pass through sed(1) to emit the configure program. The reason Autoconf chose to do this instead of merely having users change quotes around the macro arguments was because the macro arguments are allowed to and encouraged to use Autoconf macros within them. If you change quotes around an Autoconf macro, M4 will become confused because the macro was written on the assumption that it knew what the current quoting phrases are (viz., "[" and "]").

As a consequence, you, the Autoconf macro developer should, in general, do everything you can to write code that either does not contain square brackets, or only contains them in balanced pairs.

If, in some circumstance you cannot, you have these choices:

1. Replace the square bracket characters by hand that cause the imbalance. You should have AutoGen leave the text alone because the quote phrases are now balanced again.

2. Have AutoGen blindly replace all Autoconf-problematic characters with quadrigraphs. Who cares if it's ugly. Don't look at it. Just beware, quoted arguments to contained Autoconf macros will have those quoting square brackets replaced, too.

3. Have AutoGen surround the text with changequotes. Just beware, if the text contains any Autoconf macros, they will be expanded with the wrong quoting characters current. M4 will likely become confused. This is likely okay for C/C++/etc program text; Autoconf macros should only appear in shell text.

Well, that's pretty much it. You are now an expert on Autoconf's use of M4 quoting. Your final exam consists of trying to use either conftest or even autoconf directly.

---

  

AutoGen, AutoOpts, columns, getdefs, AutoFSM, AutoXDR and these web pages copyright (c) 1999 - 2002 Bruce Korb, all rights reserved.
Last modified: Wed Jan 16 10:48:51 PST 2002