diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/plweb/pl.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/plweb/pl.dtx | 1188 |
1 files changed, 1188 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/plweb/pl.dtx b/Master/texmf-dist/source/latex/plweb/pl.dtx new file mode 100644 index 00000000000..a0960f3a53e --- /dev/null +++ b/Master/texmf-dist/source/latex/plweb/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 |