summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/gene/pl/pl.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/gene/pl/pl.dtx')
-rw-r--r--macros/latex/contrib/gene/pl/pl.dtx1188
1 files changed, 1188 insertions, 0 deletions
diff --git a/macros/latex/contrib/gene/pl/pl.dtx b/macros/latex/contrib/gene/pl/pl.dtx
new file mode 100644
index 0000000000..a0960f3a53
--- /dev/null
+++ b/macros/latex/contrib/gene/pl/pl.dtx
@@ -0,0 +1,1188 @@
+% ^^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