trunk/Master/texmf-dist/source/latex/plweb

git-svn-id: svn://tug.org/texlive/trunk@452 c570f23f-e606-0410-a88d-b1316a301751

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