This is the file README for the GNU m4 distribution.

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

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

Installation consists of two steps.  First configure the program with

	./configure OSTYPE

where OSTYPE is a name for you operating system.  Check the config
directory for files of the type s-OSTYPE.h to see the possible OS names.

When the configuration is done,  say

	make all

which will compile the program `m4', but no install it.

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
example files `33.divert', `38.divnum' and `39.cleardiv'.  The file
`53.esyscmd' might also cause mismatches.  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


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 `etc/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), that is Berkeley specific.  Only the
	lib/obstack.? and lib/regex.? files does this.

      * 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
	* The config-files used by configure
	* 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.

Needless to say, I much prefer bug reports, which 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, is that I have not been able
to find any simple/pretty solutions to 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.



ADDING CONFIGURATIONS.
=====================

If you operating system does not match any of the configurations
included in the distribution, you must create your own.  Adding a new
configuration only amounts to creating two files in the config
directory.

First, chose a name for the configuration.  Usually this is the name and
version number of the operating system.  It is referred to as <OSTYPE>
below.  The name you chose is the name given to configure, when you want
to configure GNU m4 to you system.

Secondly, the create the file config/hmake-<OSTYPE>, which is inserted
in the Makefile by configure.  It should at least define macro OS as
`-D<OSTYPE>'.  Also, it can redefine any of the macros CC, CFLAGS,
LDFLAGS, DEPEND, INSTALL and INSTALLDATA, to suit the facilities of the
operating system.

Thirdly, create an include file, config/s-<OSTYPE>.h, describing which
facilities m4 can rely on having.  Currently, not much is needed, and
most of it is explained in the file config/s-template.h, which can be
edited to into config/s-<OSTYPE>.h.

Now, say

	./configure <OSTYPE>

to configure GNU m4 to your operating system.

Beware, that lib/regex.c uses the macro USG to decide whether to use
memcpy(3) or bcopy(3).  For System V like systems, it might be necessary
to include -DUSG in the definition of OS.



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.


* Thu Oct 24 15:18:46 1991

Version 1.0, manual 1.0.

	* Uses GNU configure, taken from the gdb distribution.

	* Uses GNU getopt(), with long option names.

	* The -Q/+quiet option is added, which suppresses warnings about
	  missing or superflous arguments to built-in macros.

	* Added default options via the M4OPTS environment variable.

	* The built-in format can now be configured to use sprintf as
	  the formatting engine, for systems without [efg]cvt(3).

	* GNU library code is moved to the ./lib subdirectory; other
	  utility files are now in ./etc.

	* Several minor bugs have been fixed.

Many thanks to those, who provided me with bug reports and feedback.
