The tar file you will unpack after downloading htm4l should contain:

• INSTALL
• README
• Makefile.sample
• root

To install htm4l on your machine:

1. Choose a central location that all users will be able to access. I'll call this directory $D. I use /usr/local/www/m4 for mine, because /usr/local/www is my server's document root and it made some sense to put it there.
2. Edit root/usr/local/www/m4/html-macros and modify $LOGNAME in the macro m4_last_modified_by (at the end of the file), if necessary. This should be the environment variable that (normally) contains your user name. This is typically $USER or $LNAME. $LOGNAME is the variable used by Linux. To find out which variable is used on your machine, try typing (for example) echo $USER to the shell. When you see your login name appear, chances are high that you've got the right variable. (Unfortunately, different shells do this differently, use a variable that works for you at least...)
3. Edit root/usr/local/www/m4/make-include so that the M4 macro in that file points to the version of m4 you'll be using. If you are using Solaris, make this /usr/5bin/m4. If you are using Linux, leave it alone. Otherwise, figure it out! In the worst case (e.g., you don't have m4, or your m4 gets itself into an infinite loop trying to deal with my macros), get the GNU version of m4, which is bound to work.
4. Finally,

   cp root/usr/local/www/m4/make-include root/usr/local/www/m4/html-macros $D

   These two files are

   • make-include : a file that should be included by the Makefile in the directories where you want to write htm4l files and convert them to html using make.
   • html-macros : a file that you will probably include in all your htm4l files.

   These files are more fully described in the URLs

   http://www.teclata.es/terry/htm4l/htm4l/makefile-use.html
   and
   http://www.teclata.es/terry/htm4l/htm4l/html-macros-use.html

Some Help

To help you get started and to understand the way the m4 macro files are set up on my machine, I have included a directory called 'root'. Under this directory you will find a mirror of files on my machine. The files are

• root/usr/local/www/m4/{html-macros,make-include}
• root/u/terry/html/m4/macros
• root/u/terry/html/htm4l/m4/macros
• root/u/terry/html/htm4l/htm4l/*.htm4l
• root/u/terry/html/htm4l/htm4l/examples/*.htm4l

The hierarchical chain of inclusions amongst the macro files here is also outlined in

http://www.teclata.es/terry/htm4l/htm4l/examples/inclusion.html

Most importantly, you can cd to root/u/terry/html/htm4l/htm4l and type 'make' to see all the htm4l files turned into html files by m4. From this directory, you can unravel the chain of macro inclusions back to the top (root/usr/local/www/m4/html-macros).

At least I hope you'll be able to.

It goes something like this:

The macros in root/u/terry/html/htm4l/m4/macros are specific to my documentation of htm4l. They contain things like the background specification for the htm4l documentation pages, the macros for the footers on the main and example pages etc.

All the htm4l files under root/u/terry/html/htm4l/htm4l include this file.

In turn, this file includes the macro file: root/u/terry/html/m4/macros. This is a file that contains things useful to me in general when I make html (i.e., not just the htm4l documentation).

That file (finally) includes root/usr/local/www/m4/html-macros which contains things that are useful for everyone in the production of html. Everyone on this machine who uses htm4l includes this file (if only indirectly) in each of their htm4l files.

Please feel free to mail me any questions you have and I'll try to answer them.