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;
How m4 can help you write
beneficial, but should not be necessary to a simple example is the code for creating
HTML
read and comprehend the material 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, U
language the author wishes to communi- so we we will have to write them ourself. www.w3.org
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
macro file for html.m4.The content of each page goes in a file with the ending  .mac , e.g.
What is m4?
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 The only change is that we now have
Comments: documenting
macro that will allow us to write  $1 and  $2 instead of  $* .  $1 and
our macros
 $2 refer to the first and the second
If a macro is not self-explanatory, we would
__elink(www.w3.org) 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. argument with a comma in it? That, my
up to and including the first newline.
Additionally, observe that we only had to good Watson, is simple. We just have to
dnl I am an example comment.
write the link name once, so there is less put quote the argument. When you
dnl I am highly 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

above: macros in this file.

It s worth noting that macro names do
define(__link, U not have to start with two underscores. It
content= "text/html; charset=iso-U
$*) is just a convention, because we need to
8859-1">
make sure that we do not pick a string
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
the part after the comma is the macro replacements of the macro.
content="gnu m4 html">

quoting
layout

The define command we used above
Here s how you create the resulting

expects two arguments; the new macro
index.html from the macro definitions in

name, and what to replace the macro
html.m4 and the content in index.mac:

Hello, World

name with. Considering again the
$ m4 html.m4 index.mac >
example with the __link macro above,
index.html
what should we do if we don t want to
This invokes the m4 processor with two
use the URL as the visible,  clickable
arguments.The m4 command will take the
link? We could simply create a new
macro definitions it finds,do the necessary Listing 2: first.mac
substitutions and output the result on its macro that takes several arguments, and
__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

Hello World

output go to a file instead of the screen (if
__link2(www.w3.org, a link to w3.org).

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)

and follow the directions,but you should
to define such a beast:

Last updated: __today

