\documentclass[a4paper]{article}

\usepackage{a4}
\usepackage{iso8859-1}
\usepackage{epsfig}

\begin{document}
\title{Ebnf2ps --- Automatic Railroad Diagram Drawing}
\author{
  Peter Thiemann\\
  Wilhelm-Schickard-Institut, Universität Tübingen\\
  Sand 13, 72076 Tübingen\\
  E-mail: \texttt{thiemann@informatik.uni-tuebingen.de} \\
  \copyright 1994, Peter Thiemann}
\maketitle

Ebnf2ps  was written to fill an urgent need of the author: to produce lots of
syntax diagrams (railroad diagrams) from a grammar in EBNF notation in short
time. Over the time the program has attracted a couple of features in order to
fulfill a variety of requirements.

The program may be freely used and distributed, you are however required not to
remove the copyright notices from the source files. Please send any comments,
bugs, etc.\ to the author.

\section{How to build it}

\begin{enumerate}
\item  Edit the Makefile to reflect your Haskell compiler, for example
\begin{verbatim}
        HC= hbc
\end{verbatim}
\item Find out where your TeX installation stores \texttt{.afm}-files (Adobe font
  metric files) and change the variable \texttt{afmPathDefault} in
  \texttt{Ebnf2ps.hs} accordingly. Alternatively, you can set the environment
  variable \texttt{AFMPATH} when running the program.
  These files are absolutely necessary. If you don't find them complain to
  your system administrator or get    them yourself from
  \texttt{ftp://ftp.adobe.com/pub/adobe/AFMFiles/}.
\item 
  Change the variable \texttt{rgbPathDefault} to contain the directory where
  your X installation stores its color data base (usually
  \texttt{/usr/lib/X11/rgb.txt}). This can also be corrected later with the
  environment variable \texttt{RGBPATH}.
  There are fallback color definitions for the 8 digital colors
  (black, white, blue, green, cyan, reg, magenta, yellow, white), so 
  nothing needs be done if that's enough for you.
\item 
  Typing \texttt{make} should produce an executable file named \texttt{Ebnf2ps}.
\end{enumerate}


\section{How to use it}

The syntax is
\begin{verbatim}
Ebnf2ps [options] BNFfile Nonterminal ...
\end{verbatim}
where the \texttt{options} are described in Sec.~\ref{sec:options}, the syntax
of the input file \texttt{BNFfile} in Sec.~\ref{sec:syntax}, and
\texttt{Nonterminal} describes the nonterminals, for which diagrams are to be
generated, as regular expressions (see Sec.~\ref{sec:regular}).


\subsection{Options}
\label{sec:options}

The following list shows all \textbf{options} with their \emph{parameters} and their
(default values). All distances and sizes measured in 1/100 point (1 point is
about 1/72 inch).
\begin{description}
\item[-ntFont \emph{font}] (Times-Roman) PostScript font used for nonterminals, any font goes
  here that your printer knows and for which you have fetched the AFM
  files. 
\item[-ntScale        \emph{int}] (10) Pointsize of typeface for
  nonterminals. 
\item[-ntColor      \emph{color}] (black) Color of typeface for nonterminals. 
\item[-tFont         \emph{font}] (Times-Roman) PostScript font used for
  terminal strings. 
\item[-tScale         \emph{int}] (10) Pointsize of typeface for terminals.
\item[-tColor       \emph{color}] (black) Color of typeface for terminals.
\item[-borderDistX    \emph{int}] (500) Horizontal distance of objects from
  their container.
\item[-borderDistY    \emph{int}] (500) Vertical distance of objects from their
  container. 
\item[-lineWidth      \emph{int}] (30) Width of lines used for connecting lines.
\item[-fatLineWidth   \emph{int}] (100) Width of lines used for drawing boxes.
\item[-lineColor    \emph{color}] (black) Color used for connecting lines.
\item[-fatLineColor \emph{color}] (black) Color used for outlines of boxes.
\item[-arrowSize      \emph{int}] (200) Size of (invisible) box containing an arrow.
\item[-rgbFileName    \emph{int}] (rgb.txt) File name for color definitions.
\item[-happy]                Accept happy format input files. Default: accept
  EBNF syntax as described below. 
\item[+ps]                   Produce encapulated PostScript output (default).
\item[+fig]                  Produce fig output (FORMAT 2.1).
\item[+simplify]             Simplify productions (experimental, default: don't).
\item[-verbose]              Prints some progress messages.
\item[-help]                 Prints a brief description of the command line,
  the options, and the environment variables.
\end{description}

\subsection{Syntax of the input file}
\label{sec:syntax}

\begin{verbatim}
File            = {Production}.
Production      = Nonterminal [ String ] "=" Term "." .
Term            = Factor / "|" .                # alternative
Factor          = ExtAtom + .                   # sequence
ExtAtom         = Atom
                | Atom "/" Atom                 # repetion through Atom
                | Atom "+".                     # at least one repetion
Atom            = Nonterminal
                | String                        # terminal string
                | "(" Term ")"
                | "[" Term "]"                  # an optional Term
                | "{" Term "}"                  # zero or more repetions
                .
String          = "\"" { character } "\"" .
Nonterminal     = letter { letter | digit | "_" } .
character       = "\\" charesc.
\end{verbatim}
Or in terms of diagrams (what would you expect):
\begin{center}
  \leavevmode\epsfbox{File.eps}
  \\
  \leavevmode\epsfbox{Production.eps}
  \\
  \leavevmode\epsfbox{Term.eps}
  \\
  \leavevmode\epsfbox{Factor.eps}
  \\
  \leavevmode\epsfbox{ExtAtom.eps}
  \\
  \leavevmode\epsfbox{Atom.eps}
  \\
  \leavevmode\epsfbox{String.eps}
\end{center}
These diagrams have been produced with:
\begin{verbatim}
Ebnf2ps -tFont Courier-Bold ebnf.BNF '.*'
\end{verbatim}

\subsection{Syntax of regular expressions}
\label{sec:regular}

The regular expressions used to select nonterminal symbols have the following
syntax.
\begin{verbatim}
RAtom    = character | "\\" character | "." | "\\(" Regexp "\\)" .
RExtAtom = RAtom ["*" | "+" | "?"] .
RFactor  = RExtAtom + .
Regexp   = Factor / "\\|" ["$"].
\end{verbatim}
Well, graphically, that is:
\begin{center}
  \leavevmode\epsfbox{RAtom.eps}
  \\
  \leavevmode\epsfbox{RExtAtom.eps}
  \\
  \leavevmode\epsfbox{RFactor.eps}
  \\
  \leavevmode\epsfbox{Regexp.eps}
\end{center}

\subsection{Environment variables}

The format of search pathes is a colon separated list of directories. The
default path is inserted in place of an empty directory in the list. Any file
name starting with a \texttt{/} is taken as an absolute name and any file name
starting with a \texttt{.} is taken relative to the current working directory.

\begin{description}
\item[AFMPATH] Path to search for Adobe font metric files. 
\item[EBNFINPUTS] Path to search for input files.
\item[RGBPATH] Path to search for the color definitions.
\end{description}



\section{How to change it}

In order to add new options to the program you will need a modified copy of the
program \texttt{Mkhprog} written by Nick North (\texttt{ndn@seg.npl.co.uk})
which is available from URL 
\begin{verbatim}
http://www-pu.informatik.uni-tuebingen.de/~thiemann/haskell/ebnf2ps/
\end{verbatim}


\end{document}