Gary Houston's gf - General Formatter 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 (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