This is the file README for the GNU m4 distribution.

The current version of this program is 0.75, and of the manual 0.07.

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 check

and inspect the output.  You will find the input to these tests in the
directory "examples" (the files have been generated automatically from
the manual source file).  You will see "stdout mismatch" from the
examples that uses "^D" to mark end of input.  This is normal.

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

On HP-UX this line will compile GNU m4

	make CC=cc CEXT=-DUSG LOADLIBES='-lBSD -lPW'

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.1, with cc and gcc 1.39 (w and w/o -traditional)
	Vaxen, MORE/bsd, with cc and gcc 1.39 (w and w/o -traditional)
	HP 9k300, MORE/bsd, with cc (actually gcc 1.34 -traditional)
				and gcc 1.39 (w and w/o -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.



* Thu Nov 15 21:51:06 1990

Updated and enhanced version.  Version 0.75, manual 0.07.

Changes from version 0.50 to 0.75 are:

	* Implemented search path for include files (-I option and
	  M4PATH envronment variable).

	* Implemented builtin "format" for printf-like formatting.

	* Implemented builtin "regexp" for searching for regular
	  expressions.

	* Implemented builtin "patsubst" for substitution with regular
	  expressions.

	* Implemented builtin "esyscmd", which expands to a shell
	  commands output.

	* Implemented "__file__" and "__line__" for use in error
	  messages.

	* Implemented character ranges in "translit".

	* Implemented control over debugging output.

	* Implemented multi-character quotes.

	* Implemented multi-character comment delimiters.

	* Changed predefined macro "gnu" to "__gnu__".

	* Changed predefined macro "unix" to "__unix__", when the -G
	  option is not used.  With -G, "unix" is still defined.

	* Changed "shift", "$@" and "$*" to not insert spaces afters
	  commas.

	* Added program name to error messages.

	* Fixed two missing null bytes bugs.




* Fri Jul 26 15:28:42 1991

Fixed various bugs.  Version 0.99, manual 0.09.

Changes from version 0.75 to 0.99 are:

	* The builtins incr and decr are now implemented without use of
	  eval.

	* The builtin indir is added, to allow for indirect macro calls
	  (allows use of "illegal" macro names).

	* The debugging and tracing facilities has been enhanced
	  considerably.  See the manual for details.

	* The -tMACRO option is added, marks MACRO for tracing as soon
	  as it is defined.

	* Builtins are traced after renaming iff they were before.

	* Named files can now be undiverted.

	* The -Nnum option can be used to increase the number of
	  divertions available.

	* Calling changecom without arguments now disables all comment
	  handling.

	* The function m4_patsubst() is now consistently declared
	  static.

	* A bug in dnl is fixed.

	* A bug in the multi-character quoting code is fixed.

	* Several typos in the manual has been corrected.  More probably
	  persist.

	* The m4.info file is now installed along with the program.

Many thanks to Francois Pinard <pinard@iro.umontreal.ca> and Roland H.
Pesch <pesh@cygnus.com> for providing me with reports.
