KNOW HOW GNU m4 GNU m4 Creating HTML pages m4 is a macro language used for text processing. It simply copies its input to its output, while expanding built-in or user-defined macros. It can also capture output from standard Linux commands. BY STIG BRAUTASET e will cover the basics of m4 configure script familiar to anyone At this point you may ask “What’s the by separating out content and installing software directly from source. point then? I may as well be writing the Wlayout of HTML web pages. As mentioned earlier, m4 allows us to HTML code in the usual way, instead of The techniques shown are not by any easily define our own macros, and this is using this m4 mumbo-jumbo!” The means restricted to HTML, but are the feature we will focus on. We will astute reader would, of course, be 100% applicable elsewhere as well. learn how to hide layout specifics, long- correct in this observation. However, winded code or arcane syntax behind read on as the benefits will be explained Before we begin… our own simple macros. in the next couple of paragraphs. Very basic knowledge of HTML would be Consider a snip of HTML you write a lot; beneficial, but should not be necessary to How m4 can help you write a simple example is the code for creating read and comprehend the material HTML links. Chances are it will be like this: covered in this article. It is m4’s There are no (to the author’s knowledge) capabilities as a macro processor ready-made macros for writing HTML, <a href="http://www.w3.org">U language the author wishes to communi- so we we will have to write them ourself. www.w3.org</a> cate; HTML was chosen because it is something most people should be at least Naming conventions vaguely familiar with. When splitting the content from the layout of web pages, the author prefers to call the common What is m4? macro file for html.m4.The content of each page goes in a file with the ending “.mac”,e.g. index.mac and so on.When explaining this,however,we develop our macro and .mac files bit by m4 is a macro processor used by bit,so we need to refer to several different files.Thus it is convenient to name them first.m4, Sendmail and GNU Autoconf, etc. first.mac and so on. Sendmail relies on m4 for creating its See the sidebar “Joining the content and layout”how to create the resulting HTML file from the (in)famous sendmail.cf configuration file macros and the content. while Autoconf uses m4 to create the 40 November 2002 www.linux-magazine.com GNU m4 KNOW HOW Now, what if we instead define a simple Comments: documenting The only change is that we now have macro that will allow us to write “$1” and “$2” instead of “$*”. “$1” and our macros “$2” refer to the first and the second __elink(www.w3.org) If a macro is not self-explanatory,we would argument of our macro. The arguments like to put an explanatory comment along are separated by the comma character. side the macro definition. m4 naturally and let m4 do the tedious job of filling in So, Sherlock, what now if we want to allows us to do this; it provides the built-in the necessary bits? That’s less than half create a macro that can take an dnl which reads and discards all characters, the number of characters already. up to and including the first newline. argument with a comma in it? That, my Additionally, observe that we only had to good Watson, is simple. We just have to dnl Iamanexample comment. write the link name once, so there is less put quote the argument. When you dnl Iamhighly unhelpful, chance of us spelling it wrong. quote something, everything between dnl but 100% correct. Another example is if we have a note the quote-characters will be treated as a Using dnl as part of a string does not exhibit on our page telling visitors the date of single argument, even if it consist in this behaviour. the last update. It is tedious work entirety of a string of, say, 90 commas. searching through all the files you have The default opening quote is a “`” changed, searching for and updating body. We will refer to the whole line as (back-tick) and the default closing quote date stamps. Instead we can simply the macro definition. The definition line is a “‘” (single quote). We can now define a macro named, say, __today that above in English: “Define a new macro invoke __link2 with a comma in the will expand into today’s date. The named __link. Everywhere where this second argument thus: search-and-replace business will then be macro occurs, substitute the macro name taken care of for us automatically. How for the body of the macro, but substitute __link2(www.gnu.org, U to do this will be shown later; we need to the macro’s arguments (whatever is 'www.GNU.org, the home of much U take care of the basics first. inside the parentheses following the software') macro name) for “$*” wherever “$*” Getting your hands dirty occurs in the macro body.” The second comma is now quoted, so As mentioned earlier, m4 allow us to We will store the macros we write the macro is indeed invoked with only define our own macros with ease. The ourselves, such as the above, in a file two arguments. Note that only one layer command to let us do this is cunningly called html.m4. Se sidebar “Comments: named define. Here’s how to define a documenting our macros” for details Listing 1: sample.html macro to let us use the link shorthand about how we can mix comments and <html> above: macros in this file. <head> It’s worth noting that macro names do <meta http-equiv="Content-Type"U define(__link, U not have to start with two underscores. It content= "text/html; charset=iso-U <a href="http://$*">$*</a>) is just a convention, because we need to 8859-1"> make sure that we do not pick a string <meta name="description" U The part before the comma (but inside that naturally occurs in the text. content="Sample HTML page"> the parentheses) is the macro name, and Otherwise we may get spurious <meta name="keywords" U the part after the comma is the macro replacements of the macro. content="gnu m4 html"> <meta name="author" content="U Joining the content and Multiple arguments and quoting Stig Brautaset"> layout <title>sample html page</title> The define command we used above Here’s how you create the resulting </head> expects two arguments; the new macro index.html from the macro definitions in <body> name, and what to replace the macro html.m4 and the content in index.mac: <p>Hello, World</p> name with. Considering again the $m4html.m4 index.mac > </body> example with the __link macro above, index.html </html> This invokes the m4 processor with two what should we do if we don’t want to arguments.The m4 command will take the use the URL as the visible, “clickable” macro definitions it finds,do the necessary link? We could simply create a new Listing 2: first.mac macro that takes several arguments, and substitutions and output the result on its __title({Hello World, HTML U standard output.However,we make use of invoke it thus (in context this time, just version}) the shell’s redirection facilities to make the to show that it is possible): “Here is <h1>Hello World</h1> output go to a file instead of the screen (if __link2(www.w3.org, a link to w3.org). <p>Look at this link: U this makes no sense to you,just tag along It is an informative website.” Here’s how __link(www.w3.org)</p> and follow the directions,but you should to define such a beast: consider reading up on shell basics).Now <p>Last updated: __today</p> open first.html in a browser,and voil! We </body> define(__link2, U have a web page! </html> <a href="http://$1">$2</a>) www.linux-magazine.com November 2002 41 KNOW HOW GNU m4 of quotes (the outermost) are stripped by and can even be called several times m4, so the apostrophe in the following from the same file. Listing 5: second.m4 invokation will not yield an error: The effect is immediate, but only for this changequote({,}) U invokation of m4. The author strongly dnl change quote character __link2(www.gnu.org, U advocates that you stick to one set of dnl two macros for link-creation. 'GNU, RMS's pet hobby-horse') quotes, as it quickly becomes rather define(__link, U hairy having to remember which quotes <a href="http://$*">$*</a>) The author usually changes the default go where. define(__link2, U quote characters into “{” and “}” for The quoting “characters”, by the way, <a href="http://$1">$2</a>) readability and ease of typing. The need not be single characters; you may dnl abstract away all the U command for changing the quote use “{([whoopee->” as your opening layout cruft at the beginning. characters, with an appropriate com- quote if you wish. Neither is there any define(__title, { ment attached (see the “Comments: need for the closing quote to correspond <html> documenting our macros” sidebar), is: logically to the opening quote. It is just a <head> convention, and makes the macros <meta http-equiv=U changequote({,}) dnl U easier to read 3 months hence.