%-*-TeX-*-
% Copyright 1989, David Love, SERC Daresbury Laboratory
\def\ps{{\sc PostScript}}
\def\web{{\tt WEB}}
\font\sc=cmcsc10
\centerline{{\bf Local guide for PS}\web}
\vskip5ex
\centerline{David Love, SERC Daresbury Laboratory ({\tt
love@daresbury.ac.uk})}
\vskip5ex
\noindent
This note describes the restrictions on the \ps\ code imposed by
this implementation of \web\ for \ps, the treatment of the \web\
source by {\tt TANGLE} and {\tt WEAVE} and points out a useful piece
of self-referential treatment of the code.

\beginsection Restrictions on names

There are restrictions on the characters allowed in names.  Apart from
alphamerics and underscores, only {\tt !\$\&*-} are allowed.  These
should allow some messing around defining silly-looking private names
as well as allowing {\tt -} as a `word' separator.

\beginsection {\tt WEAVE} treatment of code

Only rather limited pretty-printing is possible as the semantics of a
\ps\ expression are so difficult to establish. What is done
is:\footnote{*}{This is like GNUEmacs' \ps\ grinding, I discover.}
\item{$\bullet$} Newlines in the source are obeyed.  Consecutive
newlines are replaced by a `bigskip'---newline with extra vertical
space.  
\item{$\bullet$} \ps\ names are printed in math, numbers in
roman, strings in {\tt \char'134ttex}.
\item{$\bullet$} The only keywords which are
recognised and to which meaning is attached are {\it def}, {\it
begin}, {\it end}.   A literal name which is {\it def\/}ed has its
index entry underlined.
\item{$\bullet$} Blocks delimited by {\tt
begin} $\ldots$ {\tt end}, {\tt \char'173} $\ldots$ {\tt \char'175},
{\tt [} $\ldots$ {\tt ]}, {\tt <} $\ldots$ {\tt >} are indented.
\item{$\bullet$} The indentation may be controlled using the special
tokens {\tt =>} and {\tt <=} respectively to increase and decrease the
indentation level by one.  They tangle to nothing and are not valid
names anyway under the rules above.  They should be placed (anywhere)
on the line {\it before} the one to be in/outdented.  A typical use
might be to indent conditional code.  Maybe these frigs should be replaced
by {\tt WEB} control codes at some stage, although you can always send
the control sequences through using {\tt @t}.

\beginsection Demonstration of procedure results

Remember that the {\tt \char'134psfig} macro allows you to include
\ps\ into \TeX\ documents (if you have a suitable {\tt DVI} to \ps\
backend).  Thus you can include the {\tt TANGLE}d {\tt WEB} into the
{\tt WEAVE}d output to show example results of your code.

\beginsection \ps\ file conventions

The {\tt \%!}\ comment often required at the beginning of a \ps\ file
is inserted automatically into the {\tt TANGLE}d output.  There is no
other built-in support for the conventional structure of \ps\ files.
In particular, you may need to get a {\tt \%\%BoundingBox:}\ comment
in the output near the start---if you're using {\tt \char'134psfig},
for instance.  This can be achieved by using the {\tt @=} control
sequence.

\beginsection Example

An example of a literate re-write of a \ps\ exmaple is given in {\tt
outline.web}.  It demonstrates inclusion of the results in the
documentation. 
\bye