Ubuntu Manpage: pretzel-it - use Pretzel to build a prettyprinter

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.

AUTHOR

       Felix Gaertner, email: fcg@acm.org

                                          June 11, 1998                             pretzel-it(1)