Literate Prolog

Appeared in Volume 9/4, November 1996

Keywords: style.

Anders Green
gren@coli.uni-sb.de
17th June 1996

Is there anyone out there who has been using literate programming techniques with Prolog?

In literate programming you make your documentation a part of the program (or your program a part of your documentation).

A simple example: you write your Prolog code and document it with LaTeX commands inside the comments of the code. You can then use a literate programming tool to extract and typset the documentation.

lee@cs.mu.oz.au
Lee Naish
18th June 1996

Bert Thompson, an Honours student here in 1993, wrote some literate Prolog code. He coded a little Gofer script to translate literate Prolog files into Latex (adding \begin{verbatim}, fixing tabs, etc). The literate Prolog to Prolog translation was implemented in (literate) Prolog.

lieske@coli.uni-sb.de
Christian Lieske
18th June 1996

Anders Green writes:
In Literate Programming you make your documentation a part of the program...

I applied this definition of literate programming to a large implementation I carried out in SICStus Prolog, with the addition of the object-oriented paradigm.

I attached a method called 'showDoc' to each class. showDoc describes the class' methods, instance variables, etc. The documentation can be obtained by backtracking over all the showDoc methods in all the classes.

poole@cs.ubc.ca
David Poole
17th June 1996

I have a low-tech solution:

write latex documentation
\begin{verbatim} */
prolog code
/* \end{verbatim}
latex stuff
\begin{verbatim} */
prolog code
/* \end{verbatim}
etc.

The only problem is that it requires a one character change at the start to apply either Prolog or Latex to it. At the top of my Latex/Prolog file I have:

% This is both a Latex file and a Prolog file.
% The only difference is that the Latex version comments 
% out the following line:
 /*

This approach works quite well, and doesn't require anything fancy. Of course, it doesn't make my documentation more literate, just easier to read!

gerd@uni-koblenz.de
Gerd Neugebauer
18th June 1996

I saw a solution like David Poole's some years ago (in Theorist?) and developed it further. I didn't like the /* in the output and the change of a character to make the documentation. The result is the LaTeX package pl which can be found on the CTAN in the directory:
tex-archive/macros/latex/contrib/other/gene/pl/

Unfortunately, the package's documentation needs polishing, but you can use the example to see how it works.

As far as I know there is a version of the WEB-System which is able to handle Prolog. If someone really needs literate programming support this might be the right place to start.

dwyer@cs.adelaide.edu.au
Barry Dwyer
18th June 1996

Are you aware of FunnelWeb? This is a Web-like literate programming tool that is language and typesetter independent. It is free. The only penalty is that it does not automate the layout of programs in the documentation. They will appear with whatever layout you give them. It deservedly has a wide following.

Here is part of a (fairly) recent communication I received concerning FunnelWeb. I suggest you contact A.B. Coates if you want more details.

----
Subject: FunnelWeb 3.05AC now available!
coates@physics.uq.oz.au
A.B.Coates
21st December, 1995

FunnelWeb 3.05AC, the latest release of my enhanced version of FunnelWeb, is now available for anonymous FTP. FunnelWeb is a language-independent literate programming tool, most directly comparable to noweb and nuweb. It has a powerful parameterised macro facility. FunnelWeb 3.05AC can produce documentation in (La)TeX or HTML format.

More information is available from my FunnelWeb page:
http://www.physics.uq.edu.au:8001/people/coates/funnelweb.html

FunnelWeb 3.05AC has been uploaded to the CTAN servers (ftp://ftp.shsu.edu, ftp://ftp.tex.ac.uk, ftp://ftp.dante.de, and possibly soon at ftp://ftp.cs.rmit.edu.au) in the directory tex-archive/web/funnelAC.

If you have any questions or comments, contact:
coates@physics.uq.edu.au
----

timm@insect.sd.monash.edu.au
Tim Menzies
18th June 1996

I do the same as David Poole, with some little twists. I generate an index of my source code, and add labels so that I can refer to my Prolog code as "Listing 3.2 on page 45"

/*
\documentclass[a4paper]{book}
\usepackage{cite,varioref,makeidx,fancyheadings,lastpage,epsf,epic,ecltree}

Note the "/*" at the end, and the inclusion of makeidx and varioref. Secondly, I define a new environment that prints a unique number to the right of my Prolog code:

\newenvironment{prol}{\medskip\par\noindent
  \begin{equation}\footnotesize\begin{minipage}{.9\textwidth}}{%
  \end{minipage}\normalsize\end{equation}}

\newcommand{\src}[1]{Listing \vref{#1}}

Then I generate an index to the source code:
\makeindex

Now, if I want to include some sample code, I use David's trick, with no Prolog comment characters.

\begin{prol}\begin{verbatim}
:-  defRecord(person, [name, age, duties]),
    create(person, [age=5, duties=[]], P0),
    o([age++, duties<<eat], P0, P),
    print(P), nl, write(P), nl, printRec(P).

[Rec:person / 3]
person(G4920, 6, [eat])

name = G4920
age = 6
duties = [eat]
\end{verbatim}
\label{defRecordDemo}
\index{defRecord/2!usage}
\index{defRecord/2!manual}
\end{prol}

Note the indexing commands at the end and the label command. Now, in the text, I can type "as described in \src{defRecordDemo}" which will print (thanks to varioref) as "Listing 3.2 on page 45". Note that varioref is quite smart. If the listing is on the current page, it just says "Listing 3.2". It also generates "on the current page" and "on the previous page".

If I want "real" code, I add the Prolog comment characters:

\begin{prol}\begin{verbatim}*/
defRecord(Functor, Inits) :-
    undefineRecord(Functor),
    length(Inits, Arity),
    magicRecordNames(Functor, MagicName),
    defRecord1(Functor, Arity, Inits, MagicName, Assertion),
    assert(Assertion),
    fail.
