
				-----

			Diary of the `pretzel'

				-----


It's Tuesday, 4th October 1994, and I am finally staring to work on
this project again. There has been a break of over a year now between
the last keys I added to this project and much has happened inbetween.
I had started this project without having much experience in building
things alike and this might be the key reason why reading the source
code to this project strikes me with such severity.

I am tempted to go over the code fully again and build everything from
scratch. But having only one month left to finish it (own deadline)
this doesn't seem feasible. Instead I will take the existing code as a
frame and recycle most of the parts that have worked already. (This
seems to be a good test to the LitProg style I've used a year ago.)
Joachim is surely looking forward to putting an end to this project
too, so I'll try to be as swift as possible. Anyway, I've done more
complicated things and they've worked... Simplicity is the key for
a fast final finish.

Things to do:

  o Get rid of the `makeWEAVE' name and think of better terms for
    the `preBISON' and `preFLEX' files.

  o Strip off unessential code from the main program. Simplify the
    options.

  o Look at each of the file processors individually...

Work will continue. We'll talk again on Monday, 31st October.


4-10-94:

I'll use RCS to try and have the changes in style traceable.

5-10-94:

Went to the library today and found the names I was looking for. The
system will be called `pretzel' (which was the word following `pretty'
in the dictionary). The `preFLEX' file will be the `token format' or
`formatted token' file (or `token' file for short). The `preBISON' file
will be the `grammar format' file or `formatted grammar' file.

Starting to revise the code for the output class today.  Stuffed
everything into RCS.

6-10-94:

Finished revision of specifications for the output class. Took me
nearly 3 hours. Excluded the written history from the file.

7-10-94:

Finished revision of the output class implementation. Wrote a small
test program that shows that the standard stuff works nicely. This
took me 2:30 hrs.

Renamed fwmac.sty into pretzel.sty and stuffed it into RCS.

13-10-94:

Had a few days off. It's hard to get back into it again. Finished
the first revision of the specs for the Attribute class. (2:00)

14-10-94:

Finished revision of the implementation of the attribute class.
Added a picture and wrote the tester for it. (2:00)

Renamed the following files and directories:

	preflex		ftokens
	prebison	fgrammar

	l_parse.spz	ftparse.spc
	l_parse.y	ftparse.y

	l_scan.spz	ftscan.spc
	l_scan.y	ftscan.y

	lwvtoken.h	ftokdefs.h

	tl_parse	ftokens

Stuffed the whole freshly named set of ex-preflex files into RCS.

17-10-94:

Revised formatted token scanner. Need to think about what to
include in the specs for these modules. (1:30)

18-10-94:

Changed the interface for the formatted token file parser. Now
it is simply a generator for a prettyprinting scanner. The
fact that it is a parser is shielded from the user.

That's it: The ideas of this morning are quite convincing. This is
they way I'll structure the program:

  Pretzel is a program that generates a prettyprinter from a
  formatted token file and a formatted grammar file. The
  prettyprinting method used is a parser using format command
  primitives.

  Pretzel can be divided into two parts:

  1. The prettyprinting scanner.
  2. The prettyprinting parser (the `real' prettyprinter).

  There are two functions/commands to build both parts:

  1. ftokens (or the build_pscan() function).
  2. fgrammar (or the build pparse() function).

  The first is a generator for the prettyprinting scanner and the
  second generates the prettyprinting parser.

This is the general idea. There are ways to fine tune both the
generated scanner and the parser (e.g. change the names of the
generated functions).

The way to change the name of the generated scanner is to redefine
the macro PSCAN_NAME in the definitions section of the formatted
token file (has to be bracketed with %{ and %}).

Fine tuned the scanner generator today. It even does some error control
now. (1:30)

The thing to do now is to work on the parser generator. I'll do some
preliminary work today and go on tomorrow. Next things to do would
be to rewrite the specs and the implementation. I can go along the
example tested with the scanner generator. But that's tomorrow.

19-10-94:

New names:

    y_parse.spz           fgparse.spc
    y_parse.y		  fgparse.y
    y_scan.spz            fgscan.spc
    y_scan.l              fgscan.l
    ywvtoken.h            fgramdefs.h

Function names changed too (e.g. y_parse -> build_pparse, etc.).

Finished fgscanner and fgparser. I have to think about how to generate
the header files for both. Now at least you can redefine the names of
the generated scanner and parser, but the prettyprinting code inside
the generated parser still uses intrisicts of the scanner.


20-10-94:

Header files are not generated! This is a decision for simplicity.
The user can write his own header files if he wants, because the
interface of the generated scanner is well defined. It consists of
two functions:

    int  <scanner name> (Attribute** );
    void <scanner name>_init (istream* );

where <scanner name> defaults to `pscan' but can be changed by
redefining the PSCAN_NAME macro in the definitions section of the
formatted token file.

The scanner expects to find token code definitions (MATH, EXPR, ...)
in a file called `ptokdefs.h' that has to be provided by the user.
The name of the file can be changed by redefining PTOKDEFS_NAME.

The generated parser also has a well defined interface. It consists
of one function

    void <parser name> (istream*, ostream*);

where <parser name> is the value of PPARSE_NAME or `pparse' by
default. It expects a scanner (with the same specs as above) to
be reachable as `pscan' and an initializer function as `pscan_init'.
The name (prefix) of the scanner (and initializer) can be changed
by redefining PSCAN_NAME at the beginning of the formatted grammar
file.

The parser expects a token header file under the name of `ptokdefs.h'
to be in the current directory. The name can be changed by redefining
PTOKDEFS_NAME.

By default, the parser uses the generated scanner without change.

21-10-94:

Now you can define the name of the scanner initialiser function
seperately from the scanner name in both formatted token and grammar
file. Also, as the generated parser doesn't need to include the common
token definitions, he doesn't do it. Only the generated scanner does
it (correctly now).

In the generated scanner code there is a default version of the
necessary yywrap() routine. If you want to declare a routine of your
own you have to #undef PSCAN_YYWRAP in the definitions section of the
formatted token file and supply a version of your own.

24-10-94:

Added pscan.spc, a CWEB header template for the default prettyprinting
scanner. Also added pparse.spc, a header template for the prettyprinting
parser.

Now pretzel works. There had been problems, because multiple main()
programs had been included in the run time library, but after going
over each individual Makefile this has been taken care of.

Started to revise the documentation. Need to produce a user's manual
quickly (a usable one).

25-10-94:

Started to revise the second chapter, which is the main part of
the user's manual.

27-10-94:

Second chapter is half revised.

24-2-95:

Spent the last week revising chapter 1. This week was spent in fine
tuning the report. Today -- at last -- I'm finished and can hand
it in. At least now I can be proud of it (a bit).

26-4-95:

Today I finally gave the printed and bound version of the report
to Joachim. That's that.

Today I also met the first user of pretzel (apart from me, I've met
me before).  So I cleaned up the source code and bundled everything
together nicely.

27-4-95:

Another printout for other people interested in pretzel. Together with
the GNU GPL it's ready for the ftp server.

That's that. Final remarks will be added to the README. Changes will
be documented in the change logs of the files.

---------------------------------------------------------------------