consider reading up on shell basics).Now
open first.html in a browser,and voil! We
define(__link2, U
have a web page!

$2)
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
Listing 5: second.m4
m4, so the apostrophe in the following from the same file.
changequote({,}) U
invokation will not yield an error: The effect is immediate, but only for this
dnl change quote character
invokation of m4. The author strongly
dnl two macros for link-creation.
__link2(www.gnu.org, U advocates that you stick to one set of
define(__link, U
'GNU, RMS's pet hobby-horse') quotes, as it quickly becomes rather
$*)
hairy having to remember which quotes
define(__link2, U
The author usually changes the default go where.
$2)
quote characters into  { and  } for The quoting  characters , by the way,
dnl abstract away all the U
readability and ease of typing. The need not be single characters; you may
layout cruft at the beginning.
command for changing the quote use  {([whoopee-> as your opening
define(__title, {
characters, with an appropriate com- quote if you wish. Neither is there any

ment attached (see the  Comments: need for the closing quote to correspond

documenting our macros sidebar), is: logically to the opening quote. It is just a
convention, and makes the macros
"Content-Type" content=
changequote({,}) dnl U easier to read 3 months hence.
"text/html; charset=U
change the quote characters
iso-8859-1">
changequote({,}) dnl change U
changequote takes two arguments, the quote character
content="Sample HTML page">
new opening and closing quotes dnl create a link with the U
respectively. It can be called at any time, link name specified specifically
content="gnu m4 html">
define(__link2, U
$2)
Listing 3: first.m4
content="Stig Brautaset">
changequote({,}) U

With a html.m4 containing the
dnl change quote character

definitions shown above we can invoke
dnl two macros for link-creation.

our __link2 macro thus:
define(__link, U
$1
$*)

__link2(www.w3.org, {w3.org, U
define(__link2, U

a site well worth reading})
$2)
}) dnl the __title macro U
dnl abstract away all the layout U
ends here
Enough basics, let s do some real work
cruft at the beginning.
dnl use built-in  esyscmd to call the
With HTML, there s always a lot of
define(__title, {
standard Linux  date dnl utility and have its
stuff that needs to be set up at the top of

output replaced with the  __today dnl
each page. If you have more than, say,

macro name.The date will be on the form
2-3 pages that have a similar layout (but
 Sun 16 Jun 2002 define(__today,
with optionally different
HTML and macro calls that together

define(__index) dnl allows U
with our macro definitions enables us to

conditional processing of the U
}) dnl the __title macro U
page
Listing 4: second.m4
ends here
__title2({Hello World, HTML U
dnl use built-in 'esyscmd' to call the
__title2({Hello World, U version}, {
standard Linux 'date'
HTML version}, {

Hello World

dnl utility and have its output

Hello World

__menu
replaced with the '__today'

Look at this link: U

Look at this link: U
dnl macro name. The date will be on
__link(www.w3.org)

__link(www.w3.org)

the form "Sun 16 Jun 2002"

Last updated: __today

Last updated: __today

define(__today, esyscmd(date '+%a %d
}) })
%b %Y'))
42 November 2002 www.linux-magazine.com
GNU m4 KNOW HOW
capability to call standard Linux tools, and tags either, and indeed __rlink(index.html, index))

and puts the output of the said you don t have to. m4 allows macros to ifdef({__pics}, pictures, U
command ( date in this case) into the be nested, thus we can use a macro __rlink(pics.html, pictures))
text. Listing 3 shows the full content of within another macro. The result is

first.m4. This contains all the macro shown in listing 4. Witness that the })
definitions required by first.mac which is __title2 macro takes two arguments, the
found in listing 2. first being the page title and the second The two ifdef lines are new to us. They
being the full page body. Be careful first check whether a certain macro
More abstraction
when you go to these lengths of name is defined (observe that the first
Looking at the code in listing 2, you may abstraction though, as it is easy to miss argument of ifdef has to be quoted). If
not want to write the closing out the closing  }) at the end of the file the macro name is undefined, the third
if you do extensive updates. argument will be input into the text, and
The change to listing 3 to facilitate this the second argument will be ignored.
Listing 7: third.m4
is shown in listing 5. The use of the __menu macro is shown
changequote({,}) U
in listing 6.
dnl change quote character
More advanced macros
The __rlink macro is also new. Its
define(__link, U
Up till now, we have only looked at fairly name stands for relative link in that it
$*)
simple search-and-replace macros. These does not prepend http:// to the link. It is
define(__link2, U
work fine, but consider if we have a shown in listing 7, which is the final
$2)
collection of pages, with a common macro listing file.
define(__rlink, U
menu. We could put the whole menu in
$2)
Summary
a macro of the type we have used before,
dnl abstract away all the U
but then the pages would include a link We have seen how to use m4 to create
layout cruft at the beginning.
to itself as well as all others, and this is macros to help us maintain HTML pages.
define(__title2, {
not very elegant. A solution, of course, is We went from very simple one-line

to just cut-and-paste the menu in to the substitution macros, like __link and

individual files and change each file to __link2, to bigger but still very simple
not make a link to itself. This, however, macros of the same type, like __title.
"Content-Type" content=
is very tedious. The solution? Use m4 s From there, we went on to using m4 s
"text/html; charset=U
built-in conditionals. built-in ability to capture the output of
iso-8859-1">
In each source file we define a macro system commands when we created the
that identifies that file. In index.mac we __today macro. Lastly we used m4 s
content="Sample HTML page">
content="gnu m4 html"> conditional  ifdef can then use these macro that expands into a different
content="Stig Brautaset"> take special actions on this file. The
menu could then be something like this:
INFO

[1] GNU m4: more information about the m4

define(__menu, {
macro processor can be found at
$2

MENU

http://www.gnu.org/software/m4/m4.html

ifdef({__index}, index, U
[2]HTML tidy: get your HTML cleaned up and

validated
})
Using tidy to clean up the
http://www.w3.org/People/Raggett/tidy/
dnl use built-in  esyscmd to call the
mess
standard Linux  date dnl utility and have its
If you ve opened any of the HTML files you ve
output replaced with the  __today dnl
Stig Brautaset, born in
created from the macro and content files,
macro name.The date will be on the form
Norway, is the
you ve probably found that there s a lot of
 Sun 16 Jun 2002
founder of the Linux
unnecessary white-space in them.This is OK,
define(__today, esyscmdU Society at the
since excessive white-space is simply ignored
University of
(date '+%a %d %b %Y'))
by web browsers. If you re a pedantic zealot
Westminster. He is
define(__menu, {
like the author, you ll want your source to be
currently in his last

beautiful on its own as well.
year of a BSc Artificial Intelligence
ifdef({__index}, index, U
degree. His interests largely revolves
Enter  tidy , an HTML validating, correcting
__rlink(index.html, index))

around computer programming 
and pretty-printing program. Simply invoke
from e-mail spam filters to games.
ifdef({__pics}, pictures, U
tidy on your HTML files thus: tidy -im
Regularly spending much time on IRC
__rlink(pics.html, pictures))
first.html and the file will be audited and
he can be found there under the nick

printed prettily. See the sidebar  Links and
 Skuggan or  Skugg .
}) resources for where to get tidy.
www.linux-magazine.com November 2002 43
THE AUTHOR