defRecord(_, _).

magicRecordNames(Functor, Out) :-
    name(Functor, L0),
    name('0', Zero),
    append(L0, Zero, Out0),
    name(Out, Out0).
/*\end{verbatim}\index{defRecord/2}\index{magicRecordNames/2}\end{prol}

Again, note the indexing commands.

At the end of the document, I generate an index and close with a final "*/":

{\small
\printindex
}
\end{document}*/

To make my document latexable, I run "sed -f zap.sed" where zap.sed is:

s/\/\*//
s/\*\///

If I want to extract all my Prolog into an "in.pl" file:

gawk '
    BEGIN  { yes = 0  }
    $0 ~ /\/\*/ { yes = 0  print ""}
    $0 ~ /\*\// { yes = 1 }
    yes == 1  { print $0 }
' in.tex | grep -v verbatim | grep -v "end{document" > in.pl

I control the index generation as follows:

makeindex -s myhead.ist in.idx

myhead.ist is:

cat << END > myhead.ist
heading_prefix "{\\\bf \\\hfill "
heading_suffix "\\\hfill}\\\nopagebreak\n"
headings_flag 1
delim_0 "\\\dotfill "
delim_1 "\\\dotfill "
delim_2 "\\\dotfill "
END

All this is controlled by shell scripts, so I just type:
mylatex in

I get an in.pl file generated automatically.

Note that viroref has a known bug. If the string "Listing 3.2 on the previous page" spills over a page break, then Latex prints a warning message. I get this message occassionally, and I have to add a few new line breaks to sort it out.

pmoura@mat.uc.pt
Paulo Moura
19th June 1996

In Logtalk, my object-oriented extension to Prolog, I make all the documentation part of the objects definitions (in a similar way to Christian Lieske). Then I have a library of objects that extract the documentation and output it in LaTeX, HTML, or plain text format. One advantage of this approach is that you can use the documentation (that describes objects and slots) for other purposes, such as method signature checking or for metrics. If you are interested take a look at:
http://www.ci.uc.pt/logtalk/logtalk.html