
 $Id: README,v 2.3 1998/02/24 15:38:55 gaertner Exp $


		      README for Pretzel v.2.0n

What's new from v.2.0i?
=======================

 o major bug fix with noweb prettyprinting filter (now you
   can use plain old noweb verbatim by default) 
 o major bug fix (suggested by David Wilson) in fgparse.nw
 o enhanced compatibility to debian linux (thanks to Anthony Towns)
 o added a prettyprinter for guarded command language (by
   Anthony Towns) in contrib/aj


What's new from v.2.0f?
=======================

 o minor bug fix (due to Holger Uhr)
 o full featured Java prettyprinter for use with noweb included
 o updated PretzelBook (now second edition) and documentation

What's new from v.2.0h?
=======================

 o noweb prettyprinters are more robust in that they use the
   standard noweb verbatim environment in case prettyprinting doesn't
   work

Introduction:
=============

This is the README to the pretzel system distribution v.2.0m.
Pretzel is a tool that helps you to generate arbitrary prettyprinters
for any language or formatter you like.

In this release, Pretzel offers enhanced support for Norman
Ramsey's noweb literate programming tool. Pretzel adds fully user
controlled prettyprinting and indexing facilities to noweb and thus
eliminates a lot of deficits of noweb, which is in nature a language
independent tool.

Pretzel comes with ready to use prettyprinters for Pascal and Java
(contributed by Lee Wittenberg). A rudimentary prettyprinter for C is
also included. Prettyprinters for other languages may be written
within hours (or days, as for C :-).  The distribution is fully
documented using noweb and contains quick reference manual pages as
well as a full blown user manual, the PretzelBook.


Prerequisites:
==============

You'll need up-to-date executable versions of:

 o the noweb literate programming system
   [ftp: host: ftp.th-darmstadt.de,
         dir:  /pub/programming/literate-programming/independent]

 o flex, the fast lexical analyser generator
   [at least version 2.4.6]

 o Bison, the GNU Parser generator
   [at least version 1.19]

 o The GNU g++ compiler (or any other C++ compiler at hand).


Obtaining Pretzel:
==================

Pretzel may be obtained through the Internet at the following URL:

    http://www.informatik.tu-darmstadt.de/BS/Gaertner/pretzel/code/pretzel-2.0m.tar.gz

There also is the Pretzel homepage that always contains the latest
information on the system:

    http://www.iti.informatik.th-darmstadt.de/~gaertner/pretzel

You may also browse the distribution to get individual files at:

    http://www.informatik.tu-darmstadt.de/BS/Gaertner/pretzel/distribution/

Installation & Getting Started:
===============================

 1. To get an executable version of pretzel, unpack the
    distribution and read the README (this file fully).

 2. Edit the beginning of the global Makefile to suit your
    system (i.e. specify where the executables, libraries,
    etc. should go).

 3. Type:

        make

    This will make the executables, objects and libraries for
    your system.

 4. Type:

        make install

    This will copy the installation files to the right places
    on your system.

 5. Setup environment variables PRETZEL_LIBDIR and PRETZEL_INCLUDE
    to point to the directory with the library and the directory
    with the includes.

Now you are ready to build prettyprinters of your own. Try copying the
pascal.ft and pascal.fg files (from the languages/pascal subdirectory)
into a directory of their own. Then type

    pretzel-it pascal pascalpp

This will produce a pascal prettyprinter executable pascalpp, which
reads pascal text from stdin and writes prettyprinted text in LaTeX to
stdout. In your LaTeX documents, include the document style option
`pretzel-latex' and you have a new environment `ppcode' into which
the text from pascalpp may be included.


Documentation:
==============

The user manual of Pretzel is called the Pretzelbook. It can be found
in the Pretzel distribution in the doc/pretzelbook directory. It is
the ultimate source of information on Pretzel and its friends.


Pretzel and noweb:
==================

Pretzel comes with a facility to build prettyprinting filters for
noweb. See the Pretzelbook and/or the directory contrib/noweb for more
information. The directory contrib/leew contains Lee Wittenbergs
prettyprinting filter for Java. All directories contain README files
that you may consult for more information.


Files:
======

Here's an overview over the directory structure:

README			this file
diary			the diary of pretzel

doc			documentation
doc/pretzelbook		the Pretzelbook
doc/styles		LaTeX styles for prettyprinting

man			manpages

attr			the Attribute class
output			the Output class
ftokens			the prettyprinting scanner generator
fgrammar		the prettyprinter generator function

main			main pretzel program
pretzel-it		directory for pretzel-it shell script

languages		contains examples for several languages
languages/pascal	Pretzel input for Pascal
languages/cee		Pretzel input for C (experimental)

bin                     directory for pretzel executables

contrib/noweb		noweb prettyprinting ad-on
contrib/noweb/general	general stuff for noweb prettyprinters
contrib/noweb/cee.latex	noweb prettyprinter for C and LaTeX
contrib/noweb/cee.html	noweb prettyprinter for C and HTML (experimental)
contrib/leew		Lee Wittenberg's noweb prettyprinter for Java


Thanks:
=======

I have to thank firstly Joachim Schrod for initiating this project and
his encouragement to hang on to it for so long. I also have to thank
Lee Wittenberg and Norman Ramsey for their help on release 2.0. Thanks
also to Roger Kehr and all those other students whom I have discussed
this topic with (whether they wanted or not). I am very grateful to
the Institut f"ur Theoretische Informatik here in Darmstadt and to
Professor Waldschmidt for providing the computing resources for this
project. Release 2.0 comes as a christmas present for me and the
people on the USENET comp.programming.literate newsgroup, who -- with
their discussions -- have helped to improve my understanding of this
subject and --- with their citations --- also have helped to impove
the Pretzelbook. :-)


Author:
=======

Send comments and bug reports to Felix Gaertner at

    fcg@acm.org

or snail mail to:

    Felix Gaertner
    Sonnhalde 9
    D-35041 Marburg
    Germany


  ===================================================================

    This is Pretzel v.2.0, the language independent prettyprinter
    generator. Copyright (C) 1995-98 by Felix Gaertner

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 
    02111-1307, USA

  ===================================================================


 $Log: README,v $
 Revision 2.3  1998/02/24 15:38:55  gaertner
 for Version 2.0i

 Revision 2.2  1997/07/09 14:34:16  gaertner
 for version 2.0g

 Revision 2.1  1996/12/17 08:19:18  gaertner
 added acknowledgements

 Revision 2.0  1996/12/16 18:05:38  gaertner
 for release 2.0f

 Revision 1.8  1995/09/08  16:18:09  gaertner
 *** empty log message ***

 Revision 1.7  1995/09/07  17:43:39  gaertner
 Adapted to new Makefile.

 Revision 1.6  1995/09/05  16:44:58  gaertner
 Removed section on multiple prettyprinters. Inserted pointers
 to ADDENDUM.

 Revision 1.5  1995/08/29  17:43:37  gaertner
 Added section on multiple prettyprinters.

 Revision 1.4  1995/07/20  09:28:10  gaertner
 Added note to pretzel-it script. Simplified installation
 documentation.

 Revision 1.3  1995/04/27  07:51:09  gaertner
 Added Gnu General Public License heading.

 Revision 1.2  1995/04/26  17:03:35  gaertner
 Updated entries to suit new global Makefile.

 Revision 1.1  1995/04/26  16:03:47  gaertner
 Initial revision

