changeset 2:546bfd3988b0

Added unpolished pldoc documentation.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/pldoc/pldoc.sty	Fri Jan 13 15:53:04 2012 +0000
@@ -0,0 +1,517 @@
+%			SWI-Prolog document-style
+
+% Test for PDF generation using pdflatex
+
+\usepackage{ifpdf}
+%Old tex versions
+%\newif\ifpdf
+%\ifx\pdfoutput\undefined
+%   \pdffalse
+%\else
+%   \pdfoutput=1
+%   \pdftrue
+%\fi
+
+% Get hyperrefs to work
+
+\usepackage{makeidx}
+\usepackage{url}
+
+\ifpdf
+  \usepackage[pdftex,colorlinks=true,urlcolor=blue]{hyperref}
+  \pdfcompresslevel=9
+%  \pdfcatalog{
+%    /PageMode /UseOutLines
+%  }
+  \usepackage[pdftex]{graphicx}
+  \DeclareGraphicsExtensions{.pdf,.jpg,.png}
+\else
+  \usepackage[dvips]{graphicx}
+  \DeclareGraphicsExtensions{.eps,.ps}
+\fi
+\graphicspath{{figs/}{./}}
+
+%	Other styles
+
+\usepackage{a4wide}
+\usepackage{longtable}
+\usepackage{ifthen}
+\usepackage{dcolumn}
+\usepackage{calc}
+\setlongtables
+
+\catcode`\^^A=8% downarrow are for subscripts
+\catcode`\_=\active
+\def_{\ifmmode
\else\_\fi}
+\def\vobeyspaces{\@vobeyspaces}
+
+\newcommand{\onlinebreak}{}
+
+%	References
+
+\newcommand{\secref}[1]{section~\ref{sec:#1}}
+\newcommand{\appref}[1]{appendix~\ref{sec:#1}}
+\newcommand{\chapref}[1]{chapter~\ref{sec:#1}}
+\newcommand{\figref}[1]{figure~\ref{fig:#1}}
+\newcommand{\tabref}[1]{table~\ref{tab:#1}}
+
+\newcommand{\Secref}[1]{Section~\ref{sec:#1}}
+\newcommand{\Appref}[1]{Appendix~\ref{sec:#1}}
+\newcommand{\Chapref}[1]{Chapter~\ref{sec:#1}}
+\newcommand{\Figref}[1]{Figure~\ref{fig:#1}}
+\newcommand{\Tabref}[1]{Table~\ref{tab:#1}}
+
+\newcommand{\tm}{$^{tm}$}
+
+\newcommand{\reffont}{\tt}
+\newcommand{\predref}[2]{%		% functor/arity
+	\mbox{\reffont #1/#2}}
+\newcommand{\funcref}[2]{%		% functor/arity
+	\mbox{\reffont #1/#2}}
+\newcommand{\dcgref}[2]{%		% functor//arity
+	\mbox{\reffont #1//#2}}
+\newcommand{\qpredref}[3]{%		% module:functor/arity
+	\mbox{\reffont #1:#2/#3}}
+\newcommand{\qdcgref}[3]{%		% module:functor//arity
+	\mbox{\reffont #1:#2//#3}}
+\newcommand{\nopredref}[2]{%		% functor/arity (external)
+	\mbox{\reffont #1/#2}}
+\newcommand{\functor}[2]{%		% functor/arity (no predicate)
+	\mbox{\reffont #1/#2}}
+\newcommand{\manref}[2]{%		% page(n)
+	\mbox{{\reffont #1(}{\rm #2}{\tt )}}}
+\newcommand{\cfuncref}[2]{%		% function(Args...)
+	\mbox{{\reffont #1(}{\it #2}{\tt )}}}
+\newcommand{\prologflag}[1]{%
+	\mbox{\reffont #1}}
+
+%	Descriptions (definitions) of various things
+%	Note: I do not know where the 1ex comes from. This should fit
+%	exactly, but appearently some dimension is missing.  I suspect
+%	a space creaping in somewhere.
+
+\def\@nodescription{false}
+
+\newcommand{\defentry}[1]{\definition{#1}}
+\newcommand{\definition}[1]{%
+	\onlinebreak%
+	\ifthenelse{\equal{\@nodescription}{true}}{%
+	    \def\@nodescription{false}%
+	    \makebox[-\leftmargin]{\mbox{}}\makebox[\linewidth+\leftmargin-1ex][l]{\bf #1}\\}{%
+	    \item[{\makebox[\linewidth+\leftmargin-1ex][l]{#1}}]}}
+\newcommand{\nodescription}{\def\@nodescription{true}}
+
+\makeatletter
+\def\cmdlineoptionitem{\@ifstar{\@gluedcmdoptitem}{\@cmdoptitem}}
+\def\@gluedcmdoptitem#1#2{\definition{\texttt{#1}\var{#2}}}
+\def\@cmdoptitem#1#2{\definition{\texttt{#1} \var{#2}}}
+\makeatother
+\newcommand{\longoptionitem}[2]{%
+	\ifthenelse{\equal{}{#2}}{%
+	    \definition{-{}-#1}}{%
+	    \definition{-{}-#1={\it #2}}}\ignorespaces}
+\newcommand{\longoption}[2]{%
+	\ifthenelse{\equal{}{#2}}{%
+	    \mbox{\reffont -{}-#1}}{%
+	    \mbox{\reffont -{}-#1={\it #2}}}}
+
+\newcommand{\traceoption}[3]{%
+	\definition{{\tt #1} (#2)}#3%
+	\ignorespaces}
+\newcommand{\pleaseoption}[3]{%
+	\definition{#1 {\it #2} {\rm(default: \it #3)}}%
+	\ignorespaces}
+%\prologflagitem{Name}{Type}{Access}
+\newcommand{\prologflagitem}[3]{%
+	\definition{#1 {\it (#2%
+	    \ifthenelse{\equal{rw}{#3}}{, changeable}{})}}%
+	\index{flag:#1}\ignorespaces}
+\newcommand{\escapeitem}[1]{%
+	\definition{\Sesc{\tt #1}}
+	\ignorespaces}
+\newcommand{\fmtchar}[1]{%
+	\item[\tt #1]%
+	\ignorespaces}
+
+%	\directive{Name}{Arity}{Args}
+%	\predicate[Attibutes]{Name}{Arity}{Args}
+%	\function[Attibutes]{Name}{Arity}{Args}
+%	\infixop{Name}{Left}{Right}
+%	\prefixop{Name}{Right}
+%	\infixfunction{Name}{Left}{Right}
+%	\prefixfunction{Name}{Right}
+%	\dcg[Attibutes]{Name}{Arity}{Args}
+%
+%	Predicate   descriptions.   Must   appear   in   a   description
+%	environment.
+
+\newcommand{\resitem}[1]{%
+	\defentry{#1}%
+	\index{#1}\ignorespaces}
+\makeatletter
+\def\predatt#1{\hfill{\it\footnotesize[#1]}}
+\def\predicate{\@ifnextchar[{\@attpredicate}{\@predicate}}
+\def\qpredicate{\@ifnextchar[{\@attqpredicate}{\@qpredicate}}
+\def\@predicate#1#2#3{%
+	\ifthenelse{\equal{#2}{0}}{%
+	    \defentry{#1}}{%
+	    \defentry{#1({\it #3})}}%
+	\index{#1/#2}\ignorespaces}
+\def\@attpredicate[#1]#2#3#4{%
+	\ifthenelse{\equal{#3}{0}}{%
+	    \defentry{#2\predatt{#1}}}{%
+	    \defentry{#2({\it #4})\predatt{#1}}}%
+	\index{#2/#3}\ignorespaces}
+\def\@qpredicate#1#2#3#4{%
+	\ifthenelse{\equal{#3}{0}}{%
+	    \defentry{#1:#2}}{%
+	    \defentry{#1:#2({\it #4})}}%
+	\index{#1/#2}\ignorespaces}
+\def\@attqpredicate[#1]#2#3#4#5{%
+	\ifthenelse{\equal{#4}{0}}{%
+	    \defentry{#2:#3\predatt{#1}}}{%
+	    \defentry{#2:#3({\it #5})\predatt{#1}}}%
+	\index{#2/#3}\ignorespaces}
+\def\directive{\@ifnextchar[{\@attdirective}{\@directive}}
+\def\@directive#1#2#3{%
+	\ifthenelse{\equal{#2}{0}}{%
+	    \defentry{:- #1}}{%
+	    \defentry{:- #1({\it #3})}}%
+	\index{#1/#2}\ignorespaces}
+\def\@attdirective[#1]#2#3#4{%
+	\ifthenelse{\equal{#3}{0}}{%
+	    \defentry{:- #2\predatt{#1}}}{%
+	    \defentry{:- #2({\it #4})\predatt{#1}}}%
+	\index{#2/#3}\ignorespaces}
+\def\dcg{\@ifnextchar[{\@attdcg}{\@dcg}}
+\def\@dcg#1#2#3{%
+	\ifthenelse{\equal{#2}{0}}{%
+	    \defentry{#1}}{%
+	    \defentry{#1({\it #3}) \texttt{//}}}%
+	\index{#1/#2}\ignorespaces}
+\def\@attdcg[#1]#2#3#4{%
+	\ifthenelse{\equal{#3}{0}}{%
+	    \defentry{#2 \texttt{//}\predatt{#1}}}{%
+	    \defentry{#2({\it #4}) \texttt{//}\predatt{#1}}}%
+	\index{#2//#3}\ignorespaces}
+\def\infixop{\@ifnextchar[{\@attinfixop}{\@infixop}}
+\def\@infixop#1#2#3{%
+	\defentry{{\it #2} #1 {\it #3}}%
+	\index{#1/2}\ignorespaces}
+\def\@attinfixop[#1]#2#3#4{%
+	\defentry{{\it #3} #2 {\it #4}\predatt{#1}}%
+	\index{#2/2}\ignorespaces}
+\def\prefixop{\@ifnextchar[{\@attprefixop}{\@prefixop}}
+\def\@prefixop#1#2{%
+	\defentry{#1 {\it #2}}%
+	\index{#1/1}\ignorespaces}
+\def\@attprefixop[#1]#2#3{%
+	\defentry{#2 {\it #3}\predatt{#1}}%
+	\index{#2/1}\ignorespaces}
+\let\function\predicate
+\let\infixfunction\infixop
+\let\prefixfunction\prefixop
+\makeatother
+
+%	\termitem{functor}{Args}
+%	\infixtermitem{functor}{Left}{Right}
+%	\prefixtermitem{functor}{Right}
+%	\postfixtermitem{functor}{Left}
+%
+%	Terms in description lists. Typically used to describe various
+%	possible values or types for a term.
+
+\newcommand{\termitem}[2]{%
+	\ifthenelse{\equal{}{#2}}{%
+	    \definition{#1}}{%
+	    \definition{#1({\it #2})}}\ignorespaces}
+\newcommand{\infixtermitem}[3]{%
+	    \definition{{\it #2} #1 {\it #3}}\ignorespaces}
+\newcommand{\prefixtermitem}[2]{%
+	    \definition{#1 {\it #2}}\ignorespaces}
+\newcommand{\postfixtermitem}[2]{%
+	    \definition{{\it #2} #1}\ignorespaces}
+
+%	\term{functor}{Args}
+%	\infixterm{functor}{Left}{Right}
+%	\prefixterm{functor}{Right}
+%	\postfixterm{functor}{Left}
+%
+%	Terms used in running text.
+
+\def\term{}
+\renewcommand{\term}[2]{%
+	\ifthenelse{\equal{\protect}{\protect#2}}{%
+	    {\reffont #1}}{%
+	    {\reffont #1}({\it #2})}}
+\newcommand{\infixterm}[3]{{\it #2} #1 {\it #3}}
+\newcommand{\prefixterm}[2]{#1 {\it #2}}
+\newcommand{\postfixterm}[2]{{\it #2} #1}
+\newcommand{\errorterm}[2]{\mbox{\tt%
+	\ifthenelse{\equal{}{#2}}{%
+	    #1}{%
+	    #1(#2)}}}
+
+
+\newcommand{\cfunction}[3]{%
+	\defentry{{\tt #1} #2{\rm (}{\it #3}{\rm )}}%
+	\index{#2()}\ignorespaces}
+\newcommand{\constructor}[2]{%
+	\defentry{#1::#1{\rm (}{\it #2}{\rm )}}%
+	\index{#1::#1()}\ignorespaces}
+\newcommand{\destructor}[1]{%
+	\defentry{#1::\Stilde{}#1{\rm ()}}%
+	\index{#1::\Stilde{}#1()}\ignorespaces}
+\newcommand{\cppcast}[2]{%
+	\defentry{#1::operator #2{\rm ({\it void})}}%
+	\index{#1::operator #2()}\ignorespaces}
+\newcommand{\cdecl}[2]{{\tt #1} {\em #2}}
+\newcommand{\cmacro}[3]{%
+	\defentry{{\it #1} #2({\it #3})}%
+	\index{#2()}\ignorespaces}
+\newcommand{\constitem}[1]{%
+	\definition{#1}%
+	\index{#1}\ignorespaces}
+\newcommand{\cglobalvar}[1]{{\tt #1}}
+\newcommand{\classitem}[1]{%
+	\definition{Class #1}%
+	\index{#1 \string\idxtype{class}}\ignorespaces}
+\newcommand{\menuitem}[2]{%
+	\ifthenelse{\equal{\protect}{\protect#2}}{%
+	    \definition{\textsf #1}}{%
+	    \definition{\textsf #1 ({\it #2})}}%
+	\index{#1 \string\idxtype{menu}}%
+	\ignorespaces}
+
+
+%	\tag{Keyword}
+%
+%	PlDoc @keyword expansion.  \mtag{Keyword} is a multi-valued tag
+
+\newcommand{\tag}[1]{%
+	\item[#1]}
+\newcommand{\mtag}[1]{%
+	\item[#1]\mbox{}\\}
+
+\newcommand{\bnfmeta}[1]{\ifmmode{\langle\mbox{\it #1}\rangle}\else$\langle\mbox{\it #1}\rangle$\fi}
+\newcommand{\bnfor}{\ifmmode\mid\else$\mid$\fi}
+\newcommand{\isa}{& ::= &}
+\newcommand{\ora}{& $\mid$ &}
+
+\renewcommand{\arg}[1]{\ifmmode\mbox{\em #1}\else{\it #1}\fi}
+\newcommand{\class}[1]{{\em #1}\index{#1 \string\idxtype{class}}}
+\newcommand{\classs}[1]{{\em #1s}\index{#1 \string\idxtype{class}}}
+\newcommand{\demo}[1]{{\sf #1}\index{#1 \string\idxtype{demo}}}
+\newcommand{\pllib}[1]{{\texttt{#1}}\index{#1 \string\idxtype{library}}}
+\newcommand{\clib}[1]{{\tt #1}\index{#1 \string\idxtype{library}}}
+\newcommand{\tool}[1]{{\em #1}\index{#1 \string\idxtype{tool}}}
+\newcommand{\menuref}[1]{\textsf{#1}\index{#1 \string\idxtype{menu}}}
+\newcommand{\constf}[1]{{\reffont #1}}
+\newcommand{\const}[1]{{\tt #1}}
+\newcommand{\plflag}[1]{{\tt #1}}
+\newcommand{\type}[1]{{\reffont #1}}
+\newcommand{\idx}[1]{#1\index{#1}}
+\newcommand{\foreseen}[1]{\footnote{#1}}
+\newcommand{\metafile}[1]{\mbox{\tt #1}}
+\newcommand\file{\begingroup \urlstyle{tt}\Url}
+\newcommand\email{\begingroup \urlstyle{tt}\Url}
+\newcommand{\env}[1]{\mbox{\tt #1}}
+\newcommand{\except}[1]{\mbox{\tt #1}}
+\newcommand{\exam}[1]{\mbox{\tt #1}}
+\newcommand{\module}[1]{\mbox{\reffont #1}}
+\newcommand{\fileext}[1]{\mbox{\texttt{.#1}}}
+\newcommand{\option}[1]{\mbox{\tt #1}}
+\newcommand{\resource}[1]{\mbox{\reffont #1}}
+\newcommand{\cmdlineoption}[1]{\mbox{\tt #1}}
+\newcommand{\argoption}[2]{\mbox{\tt #1 \em #2}}
+\newcommand{\ctype}[1]{{\texttt{#1}}}
+\newcommand{\op}[1]{{\tt #1}}
+\newcommand{\program}[1]{\texttt{#1}}
+\newcommand{\manpage}[2]{{\bf #1}(#2)}
+\newcommand{\chr}[1]{{\tt #1}}
+\newcommand{\jargon}[1]{{\em #1}}
+\newcommand{\strong}[1]{{\bf #1}}
+\newcommand{\texcmd}[1]{{\Sesc}{\tt #1}}
+\newcommand{\texenv}[1]{{\tt #1}}
+\newcommand{\texmode}[1]{{\tt #1}}
+\newcommand{\HTML}[1]{{\bf #1}}
+\newcommand{\libdoc}[2]{\section{\pllib{#1}: #2}}
+\newcommand{\key}[1]{{\sf #1}}
+\newcommand{\menu}[2]{%
+	{\sf #1}%
+	\ifthenelse{\equal{#2}{}}{%
+	    }{%
+	    ~(\texttt{#2})}}
+
+\newcommand\satom{\begingroup \urlstyle{tt}\Url}
+\newcommand\fmtseq{\begingroup \urlstyle{tt}\Url}
+
+\urldef{\Sexe}\satom{#!}		% #!
+\urldef{\Scgt}\satom{#>}		% #>
+\urldef{\Scge}\satom{#>=}		% #>=
+\urldef{\Sclt}\satom{#<}		% #<
+\urldef{\Scle}\satom{#=<}		% #=<
+\urldef{\Sceq}\satom{#=}		% #=
+\urldef{\Scne}\satom{#\=}		% #\=
+\urldef{\Scnot}\satom{#\}		% #\
+\urldef{\Scor}\satom{#\/}		% #\/
+\urldef{\Scand}\satom{#/\}		% #/\
+\urldef{\Sequiv}\satom{#<=>}            % #<=>
+\urldef{\Slimpl}\satom{#<=}             % #<=
+\urldef{\Srimpl}\satom{#=>}             % #=>
+\urldef{\Slimplies}\satom{#<==}         % #<==
+\urldef{\Srimplies}\satom{#==>}         % #==>
+\urldef{\Scequal}\satom{#<==>}          % #<==>
+\urldef{\Scieq}\satom{#=:=}		% #=:=
+\urldef{\Scine}\satom{#=\=}		% #=\=
+\urldef{\Shash}\satom{#}		% #
+\urldef{\Scut}\satom{!}			% !
+\urldef{\Scomma}\satom{,}		% ,
+\urldef{\Sifthen}\satom{->}		% ->
+\urldef{\Ssoftcut}\satom{*->}		% *->
+\urldef{\Sdot}\satom{.}			% .
+\urldef{\Ssemicolon}\satom{;}		% ;
+\urldef{\Slt}\satom{<}			% <
+\urldef{\Sxor}\satom{><}		% ><
+\urldef{\Seq}\satom{=}			% =
+\urldef{\Suniv}\satom{=..}		% =..
+\urldef{\Saeq}\satom{=:=}		% =:=
+\urldef{\Sle}\satom{=<}			% =<
+\urldef{\Sel}\satom{<=}			% <=
+\urldef{\Sequal}\satom{==}		% ==
+\urldef{\Sstructeq}\satom{=@=}		% =@=
+\urldef{\Sstructneq}\satom{\=@=}	% \=@=
+\urldef{\Sane}\satom{=\=}		% =\=
+\urldef{\Sgt}\satom{>}			% >
+\urldef{\Sge}\satom{>=}			% >=
+\urldef{\Stlt}\satom{@<}		% @<
+\urldef{\Stle}\satom{@=<}		% @=<
+\urldef{\Stgt}\satom{@>}		% @>
+\urldef{\Stge}\satom{@>=}		% @>=
+\urldef{\Snot}\satom{\+}		% \+
+\urldef{\Sne}\satom{\=}			% \=
+\urldef{\Snequal}\satom{\==}		% \==
+\urldef{\Shat}\satom{^}			% ^
+\urldef{\Sbar}\satom{|}			% |
+\urldef{\Stimes}\satom{*}		% *
+\urldef{\Spow}\satom{**}		% **
+\urldef{\Splus}\satom{+}		% +
+\urldef{\Sminus}\satom{-}		% -
+\urldef{\Sdiv}\satom{/}			% /
+\urldef{\Sidiv}\satom{//}		% //
+\urldef{\Sand}\satom{/\}		% /\
+\urldef{\Slshift}\satom{<<}		% <<
+\urldef{\Srshift}\satom{>>}		% >>
+\urldef{\Sneg}\satom{\}			% \
+\urldef{\Sesc}\satom{\}			% \
+\urldef{\Sor}\satom{\/}			% \/
+\urldef{\Sdollar}\satom{$}		% $
+\urldef{\Squest}\satom{?}		% ?
+\urldef{\Smodule}\satom{:}		% :
+\urldef{\Sneck}\satom{:-}		% :-
+\urldef{\Sdirective}\satom{?-}		% ?-
+\urldef{\Sdcg}\satom{-->}		% -->
+\urldef{\Bc}\satom{\c}			% \c
+\urldef{\Bn}\satom{\n}			% \n
+\urldef{\Br}\satom{\r}			% \r
+\urldef{\Bl}\satom{\l}			% \l
+\urldef{\BB}\satom{\\}			% \\
+\urldef{\Stilde}\satom{~}		% ~
+\urldef{\Spercent}\satom{%}		% %
+\urldef{\Shash}\satom{#}		% #
+\urldef{\Scurl}\satom{{}}		% {}
+\urldef{\SxXX}\satom{xXX..\}		% xXX..\
+
+\newcommand{\bug}[1]{\footnote{BUG: #1}}
+
+\newcommand{\mod}[2]{#1 \mbox{\rm mod} #2}
+\newcommand{\rem}[2]{#1 \mbox{\rm rem} #2}
+\newcommand{\pow}[2]{{#1}^{#2}}
+\newcommand{\bsl}[0]{\Sesc}
+
+%	Index handling
+
+\newcommand{\idxtype}[1]{{\small\em #1}}
+
+%	Prolog predicate summary
+
+\newenvironment{summarylist}[1]{\begin{longtable}[l]{#1}}{\end{longtable}}
+\newcommand{\predicatesummary}[3]{#1/#2 & #3 \\}
+\newcommand{\oppredsummary}[5]{#1/#2 & #5 \\}
+\newcommand{\functionsummary}[3]{#1/#2 & #3 \\}
+\newcommand{\opfuncsummary}[5]{#1/#2 & #5 \\}
+\newcommand{\opsummary}[4]{#3 & #1 & #2 & #4 \\}
+\newcommand{\hook}[1]{(hook)}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%			CODE environment			%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\usepackage{fancyvrb}
+\usepackage{color}
+
+%\definecolor{codeboxcolor}{rgb}{0.7,0.7,0.7}
+\definecolor{codeboxcolor}{rgb}{0.4,0.4,0.4}
+\DefineVerbatimEnvironment%
+  {code}{Verbatim}
+  {frame=single,
+   framerule=0.2pt,
+   rulecolor=\color{codeboxcolor},
+  }
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%			INCLUDE FIGURES				%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%	PostScript figures
+%	\postscriptfig[width=5in]{label}{Title}
+
+\makeatletter
+\def\postscriptfig{\@ifnextchar[{\@scaledpostscriptfig}{\@postscriptfig}}
+\def\@scaledpostscriptfig[#1]#2#3{%
+	\begin{figure}%
+	    \centerline{\includegraphics[#1]{#2}}
+	    \caption{#3}
+	    \label{fig:#2}
+	\end{figure}}
+\def\@postscriptfig#1#2{%
+	\begin{figure}%
+	    \centerline{\includegraphics{#1}}
+	    \caption{#2}
+	    \label{fig:#1}
+	\end{figure}}
+\makeatother
+
+%	\begin{tabularlp}{longest-text}
+
+\newlength{\tabDright}
+\newlength{\tabDleft}
+\newcommand{\PreserveBackslash}[1]{\let\temp=\\#1\let\\=\temp}
+\newcommand{\raggedrightcolumn}{\PreserveBackslash\raggedright\hspace{0pt}}
+\newenvironment{tabularlp}[1]%
+	{\settowidth{\tabDleft}{#1}%
+	 \setlength{\tabDright}{\linewidth-\columnsep*3-\tabDleft}%
+	 \begin{tabular}{|p{\tabDleft}|>{\raggedrightcolumn}p{\tabDright}|}}%
+	{\end{tabular}}
+
+%	\begin{tags} ... \end{tags}
+
+\newenvironment{tags}%
+	{\begin{quote}\begin{description}%
+		\setlength{\itemsep}{0pt}%
+		\footnotesize}%
+	{\end{description}\end{quote}}
+
+
+%	\begin{parameters} ... \end{parameters}
+
+\newenvironment{parameters}%
+	{\par%
+	 \makebox[\linewidth]{\hfill\footnotesize Parameters}
+	 \begin{tabular*}{\linewidth}{lp{0.7\linewidth}}
+	 \hline}%
+	{\end{tabular*}}
+
+

Binary file pldoc/plml.pdf has changed

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/pldoc/plml.tex	Fri Jan 13 15:53:04 2012 +0000
@@ -0,0 +1,325 @@
+\documentclass[10pt]{article}
+\usepackage{pldoc}
+\sloppy
+\makeindex
+
+\begin{document}
+% This LaTeX document was generated using the LaTeX backend of PlDoc,
+% The SWI-Prolog documentation system
+
+
+
+\section{plml: Prolog-Matlab interface}
+
+\label{sec:plml}
+
+\begin{tags}
+    \tag{To be done}
+Use mat(I) and tmp(I) as types to include engine Id.
+
+Clarify relationship between return values and valid Matlab denotation.
+
+Reshape/2 array representation: reshape([ ... ],Size)
+Expression language: arr(Vals,Shape,InnerFunctor) - allows efficient
+representation of arrays of arbitrary things. Will require more strict
+nested list form.
+
+Deprecate old array(Vals::Type) and cell(Vals::Type) left-value syntax.
+
+Remove I from \dcgref{ml_expr}{2} and add to mx type?
+\end{tags}
+
+\paragraph{Types}
+
+\textbf{ml_eng} - Any atom identifying a Matlab engine.
+
+\textbf{ml_stmt} - A Matlab statement
+
+\begin{code}
+X;Y     :: ml_stmt :-  X:ml_stmt, Y:ml_stmt.
+X,Y     :: ml_stmt :-  X:ml_stmt, Y:ml_stmt.
+X=Y     :: ml_stmt :-  X:ml_lval, Y:ml_expr.
+hide(X) :: ml_stmt :-  X:ml_stmt.
+\end{code}
+
+\begin{code}
+ml_expr(A)       % A Matlab expression, possibly with multiple return values
+ml_loc ---> mat(atom,atom).  % Matbase locator
+\end{code}
+
+\paragraph{Matlab expression syntax}
+
+The Matlab expression syntax adopted by this module allows Prolog terms to represent
+or denote Matlab expressions. Let T be the domain of recognised Prolog terms (corresponding to
+the type ml_expr), and M be the domain of Matlab expressions written in Matlab syntax.
+Then V : T\Sifthen{}M is the valuation function which maps Prolog term X to Matlab expression V[X].
+These are some of the constructs it recognises:
+
+Constructs valid only in top level statements, not subexpressions:
+
+\begin{code}
+X;Y             % |--> V[X]; V[Y]  (sequential evaluation hiding first result)
+X,Y             % |--> V[X], V[Y]  (sequential evaluation displaying first result)
+X=Y             % |--> V[X]=V[Y] (assignment, X must denote a valid left-value)
+hide(X)         % |--> V[X]; (execute X but hide return value)
+\end{code}
+
+Things that look and work like Matlab syntax (more or less):
+
+\begin{code}
++X              % |--> uplus(V[X])
+-X              % |--> uminus(V[X])
+X+Y             % |--> plus(V[X],V[Y])
+X-Y             % |--> minus(V[X],V[Y])
+X^Y             % |--> mpower(V[X],V[Y])
+X*Y             % |--> mtimes(V[X],V[Y])
+X/Y             % |--> mrdivide(V[X],V[Y])
+X\Y             % |--> mldivide(V[X],V[Y])
+X.^Y            % |--> power(V[X],V[Y])
+X.*Y            % |--> times(V[X],V[Y])
+X./Y            % |--> rdivide(V[X],V[Y])
+X.\Y            % |--> ldivide(V[X],V[Y])
+X:Y:Z           % |--> colon(V[X],V[Y],V[Z])
+X:Z             % |--> colon(V[X],V[Z])
+X>Z             % |--> gt(V[X],V[Y])
+X>=Z            % |--> ge(V[X],V[Y])
+X<Z             % |--> lt(V[X],V[Y])
+X=<Z            % |--> le(V[X],V[Y])
+X==Z            % |--> eq(V[X],V[Y])
+[X1,X2,...]     % |--> [ V[X1], V[X2], ... ]
+[X1;X2;...]     % |--> [ V[X1]; V[X2]; ... ]
+{X1,X2,...}     % |--> { V[X1], V[X2], ... }
+{X1;X2;...}     % |--> { V[X1]; V[X2]; ... }
+@X              % |--> @V[X] (function handle)
+\end{code}
+
+Things that do not look like Matlab syntax but provide standard Matlab features:
+
+\begin{code}
+'Infinity'      % |--> inf (positive infinity)
+'Nan'           % |--> nan (not a number)
+X``             % |--> ctranpose(V[X]) (conjugate transpose, V[X]')
+X#Y             % |--> getfield(V[X],V[q(Y)])
+X\\Y            % |--> @(V[X])V[Y] (same as lambda(X,Y))
+\\Y             % |--> @()V[Y] (same as thunk(Y))
+lambda(X,Y)     % |--> @(V[X])V[Y] (anonymous function with arguments X)
+thunk(Y)        % |--> @()V[Y] (anonymous function with no arguments)
+vector(X)       % |--> horzcat(V[X1],V[X2], ...)
+atvector(X)     % as vector but assumes elements of X are assumed all atomic
+cell(X)         % construct 1xN cell array from elements of X
+`X              % same as q(X)
+q(X)            % wrap V[X] in single quotes (escaping internal quotes)
+qq(X)           % wrap V[X] in double quotes (escaping internal double quotes)
+tq(X)           % wrap TeX expression in single quotes (escape internal quotes)
+\end{code}
+
+Referencing different value representations.
+
+\begin{code}
+mat(X,Y)           % denotes a value in the Matbase using a dbload expression
+mx(X:mx_blob)      % denotes an MX Matlab array in SWI memory
+ws(X:ws_blob)      % denotes a variable in a Matlab workspace
+wsseq(X:ws_blob)   % workspace variable containing list as cell array.
+\end{code}
+
+Tricky bits.
+
+\begin{code}
+apply(X,AX)        % X must denote a function or array, applied to list of arguments AX.
+cref(X,Y)          % cell dereference, |--> V[X]{ V[Y1], V[Y2], ... }
+arr(Lists)         % multidimensional array from nested lists.
+arr(Lists,Dims)    % multidimensional array from nested lists.
+\end{code}
+
+Things to bypass default formatting
+
+\begin{code}
+noeval(_)          % triggers a failure when processed
+atom(X)            % write atom X as write/1
+term(X)            % write term X as write/1
+\(P)               % escape and call phrase P directly to generate Matlab string
+$(X)               % calls pl2ml_hook/2, denotes V[Y] where plml_hook(X,Y).
+'$VAR'(N)          % gets formatted as p_N where N is assumed to be atomic.
+\end{code}
+
+All other Prolog atoms are written using \predref{write}{1}, while other Prolog terms
+are assumed to be calls to Matlab functions named according to the head functor.
+Thus V[ $<$head$>$( $<$arg1$>$, $<$arg2$>$, ...) ] = $<$head$>$(V[$<$arg1$>$, V[$<$arg2$>$], ...).
+
+There are some incompatibilities between Matlab syntax and Prolog syntax,
+that is, syntactic structures that Prolog cannot parse correctly:
+
+\begin{itemize}
+    \item 'Command line' syntax, ie where a function of string arguments:
+"save('x','Y')" can be written as "save x Y" in Matlab,
+but in Prolog, you must use function call syntax with quoted arguments:
+save(`x,`'Y').
+    \item Matlab's postfix transpose operator "x'" must be written using a different
+posfix operator "x``" or function call syntax "ctranspose(x)".
+    \item Matlab cell referencing using braces, as in x\{1,2\} must be written
+as "cref(x,1,2)".
+    \item Field referencing using dot (.), eg x.thing - currently resolved
+by using hash (\#) operator, eg x\#thing.
+    \item Using variables as arrays and indexing them. The problem is that
+Prolog doesn't let you write a term with a variable as the head
+functor.
+\end{itemize}
+
+\vspace{0.7cm}
+
+\begin{description}
+    \predicate[nondet,multifile]{matlab_init}{2}{-Key, -Cmd:ml_expr}
+Each user-defined clause of \predref{matlab_init}{2} causes \arg{Cmd} to be executed
+whenever a new Matlab session is started.
+
+    \predicate[nondet,multifile]{matlab_path}{2}{-Key, -Path:list(atom)}
+Each user-defined clause of \predref{matlab_path}{2} causes the directories in \arg{Path}
+to be added to the Matlab path of every new Matlab session. Directories
+are relative to the root directory as returned by Matlab function proot.
+
+    \predicate[nondet,multifile]{pl2ml_hook}{2}{+X:term, -Y:ml_expr}
+Clauses of \predref{pl2ml_hook}{2} allow for extensions to the Matlab expression
+language such that \verb|V[$X] = V[Y]| if \verb$pl2ml_hook(X,Y)$.
+
+    \predicate[det]{ml_open}{3}{+Id:ml_eng, +Host:atom, +Options:list(_)}
+\nodescription
+    \predicate[det]{ml_open}{2}{+Id:ml_eng, +Host:atom}
+\nodescription
+    \predicate[det]{ml_open}{1}{+Id:ml_eng}
+Start a Matlab session on the given host. If \arg{Host}=localhost
+or the name of the current current host as returned by \predref{hostname}{1},
+then a Matlab process is started directly. Otherwise, it is
+started remotely via SSH. \arg{Options} defaults to []. \arg{Host} defaults to
+localhost.
+
+Start a Matlab session on the specified host using default options.
+If \arg{Host} is not given, it defaults to localhost. Session will be
+associated with the given \arg{Id}, which should be an atom. See \predref{ml_open}{3}.
+
+Valid options are
+
+\begin{description}
+    \termitem{noinit}{}
+If present, do not run initialisation commands specified by
+\predref{matlab_path}{2} and \predref{matlab_init}{2} clauses. Otherwise, do run them.
+\end{description}
+
+\begin{description}
+    \termitem{debug}{In, Out}
+if present, Matlab is started in a script which captures standard
+input and output to files In and Out respectively.
+
+[What if session is already open and attached to \arg{Id}?]
+\end{description}
+
+    \predicate[det]{ml_close}{1}{+Id:ml_eng}
+Close Matlab session associated with \arg{Id}.
+
+    \predicate[det]{ml_exec}{2}{+Id:ml_eng, +Expr:ml_expr}
+Execute Matlab expression without returning any values.
+
+    \predicate[det]{ml_eval}{4}{+Id:ml_eng, +Expr:ml_expr, +Types:list(type), -Res:list(ml_val)}
+Evaluate Matlab expression binding return values to results list \arg{Res}. This new
+form uses an explicit output types list, so \arg{Res} can be completely unbound on entry
+even when multiple values are required.
+
+    \predicate[semidet]{ml_test}{2}{+Id:ml_eng, +X:ml_expr(bool)}
+Succeeds if \arg{X} evaluates to true in Matlab session \arg{Id}.
+
+    \predicate[det]{===}{2}{Y:ml_vals(A), X:ml_expr(A)}
+Evaluate Matlab expression \arg{X} as in \predref{ml_eval}{4}, binding one or more return values
+to \arg{Y}. If \arg{Y} is unbound or a single ml_val(_), only the first return value is bound.
+If \arg{Y} is a list, multiple return values are processed.
+
+    \predicate[det]{??}{1}{X:ml_expr(_)}
+Execute Matlab expression \arg{X} as with \predref{ml_exec}{2}, without returning any values.
+
+    \predicate[semidet]{???}{1}{X:ml_expr(bool)}
+Evaluate Matlab boolean expression \arg{X} as with \predref{ml_test}{2}.
+
+    \predicate[det]{ml_debug}{1}{+Flag:boolean}
+Set or reset debug state. \verb$ml_debug(true)$ causes formatted Matlab
+statements to be printed before being sent to Matlab engine.
+
+    \predicate[det]{term_mlstring}{3}{+Id:ml_eng, +X:ml_expr, -Y:list(code)}
+Convert term representing Matlab expression to a list of character codes.
+
+    \predicate[det]{term_texatom}{2}{+X:tex_expr, -Y:atom}
+Convert term representing TeX expression to a string in atom form.
+
+    \predicate[semidet]{wsvar}{3}{+X:ws_blob(A), -Nm:atom, -Id:ml_eng}
+True if \arg{X} is a workspace variable in Matlab session \arg{Id}.
+Unifies \arg{Nm} with the name of the Matlab variable.
+
+    \predicate[det]{dropmat}{2}{+Id:ml_id, +Mat:ml_loc}
+Deleting MAT file from matbase.
+
+    \predicate[det]{exportmat}{3}{+Id:ml_id, +Mat:ml_loc, +Dir:atom}
+Export specified MAT file from matbase to given directory.
+
+    \predicate[nondet]{matbase_mat}{2}{+Id:ml_eng, -X:ml_loc}
+Listing mat files actually in matbase at given root directory.
+
+    \predicate[det]{persist_item}{2}{+X:ml_expr(A), -Y:ml_expr(A)}
+Convert Matlab expression to persistent form not dependent on
+current Matlab workspace or MX arrays in Prolog memory space.
+Large values like arrays and structures are saved in the matbase
+replaced with matbase locators. Scalar values are converted to
+literal numeric values. Character strings are converted to Prolog atoms.
+Cell arrays wrapped in the \predref{wsseq}{1} functor are converted to literal
+form.
+
+NB. any side effects are undone on backtracking -- in particular, any
+files created in the matbase are deleted.
+
+    \predicate[det]{mhelp}{1}{+Name:atom}
+Lookup Matlab help on the given name. Equivalent to executing help(`X).
+
+    \predicate[det]{compileoptions}{2}{+Opts:list(ml_options), -Prefs:ml_expr(options)}
+Convert list of option specifiers into a Matlab expression representing
+options (ie a struct). Each specifier can be a Name:Value pair, a name
+to be looked up in the \predref{optionset}{2} predicate, a nested list of ml_options
+compileoptions :: list (optionset \Sbar{} atom:value \Sbar{} struct) \Sifthen{} struct.
+NB. option types are as follows:
+
+\begin{code}
+X :: ml_options :- optionset(X,_).
+X :: ml_options :- X :: ml_option(_).
+X :: ml_options :- X :: list(ml_options).
+X :: ml_options :- X :: ml_expr(struct(_)).
+
+ml_option(A) ---> atom:ml_expr(A).
+\end{code}
+
+    \predicate[det]{multiplot}{2}{+Type:ml_plot, +Cmds:list(ml_expr(_))}
+\nodescription
+    \predicate[det]{multiplot}{3}{+Type:ml_plot, +Cmds:list(ml_expr(_)), -Axes:list(ml_val(handle))}
+Executes plotting commands in \arg{Cmds} in multiple figures or axes as determined
+by \arg{Type}. Valid types are:
+
+\begin{description}
+    \termitem{figs}{Range}
+Executes each plot in a separate figure, Range must be P..Q where P
+and Q are figure numbers.
+    \termitem{vertical}{}
+Executes each plot in a subplot;
+subplots are arranged vertically top to bottom in the current figure.
+    \termitem{horizontal}{}
+Executes each plot in a subplot;
+subplots are arranged horizontally left to right in the current figure.
+    \termitem{\Sdot}{Type, [link(Axis)]}
+As for multplot type \arg{Type}, but link X or Y axis scales as determined by Axis,
+which can be `x, `y, or `xy.
+\end{description}
+
+Three argument form returns a list containing the Matlab handles to axes objects,
+one for each plot.
+
+    \predicate[semidet,multifile]{optionset}{2}{+Key:term, -Opts:list(ml_options)}
+Extensible predicate for mapping arbitrary terms to a list of options
+to be processed by \predref{compileoptions}{2}.
+\end{description}
+
+
+\printindex
+\end{document}