Debian Codegraph @

texmf-dist/source/latex/plweb/pl.dtx

raw
1 % ^^A -*-LaTeX-*-
2 %\iffalse
3 %<*pl>
4 %\fi
5 \def\filename{pl.dtx}
6 \def\fileversion{3.2}
7 \def\filedate{2026-05-23}
8 \def\docversion{3.2}
9 \def\docdate{2026-05-23}
10 %\iffalse
11 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
12 \typeout{%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
13 %%
14 Prolog Documentation in LaTeX. Version \fileversion\@spaces gene \filedate
15 %%
16 %% Purpose:
17 %% Style option for LaTeX to provide routines to document Prolog programs.
18 %%
19 %% Documentation: see seperate LaTeX document `pl.tex'
20 %%
21 %% Author: Gerd Neugebauer
22 %% Brechklinge 10
23 %% 69256 Mauer (Germany)
24 %% Mail: [email protected]
25 %%
26 %% Copyright (C) 1995-2026 Gerd Neugebauer
27 %%
28 %% pl.dtx is distributed in the hope that it will be useful, but WITHOUT
29 %% ANY WARRANTY. No author or distributor accepts responsibility to
30 %% anyone for the consequences of using it or for whether it serves any
31 %% particular purpose or works at all, unless he says so in writing.
32 %%
33 %% Everyone is granted permission to copy, modify and redistribute pl.dtx,
34 %% provided this copyright notice is preserved and any modifications are
35 %% indicated.
36 %%
37 %%
38 %% This style is still under development and may be replaced with a new
39 %% version which provides an enhanced functionality. Any comments are
40 %% welcome but don't expect ANY help from my side.
41 %%
42 }
43 %\fi
44 %
45 % \title{Literate Programming:\\Prolog Documentation with \LaTeX}
46 % \author{Gerd Neugebauer\\
47 % Brechklinge 10\\
48 % 69256 Mauer (Germany)\\
49 % Net: {\tt [email protected]}}
50 %
51 % \date{{\footnotesize This document describes pl version \fileversion\
52 % as of \filedate.}}
53 %
54 % \maketitle
55 %
56 % ^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
57 %
58 % \DoNotIndex{\@ifnextchar,\box,\dimen,\divide,\newif,\noindent,\normalsize}
59 % \DoNotIndex{\obeyspaces,\other,\raggedright,\relax,\rule}
60 % \DoNotIndex{\sf,\smallskip,\textwidth,\tiny,\wd,\endgraf}
61 % \DoNotIndex{\empty,\fbox,\fboxrule,\fboxsep}
62 % \DoNotIndex{\ifdim,\medskip,\multiply,\message}
63 % \DoNotIndex{\par,\parbox,\parshape}
64 % \DoNotIndex{\@,\@@par,\@beginparpenalty,\@empty}
65 % \DoNotIndex{\@flushglue,\@gobble,\@input}
66 % \DoNotIndex{\@makefnmark,\@makeother,\@maketitle}
67 % \DoNotIndex{\@namedef,\@ne,\@spaces,\@tempa}
68 % \DoNotIndex{\@tempb,\@tempswafalse,\@tempswatrue}
69 % \DoNotIndex{\@thanks,\@thefnmark,\@topnum}
70 % \DoNotIndex{\@@,\@elt,\@forloop,\@fortmp,\@gtempa,\@totalleftmargin}
71 % \DoNotIndex{\",\/,\@ifundefined,\@nil,\@verbatim,\@vobeyspaces}
72 % \DoNotIndex{\|,\~,\ ,\ProvidesPackage}
73 % \DoNotIndex{\advance,\aftergroup,\begingroup,\bgroup}
74 % \DoNotIndex{\mathcal,\csname,\def,\documentclass,\documentstyle}
75 % \DoNotIndex{\dospecials,\edef,\egroup}
76 % \DoNotIndex{\else,\endcsname,\endgroup,\endinput,\endtrivlist}
77 % \DoNotIndex{\expandafter,\fi,\fnsymbol,\futurelet,\gdef,\global}
78 % \DoNotIndex{\hbox,\hss,\if,\if@inlabel,\if@tempswa,\if@twocolumn}
79 % \DoNotIndex{\ifcase}
80 % \DoNotIndex{\ifcat,\iffalse,\ifx,\ignorespaces,\index,\input,\item}
81 % \DoNotIndex{\jobname,\kern,\leavevmode,\leftskip,\let,\llap,\lower}
82 % \DoNotIndex{\m@ne,\next,\newpage,\nobreak,\noexpand,\nonfrenchspacing}
83 % \DoNotIndex{\obeylines,\or,\protect,\raggedleft,\rightskip,\rm,\sc}
84 % \DoNotIndex{\setbox,\setcounter,\small,\space,\string,\strut}
85 % \DoNotIndex{\strutbox}
86 % \DoNotIndex{\thefootnote,\thispagestyle,\topmargin,\trivlist,\tt}
87 % \DoNotIndex{\twocolumn,\typeout,\vss,\vtop,\xdef,\z@}
88 % \DoNotIndex{\,,\@bsphack,\@esphack,\@noligs,\@vobeyspaces,\@xverbatim}
89 % \DoNotIndex{\`,\catcode,\end,\escapechar,\frenchspacing,\glossary}
90 % \DoNotIndex{\hangindent,\hfil,\hfill,\hskip,\hspace,\ht,\it,\langle}
91 % \DoNotIndex{\leaders,\long,\makelabel,\marginpar,\markboth,\mathcode}
92 % \DoNotIndex{\mathsurround,\mbox,\newcount,\newdimen,\newskip}
93 % \DoNotIndex{\nopagebreak}
94 % \DoNotIndex{\parfillskip,\parindent,\parskip,\penalty,\raise,\rangle}
95 % \DoNotIndex{\section,\setlength,\TeX,\topsep,\underline,\unskip,\verb}
96 % \DoNotIndex{\vskip,\vspace,\widetilde,\\,\%,\@date,\@defpar}
97 % \DoNotIndex{\[,\{,\},\]}
98 % \DoNotIndex{\count@,\ifnum,\loop,\today,\uppercase,\uccode}
99 % \DoNotIndex{\baselineskip,\begin,\tw@}
100 % \DoNotIndex{\discretionary,\immediate,\makeatletter,\makeatother}
101 % \DoNotIndex{\repeat,\scriptsize,\selectfont,\the,\undefined}
102 % \DoNotIndex{\arabic,\do,\makeindex,\null,\number,\show,\write,\@ehc}
103 % \DoNotIndex{\@author,\@ehc,\@ifstar,\@sanitize,\@title,\everypar}
104 % \DoNotIndex{\if@minipage,\if@restonecol,\ifeof,\ifmmode}
105 % \DoNotIndex{\settowidth,\@resetonecoltrue,\@resetonecolfalse,\bf}
106 % \DoNotIndex{\clearpage,\closein,\lowercase,\@inlabelfalse}
107 % \DoNotIndex{\selectfont,\mathcode,\newmathalphabet,\rmdefault}
108 % \DoNotIndex{\bfdefault}
109 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
110 % \CheckSum{468}
111 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
112 %% \CharacterTable
113 %% {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
114 %% 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
115 %% Digits \0\1\2\3\4\5\6\7\8\9
116 %% Exclamation \! Double quote \" Hash (number) \#
117 %% Dollar \$ Percent \% Ampersand \&
118 %% Acute accent \' Left paren \( Right paren \)
119 %% Asterisk \* Plus \+ Comma \,
120 %% Minus \- Point \. Solidus \/
121 %% Colon \: Semicolon \; Less than \<
122 %% Equals \= Greater than \> Question mark \?
123 %% Commercial at \@ Left bracket \[ Backslash \\
124 %% Right bracket \] Circumflex \^ Underscore \_
125 %% Grave accent \` Left brace \{ Vertical bar \|
126 %% Right brace \} Tilde \~}
127 %%
128 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
129 %
130 % \setcounter{IndexColumns}{2}
131 % \def\PredicateIndex#1{}
132 % \MakeShortVerb{"}
133 %
134 % ^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
135 %
136 % \section*{Introduction}
137 %
138 % Inspired by the idea behind the web system I felt the need to
139 % have a system to write documented Prolog programs. But instead of
140 % having to transform the common source into program or
141 % documentation the central idea was to develop a method to have
142 % one common source which can be interpreted by a
143 % Prolog\footnote{C-Prolog, Quintus-Prolog, or ECLiPSe at that
144 % time.} system as well as by \LaTeX. To achieve this goal the
145 % \LaTeX\ commands are hidden from Prolog by enclosing them in
146 % comments.
147 %
148 % The C-Prolog allows two kinds of comments. The first kind starts
149 % with a "%" and ends at the end of the line. This is also a comment
150 % for \LaTeX. The other Prolog comment starts with "/*" and ends
151 % with "*/". This seemed to be the right way to hide the \LaTeX\
152 % documentation commands from the Prolog interpreter.
153 %
154 % The only problem was to define a starting sequence to open the
155 % first comment. This sequence must be an executable Prolog
156 % command as well as a valid \LaTeX{} command. The first approach
157 % was to modify both --- the Prolog program and the \LaTeX\ style
158 % --- to find a common statement. The pre 2.0 versions of the pl
159 % style option took this decision. One problem came up when the
160 % author tried to incorporate the module system of Prolog. This
161 % system requires that the first statement in a module is the
162 % declaration of the module name possibly together with the list of
163 % predicates to be exported. This restriction led to the approach
164 % taken in version 2.0 and later. In modules nearly no change has
165 % to be made. The module declaration is defined as a valid \LaTeX\
166 % macro.
167 %
168 %
169 % \section{The \LaTeX\ Documentation Driver File}
170 %
171 % The \LaTeX\ main file ties together the whole documentation. This
172 % file should contain the "\documentclass" command together with
173 % the appropriate "\usepackage" or the "\documentsyle" command with
174 % the style option "pl".\smallskip
175 %
176 % \noindent
177 % \unitlength=\textwidth\advance\unitlength-65mm
178 % \begin{minipage}{\unitlength}
179 % \indent The only special command which is required in this file is the
180 % command "\PrologInput". This command inserts the Prolog file
181 % given as argument at the current position. The formatting
182 % directives described below are activated.
183 %
184 % The command "\PrologInput" may occur several times in this main
185 % file. It may be mixed with simple input or include
186 % commands. "\PrologInput" can be used nested, as long as the
187 % other requirements described in this document are fulfilled.
188 % \end{minipage}
189 % \hfill
190 % \begin{minipage}{58mm}
191 % {\small%
192 % "\documentclass[...]{...}"\\
193 % "\usepackage{pl}"\\
194 % "\begin{document}"\\
195 % "..."\\
196 % "\PrologInput{file1.pl}"\\
197 % "\PrologInput{file2.pl}"\\
198 % "..."\\
199 % "\PrologInput{filen.pl}"\\
200 % "..."\\
201 % "\end{document}"}
202 % \end{minipage}\smallskip
203 %
204 %
205 % The commands meant for the Prolog files can also be used in a plain
206 % \LaTeX{} context. Nevertheless those commands have been developed
207 % with the application of documenting Prolog in mind. The contents of
208 % the Prolog files and the additional macros provided by pl will
209 % be described in the next sections.
210 %
211 %
212 %
213 % \section{The Prolog Files}
214 %
215 % \subsection{Starting Modules}
216 %
217 % Prolog files can come in two variants: either it is a Prolog
218 % module or a plain Prolog file. Modules are distinguished from
219 % files by a specific first Prolog statement. This module
220 % declaration can have the form\footnote{e.g. in Quintus-Prolog}
221 %
222 % {\it ":- module(" Name"," Exports ")."}
223 %
224 % Alternatively it may have the form
225 %
226 % {\it ":- module_interface(" Name ")."}
227 %
228 % These module declarations have to be the first Prolog instructions in
229 % the file.
230 %
231 % In addition to those Prolog instructions we need to use the rule
232 % that the terminating point (.) of the module declaration is
233 % followed immediately by \verb*+ /*+. Note the single space which is
234 % necessary for the Prolog parser to work properly.
235 %
236 % Thus a Prolog module documented with pl starts e.g. with
237 %
238 % {\it ":- module\_interface(" Name "). /*"}
239 %
240 % Before this line there should be only Prolog comments starting with
241 % "%". These comments are also ignored by \TeX. Thus they do
242 % neither appear in the documentation nor are the evaluated by Prolog.
243 %
244 %
245 % \subsection{Starting Plain Files}
246 %
247 % Plain Prolog files are those files not starting with a module
248 % declaration. For technical reasons plain files can not start with code
249 % directly but requires a C-style comment at the beginning. The contents
250 % of this comment is typeset by \LaTeX.
251 %
252 % In general this restriction seems to be too hard. It is always a good
253 % idea to start a file with some general remarks and comments.
254 %
255 %
256 %
257 % \subsection{Ending Prolog Files}
258 %
259 % The Prolog file should end with
260 %
261 % "\EndProlog*/"
262 %
263 % From the Prolog point of view the file consists now of the declaration
264 % of a module (or a dummy predicate). The rest is purely comment. From the
265 % \LaTeX\ point of view it contains two macros and nothing in
266 % between. Thus everything in between will be interpreted as \LaTeX\ input
267 % only.
268 %
269 % \subsection{Prolog Code}
270 %
271 % To include additional Prolog statements in this file enclose them in
272 %
273 % "\PL*/"
274 %
275 % "/*PL"
276 %
277 % This forces the Prolog system to interpret the code, and the \LaTeX\
278 % system to typeset it in a verbatim-like environment.
279 %
280 % The Prolog code may contain every characters except the string
281 % "/*PL". For some reasons which are opaque to me spaces at the
282 % beginning of a line of Prolog code are ignored. To force proper
283 % indentation you should use {\sc tab} characters at the beginning of the
284 % line.
285 %
286 %
287 % \subsection*{Options for the Code Layout}
288 %
289 % The options are implemented as macros. To change them use
290 % "\renewcommand".
291 %
292 % \begin{description}
293 % \item [\tt \char92 PrologModule]\ \\
294 % Macro to typeset the module definition. In general this may be a
295 % sectioning command producing an appropriate title. It takes two
296 % arguments --- the two arguments of the "module" declaration.
297 %
298 % The default is "\section{{\tt #1}}"
299 % \item [\tt \char92 PrologFile]\ \\
300 % Same as above but for non module files.
301 %
302 % The default is "\section{{\tt #1}}"
303 % \item [\tt \char92 PrologFont]\ \\
304 % Macro to select the font used for printing the listing part. This
305 % should be a non-pro\-portional font. The default is
306 % "\small\tt".
307 %
308 % \item [\tt \char92 PrologListFont]\ \\
309 % Macro to select the font used for printing the export list. The
310 % default is "\small\tt".
311 %
312 % \item [\tt \char92 PrologListIndent]\ \\
313 % Macro to select the indentation of the export list. This should be a
314 % length. The default is "2em".
315 %
316 % \item [\tt \char92 PrologRuleWidth]\ \\
317 % Macro to select the width of the rule to separate Prolog code from
318 % text. This should be a length. The default is "0pt".
319 %
320 % \item [\tt \char92 PrologNumberFont]\ \\
321 % Font to be used when typesetting line numbers.
322 % \end{description}
323 %
324 % The following flags can be set by simply including the commands in
325 % the \LaTeX{} part of the document. Since they are mainly of a
326 % global nature the preamble of the driver file would be a good place
327 % for them.
328 %
329 % \begin{description}
330 % \item [\tt \char92 PrologNumberLinestrue]\ \\
331 % Turn on line numbering.
332 % \item [\tt \char92 PrologNumberLinesfalse]\ \\
333 % Turn off line numbering.
334 %
335 % \item [\tt \char92 PrologDialect\char251{\em Dialect}\char253]\ \\
336 % Declare the dialect of the used Prolog. This is mainly important to
337 % make the syntax of the modules known to pl. {\em Dialect}\/ can
338 % take one of the following values: {\tt eclipse}, {\tt quintus}, {\tt
339 % sixtus}, {\tt cprolog}, {\tt swiprolog}, {\tt sbprolog}, or {\tt
340 % binprolog}.
341 % \end{description}
342 %
343 % \section{Predicate Templates}
344 %
345 % Predicate templates provide a nice way to typeset a predicate
346 % head with some additional information. A usual predicate is
347 % characterized by the name/arity, arguments and the file it can be
348 % found in. Two boxes are used to contain this information. The
349 % right one contains the file name; The left one contains the
350 % predicate description. The box for the file name has a default
351 % width which will be enlarged if the file name doesn't fit into
352 % it. The predicate description if surrounded by a frame and
353 % formatted in the following way. If the predicate description fits
354 % in one line then it is typeset in one line. Otherwise the second
355 % and following lines are indented. This indentation tries to align
356 % beneath the first argument. If the predicate name is very long
357 % this might not be desirable. Thus the indentation has a maximal
358 % value which will not be exceeded.
359 %
360 % The \LaTeX\ part of the file contains the following template
361 %
362 % "\Predicate pred/1(arg)."
363 %
364 % Note that the ")." have {\em no}\/ space in between.
365 %
366 % \subsection*{Options}
367 %
368 % The options are implemented as macros. To change them use
369 % "\renewcommand".
370 %
371 % \begin{description}
372 % \item [\tt \char92 PredicateFont]\ \\
373 % Macro containing the font changing command for the predicate
374 % description. The default is "\normalsize\tt".
375 %
376 % \item [\tt \char92 PredicateSkip]\ \\
377 % Macro containing the spacing before and after the predicate
378 % description. The default is "\smallskip".
379 %
380 % \item [\tt \char92 PredicateIndent]\ \\
381 % Macro containing the maximal length of the indentation of the
382 % predicate description. The default is "5em". If this value
383 % is very large then the arguments are always aligned beneath the
384 % first one.
385 %
386 % \item [\tt \char92 PredicateFileFont]\ \\
387 % Macro containing the font changing command for the file name. The
388 % default is "\small\sf".
389 %
390 % \item [\tt \char92 PredicateFileWidth]\ \\
391 % Macro containing the minimal width of the box containing the file
392 % name. The default is "5em". If this value is "0pt" then
393 % only the file name determines the width of the box.
394 %
395 % \item [\tt \char92 PredicateFileExtension]\ \\
396 % Macro containing the extension of the prolog file. This text is
397 % typeset right after the file name stored in "\PrologFILE". The
398 % default is empty.
399 % \end{description}
400 %
401 % \begin{figure}[t]
402 % {\dimen255=\textwidth\advance\dimen255 by-1mm\divide\dimen255 150
403 % \setlength{\unitlength}{\dimen255}
404 % \begin{picture}(150,52)
405 % \linethickness{.1pt}
406 % \put( 0, 0){\line(0,1){8}}
407 % \put( 0, 8){\line(1,0){150}}
408 % \put(150, 0){\line(0,1){8}}
409 % \put( 0, 0){\makebox(150,8){\bf Succeding Text}}
410 % \put( 75,12){\vector(0,1){4}}
411 % \put( 75,12){\vector(0,-1){4}}
412 % \put( 77,12){\makebox(0,0)[l]{\scriptsize\tt \char92 PredicateSkip \char92 par }}
413 % {\thicklines\put( 0,16){\framebox(110,20){\bf Predicate Description}}}
414 % \put(130,25){\framebox(20,4){\bf File}}
415 % \put(150,35){\makebox(0,0)[r]{\parbox[r]{60mm}{\raggedleft\scriptsize\tt
416 % \char92 PredicateFileFont\\%
417 % \char92 PrologFile\\%
418 % \char92 PredicateFileExtension}}}
419 % \put(1,17){%
420 % \begin{picture}(0,0)
421 % \put( 10, 2){\vector(1,0){10}}
422 % \put( 10, 2){\vector(-1,0){10}}
423 % \put( -1,-3){\makebox(0,0)[l]{\scriptsize\tt\char92 PredicateIndent}}
424 % \put( 20, 0){\line(1,0){87}}
425 % \put( 20, 0){\line(0,1){12}}
426 % \put( 0,12){\line(0,1){ 6}}
427 % \put( 0,12){\line(1,0){20}}
428 % \put( 0,18){\line(1,0){107}}
429 % \put(107, 0){\line(0,1){18}}
430 % \put( 2,16){\makebox(0,0)[l]{\scriptsize\tt \char92 PredicateFont}}
431 % \end{picture}}
432 % \put(130,18){\vector(1,0){20}}
433 % \put(130,18){\vector(-1,0){20}}
434 % \put(130,16){\makebox(0,0){\scriptsize\tt \char92 PredicateFileIndent}}
435 %
436 % \put(112,24){\vector(1,0){2}}
437 % \put(112,24){\vector(-1,0){2}}
438 % \put(112,22){\makebox(0,0)[l]{\scriptsize\tt \char92 PredicateFileSep}}
439 %
440 % \put( 0,44){\line(0,1){8}}
441 % \put( 0,44){\line(1,0){150}}
442 % \put(150,44){\line(0,1){8}}
443 % \put( 0,44){\makebox(150,8){\bf Preceding Text}}
444 % \put( 75,40){\vector(0,1){4}}
445 % \put( 75,40){\vector(0,-1){4}}
446 % \put( 77,40){\makebox(0,0)[l]{\scriptsize\tt \char92 PredicateSkip \char92 par }}
447 % \end{picture}
448 % }
449 % \caption{The {\tt \char92 Predicate} command}
450 % \end{figure}
451 %
452 % \def\PrologFILE{prolog}
453 %
454 % \noindent
455 % "\Predicate foo_bar/6(Argument1, Argument2, Argument3,"\\
456 % " Argument4, Argument5, Argument6)."
457 %
458 % \Predicate foo_bar/6(Argument1, Argument2, Argument3,
459 % Argument4, Argument5, Argument6).
460 % \def\PrologFILE{very\_Long\_Prolog\_File}
461 % \Predicate foo_bar/6(Argument1, Argument2, Argument3,
462 % Argument4, Argument5, Argument6).
463 %
464 % \noindent
465 % "\Predicate this_is_a_very_long_predicate/5("\\
466 % " Argument1, Argument2, Argument3, Argument4, Argument5)."
467 %
468 % \def\PrologFILE{prolog}
469 % \Predicate this_is_a_very_long_predicate/5(
470 % Argument1, Argument2, Argument3, Argument4, Argument5).
471 %
472 %
473 % \subsection{The Underscore}
474 %
475 % One thing which occurs very often in program listings is the underscore
476 % "_". The problem arises that \LaTeX\ uses the underscore only in
477 % math mode to denote subscripts. For the comands described above the
478 % "_" can be simply used as is. Beware, don't expect math mode
479 % subscript to work there.
480 %
481 % The macro "\WithUnderscore" is provided by pl to
482 % execute some commands where the underscore does have the meaning of a
483 % plain character.
484 %
485 % Example:
486 %
487 % It can be highly desirable to protect the index. Otherwise any
488 % indexed predicate containing an underscore would wrack \LaTeX. This
489 % can be done with a construction like the following one:
490 %
491 % "\WithUnderscore{\printindex}"
492 %
493 %
494 % \subsection{Inline Code}
495 % The style option {\tt idtt} allows to typeset some text using the
496 % teletype font ("\tt"). The text has simply to be enclosed in "|".
497 %
498 % The same effect can be achieved with the command
499 % "\MakeShortVerb" defined in {\sf doc.sty}. To use this you
500 % have to add the style option {\tt doc} and place the following
501 % command in the preamble:
502 %
503 % "\MakeShortVerb{|}"
504 %
505 % Example:
506 %
507 % You type "|proc_1|" and you get {\tt proc\_1}.
508 %
509 %
510 % \section*{Bugs and Problems}
511 %
512 % \begin{itemize}
513 % \item The bugs and problems of earlier releases have been corrected.
514 % \end{itemize}
515 %
516 %
517 % \newpage
518 % \section*{A Sample}
519 %
520 % {\catcode`\%=14 \Listing{sample.pl}}
521 % \newpage
522 % \PrologInput{sample.pl}
523 %
524 %
525 % ^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
526 % \StopEventually{}
527 % ^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
528 % \newpage
529 %
530 % \section{The Implementation}
531 %
532 % \begin{macrocode}
533 \ifx\documentclass\relax \else
534 \ProvidesPackage{pl}[\filedate\space Gerd Neugebauer (\fileversion)]
535 \fi
536 % \end{macrocode}
537 %
538 % \subsection{Options and Defaults}
539 %
540 % First of all we define the macros containing the default values for
541 % certain options. The user may redefine them with "\renewcommand" to
542 % adapt them to the personal preferences.
543 %
544 % \begin{macrocode}
545 \def\PrologFont{\small\tt}
546 % \end{macrocode}
547 % The macro "\PrologFont" contains the font changing command executed
548 % to typeset the Prolog code in the verbatim-like environment.
549 %
550 % \begin{macrocode}
551 \def\PrologIndent{2em}
552 % \end{macrocode}
553 % The macro "\PrologIndent" contains the indentation of the Prolog
554 % code in the verbatim-like environment.
555 %
556 % \begin{macrocode}
557 \def\PrologNumberFont{\tiny\rm}
558 % \end{macrocode}
559 % The macro "\PrologNumberFont" contains the font changing command
560 % used to typeset the line numbers (if enabled) in the verbatim-like
561 % environment.
562 %
563 % \begin{macrocode}
564 \def\PrologRuleWidth{0pt}
565 % \end{macrocode}
566 % The macro "\PrologRuleWidth" contains the width of the rule
567 % separating Prolog code and text.
568 %
569 % \begin{macrocode}
570 \def\PrologListFont{\small\tt}
571 % \end{macrocode}
572 % The macro "\PrologListFont" contains the font changing command
573 % to typeset a Prolog list (exports).
574 %
575 % \begin{macrocode}
576 \def\PrologListIndent{2em}
577 % \end{macrocode}
578 % The macro "\PrologListIndent" contains the indentation for a Prolog
579 % list (exports).
580 %
581 % \begin{macrocode}
582 \def\PrologModule#1#2{\section{The Module {\tt #1}}}
583 % \end{macrocode}
584 % The macro "\PrologModule" contains the command which is called at
585 % the beginning of a module. The first argument is the name of the
586 % module. The second argument is the list of exports.
587 %
588 % This macro is supposed to be redefined by the user with
589 % "\renewcommand".
590 %
591 % \begin{macrocode}
592 \def\PrologFile#1#2{\section{The File {\tt #1}}}
593 % \end{macrocode}
594 % The macro "\PrologFile" contains the command which is called at
595 % the beginning of a non-module Prolog file. The first argument is the name
596 % of the module. The second argument is usually empty.
597 %
598 % This macro is supposed to be redefined by the user with
599 % "\renewcommand".
600 %
601 % \begin{macrocode}
602 \def\PredicateFont{\tt}
603 % \end{macrocode}
604 % The macro "\PredicateFont" contains the font switching command
605 % used in "\Predicate" for the body of the predicate description.
606 %
607 % \begin{macrocode}
608 \def\PredicateFileFont{\small\sf}
609 % \end{macrocode}
610 % The macro "\PredicateFileFont" contains the font switching command
611 % used in "\Predicate" for the file name
612 %
613 % \begin{macrocode}
614 \def\PredicateSkip{\smallskip}
615 % \end{macrocode}
616 % The macro "\PredicateSkip" contains the skip command executed before
617 % and after "\Predicate".
618 %
619 % \begin{macrocode}
620 \def\PredicateIndent{5em}
621 % \end{macrocode}
622 % The macro "\PredicateIndent" contains length of the
623 % maximal indentation in the macro "\Predicate".
624 %
625 % \begin{macrocode}
626 \def\PredicateFileExtension{}
627 % \end{macrocode}
628 % The macro "\PredicateFileExtension" contains the text appended to
629 % file name in the "\Predicate" command.
630 %
631 % \begin{macrocode}
632 \def\PredicateFileWidth{5em}
633 % \end{macrocode}
634 % The macro "\PredicateFileWidth" contains the minimum width of the
635 % file name in the "\Predicate" command. Shorter file names are padded
636 % to this length.
637 %
638 % \begin{macrocode}
639 \def\PredicateFileSep{1em}
640 % \end{macrocode}
641 % The macro "\PredicateFileSep" contains the width of the
642 % separating space between the predicate description and the file name.
643 %
644 % \begin{macrocode}
645 \def\PredicateBoxSep{3pt}
646 % \end{macrocode}
647 % The macro "\PredicateBoxSep" contains the amount of space between
648 % the box and contents in the "\Predicate" command. This is similar to
649 % "\fboxsep" in \LaTeX.
650 %
651 % \begin{macrocode}
652 \def\PredicateBoxRule{0.5pt}
653 % \end{macrocode}
654 % The macro "\PredicateBoxRule" contains the line thickness of box in
655 % the "\Predicate" command. This is similar to "\fboxrule" in
656 % \LaTeX.
657 %
658 % \begin{macrocode}
659 \def\PredicateIndex#1{\index{#1}}
660 % \end{macrocode}
661 % The macro "\PredicateIndex" contains the command which is called to
662 % put a predicate into an index. The argument is the string to index.
663 %
664 % This macro may be redefined by the user with "\renewcommand".
665 %
666 % \begin{macrocode}
667 \newif\ifPrologNumberLines
668 % \end{macrocode}
669 % switch to enable line numbering
670 %
671 %
672 %
673 % \subsection{Internals}
674 %
675 % \begin{macrocode}
676 \def\PrologEXPORTS{}
677 % \end{macrocode}
678 % The macro "\PrologEXPORTS" contains the current list of exports.
679 %
680 % \begin{macrocode}
681 \def\PrologFILE{}
682 % \end{macrocode}
683 % The macro "\PrologFILE" contains the current module or file
684 % name. This is not supposed to be set by the user. Nevertheless
685 % there might be occasions where this is necessary (e.g. in the
686 % documentation of this style option).
687 %
688 %
689 % \subsection{Configuration Commands}
690 % The different Prolog dialects have different ways to declare
691 % modules. Thus pl needs to know which dialect is currently used. This
692 % influences how "PrologInput" handles the first Prolog clause.
693 %
694 % \begin{macrocode}
695 \def\PrologDialect#1{%
696 \@ifundefined{PL@start@module@#1}%
697 {\message{*** Prolog dialect #1 is undefined. Ignored.}}%
698 {\gdef\PL@Dialect{#1}}}
699 \def\PL@Dialect{eclipse}
700 % \end{macrocode}
701 % The command "\PrologDialect" can be used to declare the Prolog
702 % dialect used. The value is stored in the macro "\PL@Dialect" for
703 % later use. This is only done if an appropriate macro to handle a module
704 % are defined.
705 %
706 %
707 % \begin{macrocode}
708 \gdef\PL@@delayed{}
709 % \end{macrocode}
710 % Keep some characters which were read in advance.
711 %
712 %
713 %
714 % \begin{macrocode}
715 \newcount\PL@line
716 % \end{macrocode}
717 % We allocate a new counter for the line number of Prolog code (if
718 % enabled).
719 %
720 %
721 %
722 % \subsection{Typesetting Prolog Code}
723 %
724 % Prolog code is typeset is a verbatim-like way. For this purpose a
725 % modified version of the verbatim environment from the \TeX\ book is
726 % used. For an explanation see pages 380--382 in the \TeX\ book.
727 %
728 % \begin{macrocode}
729 \gdef\PL@code@setup{\PrologFont\parskip=0ex\parindent=0pt
730 \ifx\PL@@delayed\empty\else%
731 \parbox{\PrologIndent}{%
732 \ifPrologNumberLines \PrologNumberFont \the\PL@line%
733 \global\advance\PL@line1
734 \else\ \fi}\PL@@delayed%
735 \gdef\PL@@delayed{}\par
736 \fi%
737 \def\par{\leavevmode\egroup\box0\endgraf}
738 \def\do##1{\catcode`##1=12 }\dospecials
739 \obeyspaces
740 \obeylines
741 % \catcode`\`=\other
742 \catcode`\^^I=13
743 \everypar{\parbox{\PrologIndent}{%
744 \ifPrologNumberLines \PrologNumberFont \the\PL@line%
745 \global\advance\PL@line1
746 \fi
747 \hfill}\PL@code@startbox}}
748 % \end{macrocode}
749 %
750 %
751 % \begin{macrocode}
752 \def\PL@code@startbox{\setbox0=\hbox\bgroup}
753 % \end{macrocode}
754 %
755 %
756 % \begin{macrocode}
757 {\catcode`\^^I=13
758 \gdef^^I{\leavevmode\egroup
759 \dimen0=\wd0 % the width so far, or since the previous tab
760 \setbox1=\hbox{\PrologFont\space}\dimen1=8\wd1
761 \divide\dimen0 by\dimen1
762 \multiply\dimen0 by\dimen1 % compute previous multiple of tab
763 \advance\dimen0 by\dimen1 % advance to next multiple of tab
764 \wd0=\dimen0 \box0 \PL@code@startbox}%
765 }
766 {\obeyspaces\global\let =\ }
767 % \end{macrocode}
768 %
769 %
770 % \begin{macrocode}
771 \def\PL*/{\PL@PL@init%
772 \begingroup
773 \PL@code@setup
774 \PL@doPL}
775 % \end{macrocode}
776 %
777 %
778 % "|" is temporary escape character to catch the end "/*PL"
779 % \begin{macrocode}
780 {\catcode`\|=0 \catcode`\\=12
781 |obeylines|gdef|PL@doPL^^M#1/*PL{#1|endgroup|PL@PL@exit}}
782 % \end{macrocode}
783 %
784 %
785 % Initialization macro
786 % \begin{macrocode}
787 \def\PL@PL@init{%
788 \ifdim\PrologRuleWidth>0pt%
789 \par\noindent\rule{\textwidth}{\PrologRuleWidth}\par%
790 \else\medskip\par\fi}
791 % \end{macrocode}
792 %
793 %
794 %
795 % \begin{macrocode}
796 \def\PL@PL@exit{%
797 \ifdim\PrologRuleWidth>0pt%
798 \vspace{-2ex}\noindent\rule{\textwidth}{\PrologRuleWidth}\par%
799 \else\smallskip\par\fi}
800 % \end{macrocode}
801 %
802 %
803 %
804 %
805 % Dirty hack.
806 % make : active to catch :-
807 % use a group to hide the changes
808 % \begin{macrocode}
809 \def\PL@INIT{\begingroup\catcode`:=13\catcode`/=13}
810 % \end{macrocode}
811 %
812 %
813 %
814 % \begin{macrocode}
815 \def\PL@EXIT{\endgroup}
816 % \end{macrocode}
817 %
818 %
819 %
820 % we make : active and include the file
821 % \begin{macrocode}
822 \gdef\PrologInput{%
823 \begingroup
824 \catcode`\_=12
825 \PL@Input
826 }
827 % \end{macrocode}
828 %
829 %
830 % \begin{macrocode}
831 \PL@INIT
832 \gdef\PL@Input#1{%
833 \gdef\PrologFILE{#1}%
834 \gdef\PrologMODULE{}%
835 \gdef\PrologEXPORTS{}%
836 \global\PL@line=1%
837 \endgroup
838 \PL@INIT%
839 \let:=\PL@COLON
840 \let/=\PL@SLASH
841 \input{#1}%
842 \gdef\PrologFILE{}%
843 \gdef\PrologMODULE{}%
844 \gdef\PrologEXPORTS{}%
845 }
846 \PL@EXIT
847 % \end{macrocode}
848 %
849 %
850 %
851 % \subsection{End a File of Prolog Code}
852 %
853 % At the end of a file there is a "*/" which terminates the last
854 % comment for Prolog. Those two characters are stripped away by the macro
855 % "\EndProlog".
856 %
857 % \begin{macrocode}
858 \def\EndProlog#1*/{}
859 % \end{macrocode}
860 %
861 % \subsection{Definition for Various File Types}
862 %
863 % \subsubsection{Definitions for Non-Module Files}
864 %
865 % A file can start with "/*". This case is handled by making the
866 % "/" active and binding it to the command "\PL@SLASH". This
867 % command checks if the next character is a "*". In this case the
868 % catcodes of "/" and ":" can be restored to their defaults. This
869 % is done by "\PL@EXIT".
870 %
871 % Finally the underscore "_" is made active and
872 % "\PL@start@star" is called to do the rest.
873 %
874 % \begin{macrocode}
875 \def\PL@SLASH{\@ifnextchar*{%
876 \PL@EXIT
877 \PL@US@start
878 \PL@SLASH@STAR}{/}}
879 % \end{macrocode}
880 %
881 %
882 %
883 %
884 %
885 % \begin{macrocode}
886 \def\PL@SLASH@STAR*{%
887 \PrologFile{\PrologFILE}{}%
888 \PL@US@end}
889 % \end{macrocode}
890 %
891 %
892 %
893 %
894 %
895 %
896 % \begin{macrocode}
897 \def\PL@COLON{\@ifnextchar-{\PL@goal}{: }}
898 % \end{macrocode}
899 %
900 %
901 %
902 % \begin{macrocode}
903 \def\PL@goal-{%
904 \PL@EXIT
905 \PL@US@start
906 \@ifnextchar m{\csname PL@start@module@\PL@Dialect\endcsname}%
907 {\@ifnextchar t{\PL@start@true}%
908 {\csname PL@start@file@\PL@Dialect\endcsname}}}
909 % \end{macrocode}
910 %
911 %
912 % \begin{macrocode}
913 \def\PL@start@true true. /*{%
914 \PrologFile{\PrologFILE}{}%
915 \PL@US@end}
916 % \end{macrocode}
917 %
918 %
919 % \subsubsection{Definitions for ECLiPSe-Prolog}
920 %
921 % The beginning of a module file in eclipse can be in one of the following
922 % forms:
923 %
924 % \begin{description}
925 % \item[:- module\_interface({\em Module})]
926 % \item[:- module({\em Module})]
927 % \end{description}
928 %
929 % We strip away the actual predicate name getting the rest in the macro
930 % parameter \#1. The complete module declaration is stored in the macro
931 % "\PL@delayed" to be inserted later.
932 % \begin{macrocode}
933 \def\PL@start@module@eclipse module#1(#2). /*{%
934 \global\PL@line=1
935 \gdef\PL@@delayed{:- module#1(#2).}
936 \gdef\PrologMODULE{#2}%
937 \catcode`\,=13 %
938 \PrologModule{\PrologFILE}{}%
939 \PL@US@end}
940 % \end{macrocode}
941 %
942 %
943 %
944 % \subsubsection{Definitions for Quintus-Prolog}
945 %
946 % The beginning of a module file in Quintus is in the following form:
947 %
948 % \begin{description}
949 % \item[:- module({\em Module},{\em Exports})] \
950 % \end{description}
951 %
952 %
953 % \begin{macrocode}
954 \def\PL@start@module@quintus module(#1,{%
955 \global\PL@line=1
956 \gdef\PrologFILE{#1}%
957 \catcode`\,=13 %
958 \PL@start@module@quintus@}
959 % \end{macrocode}
960 %
961 %
962 %
963 % \begin{macrocode}
964 \def\PL@start@module@quintus@[#1]). /*{%
965 \gdef\PrologEXPORTS{#1}%
966 \PrologModule{\PrologFILE}{#1}%
967 \PL@US@end}
968 % \end{macrocode}
969 %
970 % \subsubsection{Definitions for C-Prolog}
971 %
972 % I don't know if C-Prolog has a module system nowadays. The last time I
973 % checked it had none. If nobody has a better idea I use Quintus Prolog
974 % syntax in this case even it does not make any sense.
975 %
976 % \begin{macrocode}
977 \let\PL@start@module@cprolog=\PL@start@module@quintus
978 % \end{macrocode}
979 %
980 % \subsubsection{Definitions for Sixtus-Prolog}
981 %
982 % I don't know what's used in Sixtus-Prolog. So I use the same value as for
983 % eclipse.
984 %
985 % \begin{macrocode}
986 \let\PL@start@module@sixtus=\PL@start@module@eclipse
987 % \end{macrocode}
988 %
989 % \subsubsection{Definitions for SWI-Prolog}
990 %
991 % Fortunately the module system of SWI-Prolog is compatible with the module
992 % system of Quintus Prolog. So we just use the definition here again.
993 %
994 % \begin{macrocode}
995 \let\PL@start@module@swiprolog=\PL@start@module@quintus
996 % \end{macrocode}
997 %
998 % \subsubsection{Definitions for SB-Prolog}
999 %
1000 % I don't know if C-Prolog has a module system nowadays. The last time I
1001 % checked it had none. If nobody has a better idea I use Quintus Prolog
1002 % syntax in this case even it does not make any sense.
1003 %
1004 % \begin{macrocode}
1005 \let\PL@start@module@sbprolog=\PL@start@module@quintus
1006 % \end{macrocode}
1007 %
1008 % \subsubsection{Definitions for bin-Prolog}
1009 %
1010 % I don't know what's used in bin-Prolog. So I use the same value as for
1011 % eclipse.
1012 %
1013 % \begin{macrocode}
1014 \let\PL@start@module@binprolog=\PL@start@module@eclipse
1015 % \end{macrocode}
1016 %
1017 %
1018 %
1019 %
1020 % \subsection{Typeset a Boxed Predicate Description}
1021 %
1022 % The first step is to protect the underscores in the predicate names and
1023 % the arguments.
1024 %
1025 %
1026 % \begin{macrocode}
1027 \def\Predicate{\PL@US@start\Predicate@}
1028 % \end{macrocode}
1029 %
1030 % The syntax is oriented towards Prolog syntax. The name and the arity of
1031 % the predicate may not contain "/" or "(".
1032 %
1033 % \begin{macrocode}
1034 \def\Predicate@#1/#2(#3).{%
1035 \PredicateSkip\par\noindent%
1036 {\setbox1=\hbox{\PredicateFileFont \PrologFILE\PredicateFileExtension}%
1037 \fboxrule=\PredicateBoxRule%
1038 \fboxsep=\PredicateBoxSep%
1039 \fbox{\PredicateIndex{#1/#2}%
1040 \dimen255=\wd1
1041 \ifdim\dimen255<\PredicateFileWidth \dimen255=\PredicateFileWidth \fi
1042 \dimen255=-\dimen255
1043 \advance\dimen255 by-\PredicateFileSep
1044 \advance\dimen255 by \textwidth
1045 \parbox{\dimen255}{\raggedright
1046 \setbox0=\hbox{\normalsize\PredicateFont #1(}
1047 \dimen254=\wd0
1048
1049 \ifdim\dimen254>\PredicateIndent \dimen254=\PredicateIndent\fi
1050 \dimen253=\dimen255 \advance\dimen253 by -\dimen254
1051 \parshape=2 0mm \dimen255 \dimen254 \dimen253
1052 \normalsize\PredicateFont #1\ifx\@empty#3 \else(#3)\fi
1053 }}%
1054 \hfill \box1\PredicateSkip\par
1055 }\PL@US@end}
1056 % \end{macrocode}
1057 %
1058 %
1059 %
1060 %
1061 %
1062 %
1063 %
1064 % \subsection{Typeset a List of Prolog Predicates}
1065 %
1066 %
1067 % \begin{macrocode}
1068 \def\PrologList{\par\noindent%
1069 \PL@US@start
1070 \PrologListFont
1071 \catcode`\,=13%
1072 \parindent=\PrologListIndent\parskip=0pt\par
1073 \PL@List}
1074 % \end{macrocode}
1075 %
1076 %
1077 %
1078 % \begin{macrocode}
1079 {\catcode`\,=13
1080 \gdef\PL@List[#1]{%
1081 \def,{\par}%
1082 #1
1083 \PL@US@end\par}
1084 }
1085 % \end{macrocode}
1086 %
1087 %
1088 % \begin{macrocode}
1089 \def\PrologListEXPORTS{\PrologList[\PrologEXPORTS]}
1090 % \end{macrocode}
1091 %
1092 %
1093 %
1094 %
1095 % \subsection{Special Treatment of the Underscore}
1096 %
1097 % We define two macros to activate and deactivate the underscore
1098 % respectively. Those two macros have to come in pairs always. The first
1099 % one opens a group to protect the changes. The closing macro simply closes
1100 % the group, thus undoing the effects of the first macro.
1101 %
1102 % \begin{macrocode}
1103 \def\PL@US@start{\begingroup\catcode`\_=13 }
1104 \def\PL@US@end{\endgroup }
1105 % \end{macrocode}
1106 %
1107 %
1108 %
1109 % \begin{macrocode}
1110 \def\WithUnderscore{\begingroup\catcode`\_=13 \With@Underscore}
1111 \def\With@Underscore#1{#1\endgroup}
1112 % \end{macrocode}
1113 %
1114 % \subsection{Misc}
1115 %
1116 % A spin off product of this style file is a macro to include a file
1117 % verbatim. Such a macro is also provided by the verbatim package and
1118 % others. Nevertheless I have left it in.
1119 %
1120 % \begin{macrocode}
1121 \def\Listing#1{\par\begingroup%
1122 \PL@line=1%
1123 \PL@code@setup%
1124 \input{#1}%
1125 \endgroup}
1126 % \end{macrocode}
1127 %
1128 %\iffalse
1129 %</pl>
1130 %<*pcode>
1131 %\fi
1132 % \section{Backward Compatibility Mode: {\tt pcode.sty}}
1133 %
1134 % For backward compatibility some macros are defined in a style file under
1135 % the old name {\tt pcode.sty}. The new style file has to be accessible
1136 % under the new name {\tt pl.sty}. This file is loaded before some macros
1137 % are defined.
1138 %
1139 % \begin{macrocode}
1140 \ifx\PrologFont\relax\else\input pl.sty\fi
1141 % \end{macrocode}
1142 %
1143 % In former versions mainly the Prolog dialect Quintus has been
1144 % supported. Thus a boolean was enough to tell apart the dialects Quintus
1145 % and eclipse --- which came next. This is emulated with the next two
1146 % macros.
1147 %
1148 % \begin{macrocode}
1149 \def\PrologQuintustrue{\PrologDialect{quintus}}
1150 \def\PrologQuintusfalse{\PrologDialect{eclipse}}
1151 % \end{macrocode}
1152 %
1153 % The macro "\WithUnderscore" was named "\WithActiveUnderscore"
1154 % in a former version of {\tt pcode.sty}. The {\em Active} part of the name
1155 % was misleading for users. Thus it has been removed. The old name is made
1156 % an alias for the new one.
1157 %
1158 % \begin{macrocode}
1159 \let\WithActiveUnderscore=\WithUnderscore
1160 % \end{macrocode}
1161 %
1162 % In an ancient version of {\tt pcode.sty} the macro "\EndProlog" was
1163 % named "\StopProlog". Thus we make an alias for the old name.
1164 %
1165 % \begin{macrocode}
1166 \let\StopProlog=\EndProlog
1167 % \end{macrocode}
1168 %
1169 % Make "\PL@INIT" usable for the user as well. I don't know where
1170 % this might be used. It has been in the old version, so I put it into the
1171 % compatibility mode.
1172 %
1173 % \begin{macrocode}
1174 \let\PrologInit=\PL@INIT
1175 % \end{macrocode}
1176 %
1177 %\iffalse
1178 %</pcode>
1179 %\fi
1180 % \Finale
1181 %
1182 \endinput