This is the file README for the GNU m4 distribution.

The current version of this program is 0.50, and of the manual 0.05.

INSTALLATION.
============

Installation should be fairly straightforward.  Unpack the distribution, and
edit the Makefile to use you preferred C compiler (CC) and options (COPTS),
and installation directory (BINDIR).  Then say

	make all

To run a simple test of your new m4, say

	make -i test

and inspect the output.  There is rather a lot, so you might want to save it
in a file.  The output should contain both the input and output of m4 run on
most of the examples from the manual.  You will find the input to these tests
in the directory examples (the files have been generated automatically from
the manual source file).

In the subdirectory test you will find various m4 files, ranging from trivial
test files, to rather advanced macros.  You might want to play a little with
these files too.  If you intend to use m4 seriously, you might find useful
material down there.

When you have finished playing, install m4 with the command

	make install


If you are using System V, you should define USG when compiling.  You can
either edit the Makefile to do this, or say

	make CEXT=-DUSG all

I have had no possibility to test the USG part, as I have only access to
Berkeley derived systems.  Most of the USG things are taken from GNU make.

PORTABILITY.
===========

GNU m4 has been compiled and tested on the following systems:

	Sun-[34], SunOS 4.0, with cc and gcc 1.35 (w and w/o -traditional)
	Vaxen, MORE/bsd, with cc and gcc 1.35 (w and w/o -traditional)
	HP 9k300, MORE/bsd, with cc (actually gcc 1.34 -traditional)
	Vaxen, Ultrix 2.0, with cc

I have absolutely no idea about how hard it will be to port m4 on other
systems.  I have tried to keep the program clean, so hopefully the problems
won't be that big.  In any case, if you manage to compile and use this program
on a system, that is not on the list above, I would like to know.  If you had
to make changes, send me them too.

PROBLEMS.
========

There are a few things, that will no doubt cause trouble for some of you.

      * The functions used for error messages uses vfprintf(3), that is not a
	part of all systems.  If you system does not have vfprintf(), there is
	a version in `vfprintf.c', that might, or might not, work on you
	system.  This version of vfprintf() is from the released BSD code.

      * The program uses bcopy(3) and bzero(3), that are Berkeley specific.
	The USG stuff taken from GNU make should fix this in most cases.

      * The code for diversions uses mkstemp(3), that is apparently not a part
	of System V and other non 4.3BSD derived systems.  There is a usable
	version in `output.c' (ifdef'ed on USG or ultrix), but that version
	doesn't solve the problem mkstemp() is there to solve.  Too bad!

      * Probably oodles of other little annoying details.

BUG REPORTS.
===========

Send bug reports to me (Rene' Seindal, email: seindal@diku.dk) or to
bug-gnu-utils@prep.ai.mit.edu.

ALL bug reports should include:

	* The version number of m4
	* The hardware and operating system
	* The compiler used to compile
	* A description of the bug behaviour
	* The input to m4, that triggered the bug
	* A transcript of the output from m4

If I can't reproduce the bug, there is really not much I can do about it.

Again, since I have no access to System V machines, I can't do much about
bugs, that are System V specific, unless, of course, the bug reports are
accompanied by patches/fixes.

KNOWN BUGS.
==========

This version of GNU m4 suffers from at least these known bugs.  The reason,
why these bug have not been fixed, varies.  Most often, it is because I don't
know how to solve the problems involved.

      * Sync lines (-s option) and diversion are not happy together!  The
	problem is which lines and file names that should be attached to text
	that are being, or have been, diverted.  System V m4 regards all the
	diverted text as being generated by the source line containing the
	`undivert' call, whereas GNU m4 regards the diverted text as being
	generated at the time it is diverted.  Which is right?

	I expect the sync line option to be used mostly when using m4 as a
	front end to a compiler.  If a diverted line causes a compiler error,
	I believe that the error messages should refer to the place where the
	diversion were made, and not where it was inserted again.  Comments
	anyone?

	Anyway, GNU m4's approach causes a serious bug, if calls to undivert
	aren't alone on the input line.  See the file `test/divert.m4' for a
	demonstration of the bug.  I don't feel it is acceptable to insert
	newlines in the output the user hasn't asked for.

      * The second argument to `eval', specifying an output radix, cannot be
	larger than 36 in the current implemention.  Which characters can be
	used as digits, if the radix is larger than 36?  Currently any radix
	larger than 36 are rejected.



RELEASE HISTORY.
===============

* Mon Jan 22 21:08:52 1990

Initial beta release.  Version 0.50, manual 0.05.
