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)