NAME
pretzel-it - use Pretzel to build a prettyprinter
SYNOPSIS
pretzel-it [-iqvdnh] language ppname
DESCRIPTION
Pretzel-it is a shell script that uses pretzel(1) to build a simple
prettyprinter executable. It minimizes building a Pretzel prettyprinter
to just one shell command. See pretzel(1) for a general overview and a
description of the input files.
You have to provide the same two input files to pretzel-it as to
pretzel. These two files are called the formatted token file (suffix
.ft) and the formatted grammar file (suffix .fg). Both files need to
have the same prefix language. From this input, pretzel-it generates
an executable prettyprinter called ppname.
Example
Say, you have written two files foo.ft and foo.fg that contain the
prettyprinting information for your favourite programming language foo.
To get an executable prettyprinter foopp for it, simply type:
pretzel-it foo foopp
OPTIONS
Pretzel-it has the following options:
-i Don’t remove intermediate products of pretzeling.
-q Run quietly.
-v Verbose mode, print shell commands before invoking (for
debugging).
-d Turn prettyprinter debugging features on by default; also
produce a detailed diagnosis file (suffix .output) that
contains a detailed analysis of the grammar and possible
problems with it (to ease debugging the prettyprinting
grammar).
-h Print full usage message.
-n Noweb mode. See section Interfacing with noweb(1) below.
THE GENERATED PRETTYPRINTER
The generated executable will be a program that reads source code from
the standard input and will write prettyprinted code to the standard
output. The prettyprinted code can be typeset using latex together with
the pretzel-latex document style.
Example
Say, you have built foopp already and have a scrap of source code in a
file bar.foo. Type
foopp <bar.foo >bar.tex
and the prettyprinter will prettyprint the code and write LaTeX code to
bar.tex. To use this code in your documents, simple include the
pretzel-latex document style and include the file inside the new ppcode
LaTeX environment. Here’s a minimal LaTeX file to look at the
prettyprinted code:
\documenstyle[pretzel-latex]{article}
\begin{document}
\begin{ppcode}
\input{foo.tex}
\end{ppcode}
\end{document}
INTERFACING WITH NOWEB
Using the -n option will produce a prettyprinting filter ppname
compatible to Norman Ramsey’s noweb(1) literate programming system. The
filter can be inserted into the noweb pipeline using noweave’s -filter
option.
For example, you can build a noweb prettyprinting filter for Pascal by
issuing
pretzel-it -n pascal prettypascal
inside the languages/pascal directory, you’ll get a prettyprinting
filter prettypascal . This filter then can be used within noweave(1)
by saying:
noweave -filter prettypascal foo.nw > foo.tex
This will prettyprint all code chunks using the Pascal prettyprinter.
You will need to include the pretzel-noweb.sty LaTeX document style
after including the noweb.sty ( see nowebstyle(1) ) to get the output
typeset correctly by LaTeX.
You can get debugging output from the prettyprinting filter by setting
the environment variable PRETZEL_NOWEB_DEBUG to a non-null value, e.g.
in the bash(1) shell by saying:
export PRETZEL_NOWEB_DEBUG=on
Debug output stops only when the value is explicitly unset (in bash(1)
this is the unset builtin command.
The noweb option at present works only for LaTeX as target typesetter.
If the prettyprinter experiences problems when prettyprinting a certain
code chunk, it automatically switches to standard verbatim output of
noweb. Through the inclusion of code within rules of the formatted
grammar file it is possible to automate indexing. For more information
see chapters 3 and 4 of the Pretzelbook, contained in the Pretzel
distribution.
CAVEATS
The pretzel-it shell script can only be run if the environment
variables PRETZEL_LIBDIR and PRETZEL_INCLUDE are set to the Pretzel
library directory (/usr/lib/pretzel on Debian systems) and the Pretzel
include directory (/usr/include/pretzel on Debian systems). During
execution, pretzel-it might issue warnings that are due to the programs
it invokes (pretzel-it invokes pretzel(1), flex(1), bison(1) and the
GNU C++ compiler).
The -n (noweb) option works only for LaTeX as target typesetter and is
still very much experimental.
FILES
/usr/lib/pretzel/libpretzel.a pretzel runtime library.
/usr/include/pretzel directory for runtime library include
files.
/usr/include/pretzel/pscan.h
/usr/include/pretzel/pparse.h template headers for the generated
functions.
/usr/lib/texmf/tex/latex/pretzel/pretzel-latex.sty
LaTeX style to typeset Pretzel output.
/usr/lib/pretzel/plainpp.o simple main program linked to the
prettyprinter object generated by
Pretzel.
/usr/lib/pretzel/plaindpp.o simple main program linked to the
prettyprinter object generated by Pretzel
with debug features.
/usr/lib/pretzel/nowebpretzelpp.o main
program the interfaces the Preztel
prettyprinter with noweb.
SEE ALSO
pretzel(1), noweb(1)
The Pretzelbook by Felix Gaertner, included in the Pretzel
distribution.
The Pretzel homepage on the WWW at http://www.iti.informatik.tu-
darmstadt.de/~gaertner/pretzel
AUTHOR
Felix Gaertner, email: fcg@acm.org
June 11, 1998 pretzel-it(1)