gf is short for "general formatter", i.e., it can work on documents
which use the ISO "general" document type definition (DTD). It can
convert SGML documents conforming to a small number of DTDs into
various output formats: LaTeX, ASCII, RTF and Texinfo. However not
every output format can be generated for every DTD.

Apart from the general DTD, gf supports the HTML DTD used in the WWW
project and the Snafu DTD I just made up. There are many other DTDs
which would be worth supporting. However gf is not intended as a
flexible system for hacking up a formatter for a random DTD, but as a
usable document production system for a few DTDs.

For more information on gf and the supported DTDs, see the file
doc/gf.sgml.  gf can be used to convert this documentation into other
formats if desired.

gf may be copied and modified under the terms of the GNU General
Public License, version 2. See the file COPYING for details.

gf is usually available at
ftp://ftp.th-darmstadt.de/pub/text/sgml/misc, in the SGML archive
maintained by Joachim Schrod.

Installation
------------ 
This package contains source code: compiling it requires a computer
with a Unix-like operating system, a compiler supporting ANSI-C
prototypes and the flex program (available from GNU archives) among
other things.

James Clark's nsgmls program must also be installed (from sp version
1.0.1 or 1.1, see http://www.jclark.com/sp/index.htm).

Typesetting the LaTeX output produced by gf requires LaTeX version 2e.

To compile and install gf, follow these steps:

1. The default output from gf is LaTeX 2e, but can be changed at the
top of of src/Makefile.in.

2. If LaTeX is to be used, there are some macros which must be
installed.  Set the location at the top of latex2e/Makefile.in
according to your TeX installation.

3. LaTeX 2.09 output is no longer supported.

4. Run ./configure: see the file INSTALL for more details.

5. make

6. make install

7. If you want to build and install Info format versions of the
documentation, run "make info" and "make install-info".  This
requires the makeinfo program to be available.  You need to edit the
"dir" file in the info directory as usual.

8. If you want to install the LaTeX 2e macros, type "make install-2e".

Formatting the Manuals for Printing
-----------------------------------
PostScript versions of the two user manuals can be created (via
LaTeX) by switching to the doc directory and typing "make gf.ps"
or "make snafu.ps".

Alternatively ASCII or RTF versions can be created, e.g., 
"gf -fab gf.sgml > gf.txt".

Future Development
------------------
There are some difficulties with the way gf is implemented which
suggest future development in this direction would not be a great
idea, particularly:

- It is not possible to make even minor modifications to the
supported DTDs without modifying and recompiling the C code in
gf.  Likewise, supporting new DTDs requires modification and
recompiling.

- The C code is unpleasant in some ways: there is a lot of tedious
manual memory management and list manipulation.  Fixing this would
require either a better support library or a better language.

- It isn't clear that this type of file conversion is particularly
useful, or at least would not be useful in a world where SGML was
widely used.  Once it is possible to format an SGML file for display
on a screen or paper, producing a TeX or RTF version does not gain
much.

Acknowledgements
----------------
Some code and many ideas are from other sources:

Initial support for HTML 3.2 tables was contributed by Abbey akalay-watkin
<abbey@afsmail.cern.ch> (later rewritten).

The tables for the conversion of ISOlat1 to "best" ASCII follow a system
developed by Markus Kuhn.

ISOlat1.2tex is based on a latin1 to TeX table by (I think) Peter Flynn.

Other TeX symbols were grabbed individually from numerous sources.

error.c is from the GNU textutils by David MacKenzie.

putenv.c is from the GNU C library version 1.09.

getopt.c, getopt1.c, getopt.h are from the GNU C library version 1.07.

The HTML DTD is by Dan Connelly et al. from the WWW project.

ISOlat1 etc., and general.dtd are from the ISO.

mkinstalldirs, configure, install-sh, INSTALL are from autoconf.
----------------

Gary Houston <ghouston@actrix.gen.nz>
