During my Ph.D. candidature, I determined at one point that it would be very desirable to automatically insert diagrams from the MacDraw program on my Macintosh into TEX insertions in my thesis. This would allow diagrams to float around with the text and be printed automatically rather than having to be printed separately and stuck in with real glue. On the face of it, the problem seemed inherently solvable as the Macintosh could generate PostScript for each diagram and this PostScript could presumably be inserted into the PostScript generated using TEX.
The only trouble was that the Macintosh PostScript code for the diagrams relied on an Apple PostScript header file. This meant that the header file had to be included at the start of the TEX PostScript if the inserted PostScript for the diagrams was to work. Unfortunately, merely including the header file at the top didn't work, and it turned out that a rather detailed analysis of some parts of the Apple header file was required in order to perform the necessary surgery on the header file to make it work. This analysis was severely aggravated by the fact that the PostScript header file was virtually unreadable. Basically it was about 50K of interwoven definitions, that looked as if it had been run through a word processor. There was no way that the code could be understood clearly without some kind of reformatting. Two other aspects of the problem further complicated the analysis:
In fact the file was so messy and complicated that, as a rule, it had to be handled with kid gloves. It would have been unwise to re-arrange the definitions or to insert comments.
To my surprise, FunnelWeb provided an unexpected solution to the problem. First I replaced all occurrences of the @ in the header file with @@. Second, I placed the entire header file in a FunnelWeb macro definition connected to a product file. I then processed the file and checked to make sure that the product file was identical to the original file. By doing all this I had placed the header file under FunnelWeb control. I then left the macro definition largely untouched, but replaced the PostScript definitions of interest with FunnelWeb macro calls, moving the actual PostScript definitions into FunnelWeb macro definitions at the end of the FunnelWeb file.
@O@<LaserHeader.ps@>==@{@-
Unreadable Postscript code
@<Print routine@>
Unreadable Postscript code
@<Zap routine@>
Unreadable Postscript code
@}
@A This routine looks as if it does this, but really is does that,
blah, blah blah.
@$@<Print routine@>==@{@-
/print { push pop pop push turn around and jump up and down and print it} def
@}
@A This routine zaps the...
@$@<Zap routine@>==@{@-
/zap { push pop pop push turn around and jump up and down and print it} def
@}
Use of FunnelWeb meant that I was able to pluck out the definitions of interest (a very small part of the whole file) and collect them as a group at the end of the file where they could be studied. Because each definition was safely contained in a macro, it was possible to write a detailed commentary of each routine without fear of affecting the final PostScript code in any way at all. Once this analysis was completed, it was possible to perform surgery on the offending PostScript definitions in an extremely controlled way. In particular, the FunnelWeb input file served as a repository for all the different versions of particular routines that were tried in order to get the definitions to work. A new (Zero) macro was created for each version of each definition, and a commentary of how it performed added above it.
This case demonstrates that FunnelWeb is an extremely powerful tool for dissecting and documenting cryptic text files. Through the use of macros, particular parts of the file can be isolated and discussed without affecting the final product file in any way. In the example above, only a small part of the file was analysed, the rest being left as a blob, but in the general case, a cryptic text file could be inserted into FunnelWeb and then incrementally dissected (and possibly modified) until the result is a fully documented literate program. That this can be done without affecting the actual product file demonstrates the high degree of descriptive control that FunnelWeb provides.