% ^^A -*-LaTeX-*-
%\iffalse
%<*pl>
%\fi
\def\filename{pl.doc}
\def\fileversion{3.0}
\def\filedate{1996/05/30}
\def\docversion{2.5}
\def\docdate{1995/11/28}
%\iffalse
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\typeout{%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
   Prolog Documentation in LaTeX. Version \fileversion\@spaces gene \filedate
%% 
%% Purpose:
%%   Style option for LaTeX to provide routines to document Prolog programs.
%%
%% Documentation: see seperate LaTeX document `pl.tex'
%%
%% Author: Gerd Neugebauer
%%         Mainzer Str. 8
%%         56321 Rhens (Germany)
%% Mail:   gerd@informatik.uni-koblenz.de
%%
%% Copyright (C) 1995-1996 Gerd Neugebauer
%%
%%  pl.doc is distributed in the hope  that it will  be useful, but WITHOUT
%%  ANY WARRANTY.    No author or   distributor accepts  responsibility  to
%%  anyone for the  consequences of using  it or for  whether it serves any
%%  particular purpose or works at all, unless he says so in writing.
%%
%%  Everyone is granted permission to copy, modify and redistribute pl.doc,
%%  provided this copyright notice  is preserved and any modifications  are
%%  indicated.
%%
%%
%%  This  style is still under  development and may  be replaced with a new
%%  version  which  provides an enhanced   functionality.  Any comments are
%%  welcome but don't expect ANY help from my side.
%%
}
%\fi
%
%    \title{Literate Programming:\\Prolog Documentation with \LaTeX}
%    \author{Gerd Neugebauer\\
%           Mainzer Str. 8\\
%           56321 Rhens (Germany)\\
%           Net: {\tt gerd@informatik.uni-koblenz.de}}
%
%    \date{{\footnotesize This document describes pl version \fileversion\
%          as of \filedate.}}
%
%    \maketitle
%
% ^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% \DoNotIndex{\@ifnextchar,\box,\dimen,\divide,\newif,\noindent,\normalsize}
% \DoNotIndex{\obeyspaces,\other,\raggedright,\relax,\rule}
% \DoNotIndex{\sf,\smallskip,\textwidth,\tiny,\wd,\endgraf}
% \DoNotIndex{\empty,\fbox,\fboxrule,\fboxsep}
% \DoNotIndex{\ifdim,\medskip,\multiply,\message}
% \DoNotIndex{\par,\parbox,\parshape}
% \DoNotIndex{\@,\@@par,\@beginparpenalty,\@empty}
% \DoNotIndex{\@flushglue,\@gobble,\@input}
% \DoNotIndex{\@makefnmark,\@makeother,\@maketitle}
% \DoNotIndex{\@namedef,\@ne,\@spaces,\@tempa}
% \DoNotIndex{\@tempb,\@tempswafalse,\@tempswatrue}
% \DoNotIndex{\@thanks,\@thefnmark,\@topnum}
% \DoNotIndex{\@@,\@elt,\@forloop,\@fortmp,\@gtempa,\@totalleftmargin}
% \DoNotIndex{\",\/,\@ifundefined,\@nil,\@verbatim,\@vobeyspaces}
% \DoNotIndex{\|,\~,\ ,\ProvidesPackage}
% \DoNotIndex{\advance,\aftergroup,\begingroup,\bgroup}
% \DoNotIndex{\mathcal,\csname,\def,\documentclass,\documentstyle}
% \DoNotIndex{\dospecials,\edef,\egroup}
% \DoNotIndex{\else,\endcsname,\endgroup,\endinput,\endtrivlist}
% \DoNotIndex{\expandafter,\fi,\fnsymbol,\futurelet,\gdef,\global}
% \DoNotIndex{\hbox,\hss,\if,\if@inlabel,\if@tempswa,\if@twocolumn}
% \DoNotIndex{\ifcase}
% \DoNotIndex{\ifcat,\iffalse,\ifx,\ignorespaces,\index,\input,\item}
% \DoNotIndex{\jobname,\kern,\leavevmode,\leftskip,\let,\llap,\lower}
% \DoNotIndex{\m@ne,\next,\newpage,\nobreak,\noexpand,\nonfrenchspacing}
% \DoNotIndex{\obeylines,\or,\protect,\raggedleft,\rightskip,\rm,\sc}
% \DoNotIndex{\setbox,\setcounter,\small,\space,\string,\strut}
% \DoNotIndex{\strutbox}
% \DoNotIndex{\thefootnote,\thispagestyle,\topmargin,\trivlist,\tt}
% \DoNotIndex{\twocolumn,\typeout,\vss,\vtop,\xdef,\z@}
% \DoNotIndex{\,,\@bsphack,\@esphack,\@noligs,\@vobeyspaces,\@xverbatim}
% \DoNotIndex{\`,\catcode,\end,\escapechar,\frenchspacing,\glossary}
% \DoNotIndex{\hangindent,\hfil,\hfill,\hskip,\hspace,\ht,\it,\langle}
% \DoNotIndex{\leaders,\long,\makelabel,\marginpar,\markboth,\mathcode}
% \DoNotIndex{\mathsurround,\mbox,\newcount,\newdimen,\newskip}
% \DoNotIndex{\nopagebreak}
% \DoNotIndex{\parfillskip,\parindent,\parskip,\penalty,\raise,\rangle}
% \DoNotIndex{\section,\setlength,\TeX,\topsep,\underline,\unskip,\verb}
% \DoNotIndex{\vskip,\vspace,\widetilde,\\,\%,\@date,\@defpar}
% \DoNotIndex{\[,\{,\},\]}
% \DoNotIndex{\count@,\ifnum,\loop,\today,\uppercase,\uccode}
% \DoNotIndex{\baselineskip,\begin,\tw@}
% \DoNotIndex{\discretionary,\immediate,\makeatletter,\makeatother}
% \DoNotIndex{\repeat,\scriptsize,\selectfont,\the,\undefined}
% \DoNotIndex{\arabic,\do,\makeindex,\null,\number,\show,\write,\@ehc}
% \DoNotIndex{\@author,\@ehc,\@ifstar,\@sanitize,\@title,\everypar}
% \DoNotIndex{\if@minipage,\if@restonecol,\ifeof,\ifmmode}
% \DoNotIndex{\settowidth,\@resetonecoltrue,\@resetonecolfalse,\bf}
% \DoNotIndex{\clearpage,\closein,\lowercase,\@inlabelfalse}
% \DoNotIndex{\selectfont,\mathcode,\newmathalphabet,\rmdefault}
% \DoNotIndex{\bfdefault}
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%   \CheckSum{468}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%  \CharacterTable
%%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%%
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%   \setcounter{IndexColumns}{2}
%   \def\PredicateIndex#1{}
%   \MakeShortVerb{"}
%
% ^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%    \section*{Introduction}
%
%   
%    Inspired by the idea behind the web  system I  felt the need to have a
%    system to write documented Prolog programs. But instead of having to
%    transform the common source into program or documentation the central
%    idea was to develop a  method  to have one  common  source which can  be
%    interpreted   by a  Prolog\footnote{C-Prolog, Quintus-Prolog, or ECLiPSe
%    at that time.} system aswell as  by \LaTeX.   To achive this  goal  the 
%    \LaTeX\ commands  are hidden from Prolog by enclosing them into comments.
%   
%    The C-Prolog allows two kinds of comments. The first kind starts with a 
%    "%" and ends at the end of the line. This is also a comment for
%    \LaTeX. 
%    The other Prolog comment starts  with "/*" and ends with "*/".
%    This  seemed  to be  the  right  way to hide   the \LaTeX\ documentation
%    commands from the Prolog interpreter.
%   
%    The only problem  was to  define a  starting sequence to  open the first
%    comment.  This sequence must be an executable Prolog  command as well as
%    a valid \LaTeX{} command. The first approach was to  modify both --- the
%    Prolog program and the \LaTeX\ style --- to find a common statement. The
%    pre 2.0 versions  of the  pl  style option took  this  decision.  One
%    problem came  up when the author tried  to incorporate the module system
%    of Prolog.  This system requires  that the first command  in a module is
%    the declaration of the module name possibly together  with the list of
%    predicates to be  exported. This restriction led  to the approach taken
%    in version 2.0 and later.  In modules nearly no change has  to be made.
%    The module declaration is defined as a valid \LaTeX\ macro.
%   
%   
%    \section{The \LaTeX\ Documentation Driver File}
%    
%    The  \LaTeX\ main file ties together  the whole documentation. This file
%    should contain   the "\documentclass" command together with the
%    appropriate "\usepackage" or the "\documentsyle" command  with  the style
%    option "pl".\smallskip 
%    
%    \noindent
%    \unitlength=\textwidth\advance\unitlength-65mm
%    \begin{minipage}{\unitlength}
%      \indent The  only special   command required  in   this file  is the
%      command  "\PrologInput". This  command inserts  the Prolog file
%      given as argument at the current position. The formatting directives
%      described below are activated.
%    
%      The command "\PrologInput" may occur several times in this main
%      file.  it   may    be    mixed with    simple  input    or   include
%      commands. "\PrologInput"  can be  used nested,  as  long as the
%      other requirements described in this document are fulfilled.
%    \end{minipage}
%    \hfill
%    \begin{minipage}{58mm}
%    {\small%
%      "\documentclass[...]{...}"\\
%      "\usepackage{pl}"\\
%      "\begin{document}"\\
%      "..."\\
%      "\PrologInput{file1.pl}"\\
%      "\PrologInput{file2.pl}"\\
%      "..."\\
%      "\PrologInput{filen.pl}"\\
%      "..."\\
%      "\end{document}"}
%    \end{minipage}\smallskip
%    
%    
%    The commands meant for the Prolog files can also be used in a plain
%    \LaTeX{} context. Nevertheless those commands have been developed
%    with the application of documenting Prolog in mind. The contents of
%    the Prolog files and the additional macros provided by pl will
%    be described in the next sections.   
%   
%   
%
%    \section{The Prolog Files}
%    
%    \subsection{Starting Modules}
%    
%    Prolog files can come in two variants: either  it is a Prolog module or
%    a plain Prolog file. Modules are distinguished from files by a specific
%    first  Prolog statement.    This  module  declaration   can  have   the
%    form\footnote{e.g. in Quintus-Prolog}
%    
%    {\it ":- module(" Name"," Exports ")."}
%    
%    Alternatively it may have the form
%    
%    {\it ":- module_interface(" Name ")."}
%    
%    These module declarations have to be the first Prolog instructions in
%    the file.
%
%    In addition to those Prolog instructions we need to use the rule
%    that the terminating point (.) of the module declaration is
%    followed immediately by \verb*+ /*+. Note the single space which is
%    neccesary for the Prolog parser to work properly.
% 
%    Thus a Prolog module documented with pl starts e.g. with 
%   
%    {\it ":- module\_interface(" Name "). /*"}
%   
%    Before this line there should be only Prolog comments starting with
%    "%". These comments are also ignored by \TeX. Thus they do
%    neither appear in the documentation nor are the evaluated by Prolog.
%   
%   
%    \subsection{Starting Plain Files}
%   
%    Plain Prolog files are those files not starting with a module
%    declaration. For technical reasons plain files can not start with code
%    directly but requires a C-style comment at the beginning. The contents
%    of this comment is typeset by \LaTeX.
%
%    In generale this restriction seems to be too hard. It is always a good
%    idea to start a file with some general remarks and comments.
%
%   
%   
%    \subsection{Ending Prolog Files}
%   
%    The Prolog file should end with
%
%    "\EndProlog*/"
%    
%    From the Prolog  point of view the  file consists now of the declaration
%    of a module (or a dummy predicate). The rest is purely comment. From the
%    \LaTeX\   point  of view   it   contains  two   macros  and  nothing  in
%    between. Thus everything in between will be interpreted as \LaTeX\ input
%    only.
%   
%    \subsection{Prolog Code}
%   
%    To include additional Prolog statements in this file enclose them in 
%
%    "\PL*/"
%   
%    "/*PL"
%
%    This forces the   Prolog system to  interpret  the code and  the \LaTeX\
%    system to typeset it in a verbatim like environment.
%   
%    The Prolog code may contain every characters except the string
%    "/*PL". For some reasons which are opaque to me spaces at the
%    binning of a line of Prolog code are ignored. To force proper
%    indentation you should use {\sc tab} characters at the beginning of the
%    line. 
%   
%   
%    \subsection*{Options for the Code Layout}
%   
%    The  options    are  implemented  as    macros.  To   change  them   use
%    "\renewcommand".
%   
%    \begin{description}
%      \item [\tt \char92 PrologModule]\ \\
%      Macro to typeset  the module  definition. In general  this  may be a
%      sectioning command  producing an appropriate    title. It takes  two
%      arguments --- the two arguments of the "module" declaration.
%     
%      The default is "\section{{\tt #1}}"
%      \item [\tt \char92 PrologFile]\ \\
%      Same as above but for non module files.
%    
%      The default is "\section{{\tt #1}}"
%      \item [\tt \char92 PrologFont]\ \\
%      Macro to select the font used  for printing the  listing part.  This
%      should  be  a    non-pro\-portional   font.    The      default   is
%      "\small\tt".
%    
%      \item [\tt \char92 PrologListFont]\ \\
%      Macro to select  the font used for  printing  the export  list.  The
%      default is "\small\tt".
%    
%      \item [\tt \char92 PrologListIndent]\ \\
%      Macro to select the indentation of the export list. This should be a
%      length. The default is "2em".
%    
%      \item [\tt \char92 PrologRuleWidth]\ \\
%      Macro to select the  width of the rule  to seperate Prolog code from
%      text. This should be a length. The default is "0pt".
%    
%      \item [\tt \char92 PrologNumberFont]\ \\
%      Font to be used when typesetting line numbers.
%    \end{description}
%    
%    The following flags can be set by simply including the commands in
%    the \LaTeX{} part of the document. Since they are mainly of a
%    global nature the preamble of the driver file would be a good place
%    for them.
%    
%    \begin{description}
%      \item [\tt \char92 PrologNumberLinestrue]\ \\
%        Turn on line numbering.
%      \item [\tt \char92 PrologNumberLinesfalse]\ \\
%        Turn off line numbering.
% 
%      \item [\tt \char92 PrologDialect\char251{\em Dialect}\char253]\ \\
%      Declare the dialect of the used Prolog. This is mainly important to
%      make the syntax of the modules known to pl. {\em Dialect}\/ can
%      take one of the following values: {\tt eclipse}, {\tt quintus}, {\tt
%      sixtus}, {\tt cprolog}, {\tt swiprolog}, {\tt sbprolog}, or {\tt
%      binprolog}.
%    \end{description}
%    
%    \section{Predicate Templates}
%    
%    Predicate templates provide a nice way  to typeset a predicate head with
%    some additional information. A  usual predicate is characterized  by the
%    name/arity, arguments  and the file it can  be  found in. Two  boxes are
%    used to  contain this information. The  right one contains the file name
%    and  the left one  contains the predicate  description.  The box for the
%    file name has  a default width  which will be enlarged  if the file name
%    doesn't fit into it. The predicate  description if surrounded by a frame
%    and formatted in the following way.  If the predicate desciption fits in
%    one line then  it  is typeset in  one line.   Otherwise the  second  and
%    following lines are  indented. This indentation  tries  to align beneath
%    the first argument. If the predicate name is very long this might not be
%    desirable. Thus  the indentation has a  maximal value  which will not be
%    exceeded.
%    
%    The \LaTeX\ part of the file contains the following template
%    
%    "\Predicate pred/1(arg)."
%    
%    Note that the ")." have {\em no}\/ space in between.
%    
%    \subsection*{Options}
%    
%    The   options  are  implemented   as  macros.    To   change   them  use
%    "\renewcommand".
%    
%    \begin{description}
%      \item [\tt \char92 PredicateFont]\ \\
%      Macro containing   the   font changeing  command  for the  predicate
%      description. The default is "\normalsize\tt".
%    
%      \item [\tt \char92 PredicateSkip]\ \\
%      Macro containing  the spacing  before  and after the predicate
%      description.  The  default is  "\smallskip".
%    
%      \item [\tt \char92 PredicateIndent]\ \\
%      Macro  containing  the  maximal  length of the    indentation of the
%      predicate description.  The default  is "2em".   If this  value
%      is very large   then the arguments  are  always aligned  beneath the
%      first one.
%
%      \item [\tt \char92 PredicateFileFont]\ \\
%      Macro containing  the font changeing command  for the file name. The
%      default is "\small\sf".
%    
%      \item [\tt \char92 PredicateFileWidth]\ \\
%      Macro containing the  minimal width of  the box containing  the file
%      name.  The default is "5em".  If  this value is "0pt" then
%      only the file name determines the width of the box.
%    
%      \item [\tt \char92 PredicateFileExtension]\ \\
%      Macro containing the   extension of the prolog  file.   This text is
%      typeset right after the file  name stored in "\PrologFILE". The
%      default is empty.
%    \end{description}
%    
%    \begin{figure}[t]
%    {\dimen255=\textwidth\advance\dimen255 by-1mm\divide\dimen255 150
%    \setlength{\unitlength}{\dimen255}
%    \begin{picture}(150,52)
%      \linethickness{.1pt}
%      \put(  0, 0){\line(0,1){8}}
%      \put(  0, 8){\line(1,0){150}}
%      \put(150, 0){\line(0,1){8}}
%      \put(  0, 0){\makebox(150,8){\bf Succeding Text}}
%      \put( 75,12){\vector(0,1){4}}
%      \put( 75,12){\vector(0,-1){4}}
%      \put( 77,12){\makebox(0,0)[l]{\scriptsize\tt \char92 PredicateSkip \char92 par }}
%      {\thicklines\put(  0,16){\framebox(110,20){\bf Predicate Description}}}
%      \put(130,25){\framebox(20,4){\bf File}}
%      \put(150,35){\makebox(0,0)[r]{\parbox[r]{60mm}{\raggedleft\scriptsize\tt
%      \char92 PredicateFileFont\\%
%      \char92 PrologFile\\%
%      \char92 PredicateFileExtension}}}
%      \put(1,17){%
%      \begin{picture}(0,0)
%        \put( 10, 2){\vector(1,0){10}}
%        \put( 10, 2){\vector(-1,0){10}}
%        \put( -1,-3){\makebox(0,0)[l]{\scriptsize\tt\char92 PredicateIndent}}
%        \put( 20, 0){\line(1,0){87}}
%        \put( 20, 0){\line(0,1){12}}
%        \put(  0,12){\line(0,1){ 6}}
%        \put(  0,12){\line(1,0){20}}
%        \put(  0,18){\line(1,0){107}}
%        \put(107, 0){\line(0,1){18}}
%        \put(  2,16){\makebox(0,0)[l]{\scriptsize\tt \char92 PredicateFont}}
%      \end{picture}}
%      \put(130,18){\vector(1,0){20}}
%      \put(130,18){\vector(-1,0){20}}
%      \put(130,16){\makebox(0,0){\scriptsize\tt \char92 PredicateFileIndent}}
%      
%      \put(112,24){\vector(1,0){2}}
%      \put(112,24){\vector(-1,0){2}}
%      \put(112,22){\makebox(0,0)[l]{\scriptsize\tt \char92 PredicateFileSep}}
%      
%      \put(  0,44){\line(0,1){8}}
%      \put(  0,44){\line(1,0){150}}
%      \put(150,44){\line(0,1){8}}
%      \put(  0,44){\makebox(150,8){\bf Preceding Text}}
%      \put( 75,40){\vector(0,1){4}}
%      \put( 75,40){\vector(0,-1){4}}
%      \put( 77,40){\makebox(0,0)[l]{\scriptsize\tt \char92 PredicateSkip \char92 par }}
%    \end{picture}
%    }
%    \caption{The {\tt \char92 Predicate} command}
%    \end{figure}
%    
%    \def\PrologFILE{prolog}
%    
%    \noindent
%    "\Predicate foo_bar/6(Argument1, Argument2, Argument3,"\\
%    "                  Argument4, Argument5, Argument6)."
%
%    \Predicate foo_bar/6(Argument1, Argument2, Argument3,
%                      Argument4, Argument5, Argument6).
%    \def\PrologFILE{very\_Long\_Prolog\_File}
%    \Predicate foo_bar/6(Argument1, Argument2, Argument3,
%                      Argument4, Argument5, Argument6).
%    
%    \noindent
%    "\Predicate this_is_a_very_long_predicate/5("\\
%    "    Argument1, Argument2, Argument3, Argument4, Argument5)."
%
%    \def\PrologFILE{prolog}
%    \Predicate this_is_a_very_long_predicate/5(
%        Argument1, Argument2, Argument3, Argument4, Argument5).
%    
%    
%    \subsection{The Underscore}
%    
%    One thing which occurs very often  in program listings is the underscore
%    "_".   The problem arises that \LaTeX\  uses the underscore only in
%    math mode  to denote subscripts.   For the comands  described above the
%    "_" can be  simply  used as  is.   Beware, don't expect  math  mode
%    subscript to work there.
%    
%    The macro "\WithUnderscore" is provided by pl to
%    execute some commands where the underscore does have the meaning as
%    plain character. 
%    
%    Example:
%    
%    It can be highly desirable to protect the index. Otherwise any
%    indexed predicate containing an underscore would wrack \LaTeX. This
%    can be done with a construction like the following one:
%    
%    "\WithUnderscore{\printindex}"
%    
%    
%    \subsection{Inline Code}
%    The style  option  {\tt idtt} allows    to typeset some   text using the
%    teletype  font ("\tt").   The text  has simply to  be enclosed in "|".
%    
%    The same effect can be achieved with the command
%    "\MakeShortVerb" defined in {\sf doc.sty}. To use this you
%    have to add the style option {\tt doc} and place the following
%    command in the preamble:
%    
%    "\MakeShortVerb{|}"
%    
%    Example:
%    
%    You type "|proc_1|" and you get {\tt proc\_1}.
%    
%    
%    \section*{Bugs and Problems}
%    
%    
%    \begin{itemize}
%      \item The bugs and problems of earlier releases have been corrected.
%      \item The documentation needs polishing.
%    \end{itemize}
% 
%    
%    \newpage
%    \section*{A Sample}
%    
%    
%    {\catcode`\%=14 \Listing{sample.pl}}
%    \newpage
%    \PrologInput{sample.pl}
%
%
% ^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%   \StopEventually{}
% ^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%    \newpage
% 
%    \section{The Implementation}
%
%    \begin{macrocode}
\ifx\documentclass\relax \else
  \ProvidesPackage{pl}[\filedate\space gene (\fileversion)]
