% ^^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