\fi
%    \end{macrocode}
%
%    \subsection{Options and Defaults}
% 
%    First of all we define the macros containing the default values for
%    certain options. The user may redefine them with "\renewcommand" to
%    adapt them to the personal preferences.
%
%    \begin{macrocode}
\def\PrologFont{\small\tt}
%    \end{macrocode}
%    The macro "\PrologFont" contains the font changing command executed
%    to typeset the Prolog code in the verbatim-like environment.
%
%    \begin{macrocode}
\def\PrologIndent{2em}
%    \end{macrocode}
%    The macro "\PrologIndent" contains the indentation of the Prolog
%    code in the verbatim-like environment.
%
%    \begin{macrocode}
\def\PrologNumberFont{\tiny\rm}
%    \end{macrocode}
%    The macro "\PrologNumberFont" contains the font changing command
%    used to typeset the line numbers (if enabled) in the verbatim-like
%    environment.
%
%    \begin{macrocode}
\def\PrologRuleWidth{0pt}
%    \end{macrocode}
%    The macro "\PrologRuleWidth" contains the width of the rule
%    seperating Prolog code and text.
%
%    \begin{macrocode}
\def\PrologListFont{\small\tt}
%    \end{macrocode}
%    The macro "\PrologListFont" contains the font changing command
%    to typeset a Prolog list (exports).
%
%    \begin{macrocode}
\def\PrologListIndent{2em}
%    \end{macrocode}
%    The macro "\PrologListIndent" contains the indentation for a Prolog
%    list (exports).
%
%    \begin{macrocode}
\def\PrologModule#1#2{\section{The Module {\tt #1}}}
%    \end{macrocode}
%    The macro "\PrologModule" contains the command which is called at
%    the beginning of a module. The first argument is the name of the
%    module. The second argument is the list of exports.
%
%    This macro is supposed to be redefined by the user with
%    "\renewcommand". 
%
%    \begin{macrocode}
\def\PrologFile#1#2{\section{The File {\tt #1}}}
%    \end{macrocode}
%    The macro "\PrologFile" contains the command which is called at
%    the beginning of a non-module Prolog file. The first argument is the name
%    of the module. The second argument is usually empty.
%
%    This macro is supposed to be redefined by the user with
%    "\renewcommand". 
%
%    \begin{macrocode}
\def\PredicateFont{\tt}
%    \end{macrocode}
%    The macro "\PredicateFont" contains the font switching command
%    used in "\Predicate" for the body of the predicate description.
%
%    \begin{macrocode}
\def\PredicateFileFont{\small\sf}
%    \end{macrocode}
%    The macro "\PredicateFileFont" contains the font switching command
%    used in "\Predicate" for the file name
%
%    \begin{macrocode}
\def\PredicateSkip{\smallskip}
%    \end{macrocode}
%    The macro "\PredicateSkip" contains the skip command executed before
%    and after "\Predicate".
%
%    \begin{macrocode}
\def\PredicateIndent{5em}
%    \end{macrocode}
%    The macro "\PredicateIndent" contains length of the
%    maximal indentation in the macro "\Predicate".
%
%    \begin{macrocode}
\def\PredicateFileExtension{}
%    \end{macrocode}
%    The macro "\PredicateFileExtension" contains the text appended to
%    file name in the "\Predicate" command.
%
%    \begin{macrocode}
\def\PredicateFileWidth{5em}
%    \end{macrocode}
%    The macro "\PredicateFileWidth" contains the minimum width of the
%    file name in the "\Predicate" command. Shorter file names are padded
%    to this length.
%
%    \begin{macrocode}
\def\PredicateFileSep{1em}
%    \end{macrocode}
%    The macro "\PredicateFileSep" contains the width of the
%    separating space between the predicate description and the file name.
%
%    \begin{macrocode}
\def\PredicateBoxSep{3pt}
%    \end{macrocode}
%    The macro "\PredicateBoxSep" contains the amount of space between
%    the box and contents in the "\Predicate" command. This is similar to
%    "\fboxsep" in \LaTeX.
%
%    \begin{macrocode}
\def\PredicateBoxRule{0.5pt}
%    \end{macrocode}
%    The macro "\PredicateBoxRule" contains the line thickness of box in
%    the "\Predicate" command. This is similar to "\fboxrule" in
%    \LaTeX. 
%
%    \begin{macrocode}
\def\PredicateIndex#1{\index{#1}}
%    \end{macrocode}
%    The macro "\PredicateIndex" contains the command which is called to
%    put a predicate into an index. The argument is the string to index.
%
%    This macro may be redefined by the user with "\renewcommand". 
%
%    \begin{macrocode}
\newif\ifPrologNumberLines
%    \end{macrocode}
%    switch to enable line numbering
%
%
%
%    \subsection{Internals}
% 
%    \begin{macrocode}
\def\PrologEXPORTS{}
%    \end{macrocode}
%    The macro "\PrologEXPORTS" contains the current list of exports.
%
%    \begin{macrocode}
\def\PrologFILE{}
%    \end{macrocode}
%    The macro "\PrologFILE" contains the current module or file
%    name. This is not supposed to be set by the user. Nevertheless
%    there might be occasions where this is neccesary (e.g. in the
%    documentation of this style option).
%
%
%    \subsection{Configuration Commands}
%    The different Prolog dialects have different ways to declare
%    modules. Thus pl needs to know which dialect is currently used. This
%    influences how "PrologInput" handles the first Prolog clause.
%
%    \begin{macrocode}
\def\PrologDialect#1{%
  \@ifundefined{PL@start@module@#1}%
                {\message{*** Prolog dialect #1 is undefined. Ignored.}}%
                {\gdef\PL@Dialect{#1}}}
\def\PL@Dialect{eclipse}
%    \end{macrocode}
%    The command "\PrologDialect" can be used to declare the Prolog
%    dialect used. The value is stored in the macro "\PL@Dialect" for
%    later use. This is only done if an appropriate macro to handle a module
%    are defined.
%
%
%    \begin{macrocode}
\gdef\PL@@delayed{}
%    \end{macrocode}
%    Keep some characters which were read in advance.
%
%
%
%    \begin{macrocode}
\newcount\PL@line
%    \end{macrocode}
%    We allocate a new counter for the line number of Prolog code (if
%    enabled).
%
%
%
%    \subsection{Typesetting Prolog Code}
%
%    Prolog code is typeset is a verbatim-like way. For this purpose a
%    modified version of the verbatim environment from the \TeX\ book is
%    used. For an explanation see pages 380--382 in the \TeX\ book.
%
%    \begin{macrocode}
\gdef\PL@code@setup{\PrologFont\parskip=0ex\parindent=0pt
  \ifx\PL@@delayed\empty\else%
    \parbox{\PrologIndent}{%
      \ifPrologNumberLines \PrologNumberFont \the\PL@line%
      \global\advance\PL@line1
      \else\ \fi}\PL@@delayed%
    \gdef\PL@@delayed{}\par
  \fi%
  \def\par{\leavevmode\egroup\box0\endgraf}
  \def\do##1{\catcode`##1=12 }\dospecials
  \obeyspaces
  \obeylines
%  \catcode`\`=\other
  \catcode`\^^I=13
  \everypar{\parbox{\PrologIndent}{%
      \ifPrologNumberLines \PrologNumberFont \the\PL@line%
      \global\advance\PL@line1
      \fi
      \hfill}\PL@code@startbox}}
%    \end{macrocode}
% 
%
%    \begin{macrocode}
\def\PL@code@startbox{\setbox0=\hbox\bgroup}
%    \end{macrocode}
% 
%
%    \begin{macrocode}
{\catcode`\^^I=13
 \gdef^^I{\leavevmode\egroup
   \dimen0=\wd0 % the width so far, or since the previous tab
   \setbox1=\hbox{\PrologFont\space}\dimen1=8\wd1
   \divide\dimen0   by\dimen1
   \multiply\dimen0 by\dimen1 % compute previous multiple of tab
   \advance\dimen0  by\dimen1 % advance to next multiple of tab
   \wd0=\dimen0 \box0 \PL@code@startbox}%
}
{\obeyspaces\global\let =\ }
%    \end{macrocode}
% 
%
%    \begin{macrocode}
\def\PL*/{\PL@PL@init%
  \begingroup
  \PL@code@setup
  \PL@doPL}
%    \end{macrocode}
% 
% 
%    "|" is temporary escape character to catch the end "/*PL"
%    \begin{macrocode}
{\catcode`\|=0 \catcode`\\=12
  |obeylines|gdef|PL@doPL^^M#1/*PL{#1|endgroup|PL@PL@exit}}
%    \end{macrocode}
% 
%
%    Initialization macro
%    \begin{macrocode}
\def\PL@PL@init{%
        \ifdim\PrologRuleWidth>0pt%
          \par\noindent\rule{\textwidth}{\PrologRuleWidth}\par%
        \else\medskip\par\fi}
%    \end{macrocode}
%
%
%
%    \begin{macrocode}
\def\PL@PL@exit{%
        \ifdim\PrologRuleWidth>0pt%
          \vspace{-2ex}\noindent\rule{\textwidth}{\PrologRuleWidth}\par%
        \else\smallskip\par\fi}
%    \end{macrocode}
%
%
%
%
%    Dirty hack.
%    make : active to catch :-
%    use a group to hide the changes
%    \begin{macrocode}
\def\PL@INIT{\begingroup\catcode`:=13\catcode`/=13}
%    \end{macrocode}
%
%
%
%    \begin{macrocode}
\def\PL@EXIT{\endgroup}
%    \end{macrocode}
%
%
%
%    we make : active and include the file
%    \begin{macrocode}
\gdef\PrologInput{%
  \begingroup
  \catcode`\_=12
  \PL@Input
}
%    \end{macrocode}
%
%
%    \begin{macrocode}
\PL@INIT
\gdef\PL@Input#1{%
  \gdef\PrologFILE{#1}%
  \gdef\PrologMODULE{}%
  \gdef\PrologEXPORTS{}%
  \global\PL@line=1%
  \endgroup
  \PL@INIT%
  \let:=\PL@COLON
  \let/=\PL@SLASH
  \input{#1}%
  \gdef\PrologFILE{}%
  \gdef\PrologMODULE{}%
  \gdef\PrologEXPORTS{}%
  }
\PL@EXIT
%    \end{macrocode}
%
%
%
%    \subsection{End a File of Prolog Code}
% 
%    At the end of a file there is a "*/" which terminates the last
%    comment for Prolog. Those two characters are stripped away by the macro
%    "\EndProlog".
%
%    \begin{macrocode}
\def\EndProlog#1*/{}
%    \end{macrocode}
%
%
%
%    \subsection{Definition for Various File Types}
%
%    \subsubsection{Defininitions for Non-Module Files}
%
%    A file can start with "/*". This case is handled by making the
%    "/" active and binding it to the command "\PL@SLASH". This
%    command checks if the next character is a "*". In this case the
%    catcodes of "/" and ":" can be restored to their defaults. This
%    is done by "\PL@EXIT".
% 
%    Finally the underscore "_" is made active and
%    "\PL@start@star" is called to do the rest.
%
%    \begin{macrocode}
\def\PL@SLASH{\@ifnextchar*{%
    \PL@EXIT
    \PL@US@start
    \PL@SLASH@STAR}{/}}
%    \end{macrocode}
%
%
%
%
%
%    \begin{macrocode}
\def\PL@SLASH@STAR*{%
  \PrologFile{\PrologFILE}{}%
  \PL@US@end}
%    \end{macrocode}
%
%
%
% 
%
%
%    \begin{macrocode}
\def\PL@COLON{\@ifnextchar-{\PL@goal}{: }}
%    \end{macrocode}
%
%
%
%    \begin{macrocode}
\def\PL@goal-{%
  \PL@EXIT
  \PL@US@start
  \@ifnextchar m{\csname PL@start@module@\PL@Dialect\endcsname}%
  {\@ifnextchar t{\PL@start@true}%
    {\csname PL@start@file@\PL@Dialect\endcsname}}}
%    \end{macrocode}
%
%
%    \begin{macrocode}
\def\PL@start@true true. /*{%
  \PrologFile{\PrologFILE}{}%
  \PL@US@end}
%    \end{macrocode}
%
%
%
%
%
%
%    \subsubsection{Defininitions for ECLiPSe-Prolog}
%
%    The beginning of a module file in eclipse can be in one of the following
%    forms:
%
%    \begin{description}
%    \item[:- module\_interface({\em Module})] 
%    \item[:- module({\em Module})] 
%    \end{description}
%
%    We strip away the actual predicate name getting the rest in the macro
%    parameter \#1. The complete module declaration is stored in the macro
%    "\PL@delayed" to be inserted later.
%    \begin{macrocode}
\def\PL@start@module@eclipse module#1(#2). /*{%
  \global\PL@line=1
  \gdef\PL@@delayed{:- module#1(#2).}
  \gdef\PrologMODULE{#2}%
  \catcode`\,=13 %
  \PrologModule{\PrologFILE}{}%
  \PL@US@end}
%    \end{macrocode}
%
%
%
%    \subsubsection{Definitions for Quintus-Prolog}
%
%    The beginning of a module file in Quintus is in the following form:
%
%    \begin{description}
%    \item[:- module({\em Module},{\em Exports})] \ 
%    \end{description}
%
%
%    \begin{macrocode}
\def\PL@start@module@quintus module(#1,{%
  \global\PL@line=1
  \gdef\PrologFILE{#1}%
  \catcode`\,=13 %
  \PL@start@module@quintus@}
%    \end{macrocode}
%
%
%
%    \begin{macrocode}
\def\PL@start@module@quintus@[#1]). /*{%
  \gdef\PrologEXPORTS{#1}%
  \PrologModule{\PrologFILE}{#1}%
  \PL@US@end}
%    \end{macrocode}
%
%    \subsubsection{Definitions for C-Prolog}
%
%    I don't know if C-Prolog has a module system nowadays. The last time I
%    checked it had none. If nobody has a better idea I use Quintus Prolog
%    syntax in this case even it does not make any sense.
%
%    \begin{macrocode}
\let\PL@start@module@cprolog=\PL@start@module@quintus
%    \end{macrocode}
%
%    \subsubsection{Definitions for Sixtus-Prolog}
%
%    I don't know what's used in Sixtus-Prolog. So I use the same value as for
%    eclipse.
%
%    \begin{macrocode}
\let\PL@start@module@sixtus=\PL@start@module@eclipse
%    \end{macrocode}
%
%    \subsubsection{Definitions for SWI-Prolog}
%
%    Fortunately the module system of SWI-Prolog is compatible with the module
%    system of Quintus Prolog. So we just use the definition here again.
%
%    \begin{macrocode}
\let\PL@start@module@swiprolog=\PL@start@module@quintus
%    \end{macrocode}
%
%    \subsubsection{Definitions for SB-Prolog}
%
%    I don't know if C-Prolog has a module system nowadays. The last time I
%    checked it had none. If nobody has a better idea I use Quintus Prolog
%    syntax in this case even it does not make any sense.
%
%    \begin{macrocode}
\let\PL@start@module@sbprolog=\PL@start@module@quintus
%    \end{macrocode}
%
%    \subsubsection{Definitions for bin-Prolog}
%
%    I don't know what's used in bin-Prolog. So I use the same value as for
%    eclipse.
%
%    \begin{macrocode}
\let\PL@start@module@binprolog=\PL@start@module@eclipse
%    \end{macrocode}
%
%
%
%
%    \subsection{Typeset a Boxed Predicate Description}
%
%    The first step is to protect the underscores in the predicate names and
%    the arguments.
%
%
%    \begin{macrocode}
\def\Predicate{\PL@US@start\Predicate@}
%    \end{macrocode}
%
%    The syntax is oriented towards Prolog syntax. The name and the arity of
%    the predicate may not contain "/" or "(". 
%
%    \begin{macrocode}
\def\Predicate@#1/#2(#3).{%
  \PredicateSkip\par\noindent%
  {\setbox1=\hbox{\PredicateFileFont \PrologFILE\PredicateFileExtension}%
   \fboxrule=\PredicateBoxRule%
   \fboxsep=\PredicateBoxSep%
   \fbox{\PredicateIndex{#1/#2}%
         \dimen255=\wd1
         \ifdim\dimen255<\PredicateFileWidth \dimen255=\PredicateFileWidth \fi
         \dimen255=-\dimen255
         \advance\dimen255 by-\PredicateFileSep
         \advance\dimen255 by \textwidth
         \parbox{\dimen255}{\raggedright
                 \setbox0=\hbox{\normalsize\PredicateFont #1(}
                 \dimen254=\wd0
        
                 \ifdim\dimen254>\PredicateIndent \dimen254=\PredicateIndent\fi
                 \dimen253=\dimen255 \advance\dimen253 by -\dimen254
                 \parshape=2 0mm \dimen255 \dimen254 \dimen253
                 \normalsize\PredicateFont #1\ifx\@empty#3 \else(#3)\fi
        }}%
    \hfill \box1\PredicateSkip\par
  }\PL@US@end}
%    \end{macrocode}
%
%
%
%
%
%
%
%    \subsection{Typeset a List of Prolog Predicates}
% 
%
%    \begin{macrocode}
\def\PrologList{\par\noindent%
  \PL@US@start
  \PrologListFont
  \catcode`\,=13%
  \parindent=\PrologListIndent\parskip=0pt\par
  \PL@List}
%    \end{macrocode}
%
%
%
%    \begin{macrocode}
{\catcode`\,=13 
\gdef\PL@List[#1]{%
  \def,{\par}%
  #1
  \PL@US@end\par}
}
%    \end{macrocode}
%
%
%    \begin{macrocode}
\def\PrologListEXPORTS{\PrologList[\PrologEXPORTS]}
%    \end{macrocode}
%
%
%
%
%    \subsection{Special Treatment of the Underscore}
%
%    We define two macros to activate and deactivate the underscore
%    respectively. Those two macros have to come in pairs always. The first
%    one opens a group to protect the changes. The closing macro simply closes
%    the group, thus undoing the effects of the first macro.
%
%    \begin{macrocode}
\def\PL@US@start{\begingroup\catcode`\_=13 }
\def\PL@US@end{\endgroup }
%    \end{macrocode}
%
%
%
%    \begin{macrocode}
\def\WithUnderscore{\begingroup\catcode`\_=13 \With@Underscore}
\def\With@Underscore#1{#1\endgroup}
%    \end{macrocode}
%
%    \subsection{Misc}
%
%    A spin off product of this style file is a macro to include a file
%    verbosely. Such a macro is also provided by the verbatim package and
%    others. Nevertheless I have left it in. 
%
%    \begin{macrocode}
\def\Listing#1{\par\begingroup%
  \PL@line=1%
  \PL@code@setup%
  \input{#1}%
  \endgroup}
%    \end{macrocode}
%
%\iffalse
%</pl>
%<*pcode>
%\fi
%    \section{Backward Compatibility Mode: {\tt pcode.sty}}
%
%    For backward compatibility some macros are defined in a style file under
%    the old name {\tt pcode.sty}. The new style file has to be acessible
%    under the new name {\tt pl.sty}. This file is loaded before some macros
%    are defined.
%
%    \begin{macrocode}
\ifx\PrologFont\relax\else\input pl.sty\fi
%    \end{macrocode}
%
%    In former versions mainly the Prolog dialect Quintus has been
%    supported. Thus a boolean was enough to tell apart the dialects Quintus
%    and eclipse --- which came next. This is emulated with the next two
%    macros.
%
%    \begin{macrocode}
\def\PrologQuintustrue{\PrologDialect{quintus}}
\def\PrologQuintusfalse{\PrologDialect{eclipse}}
%    \end{macrocode}
%
%    The macro "\WithUnderscore" was named "\WithActiveUnderscore"
%    in a former version of {\tt pcode.sty}. The {\em Active} part of the name
%    was missleading for users. Thus it has been removed. The old name is made
%    an alias for the new one.
%
%    \begin{macrocode}
\let\WithActiveUnderscore=\WithUnderscore
%    \end{macrocode}
%
%    In an ancient version of {\tt pcode.sty} the macro "\EndProlog" was
%    named "\StopProlog". Thus we make an alias for the old name.
%
%    \begin{macrocode}
\let\StopProlog=\EndProlog
%    \end{macrocode}
%
%    Make "\PL@INIT" usable for the user as well. I don't know where
%    this might be used. It has been in the old version, so I put it into the
%    compatibility mode.
%
%    \begin{macrocode}
\let\PrologInit=\PL@INIT
%    \end{macrocode}
%
%\iffalse
%</pcode>
%\fi
%    \Finale
%
\endinput