<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet type="text/css" href="../styles.css" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
<title>Logtalk user manual: documenting programs</title>
<link rel="stylesheet" href="../styles.css" type="text/css" />
</head>
<body>
<div class="navtop">
<a href="../index.html">contents</a> > <a href="index.html">user manual</a>
</div>
<h1>Documenting Logtalk programs</h1>
<p>
Logtalk automatically generates a documentation file for each compiled entity (object, protocol, or category) in <a href="http://www.w3.org/XML/">XML</a> format. Contents of the XML file include the entity name, type, and compilation mode (static or dynamic), the entity relations with other entities, and a description of any declared predicates (name, compilation mode, scope, ...).
</p>
<p>
The XML documentation files can be enriched with arbitrary user-defined information, either about an entity or about its predicates, by using the two directives described below.
</p>
<h2>Documenting directives<a name="directives"></a></h2>
<p>
Logtalk supports two documentation directives for providing arbitrary user-defined information about an entity or a predicate. These two directives complement other Logtalk directives that also provide important documentation information like <a title="Consult reference manual" href="../refman/directives/uses1.html"><code>uses/1</code></a>, <a title="Consult reference manual" href="../refman/directives/calls1.html"><code>calls/1</code></a>, or <a title="Consult reference manual" href="../refman/directives/mode2.html"><code>mode/2</code></a>.
</p>
<h3>Entity directives<a name="entity"></a></h3>
<p>
Arbitrary user-defined entity information can be represented using the <a title="Consult reference manual" href="../refman/directives/info1.html"><code>info/1</code></a> directive:
</p>
<pre>
:- info([
Key1 is Value1,
Key2 is Value2,
...]).
</pre>
<p>
In this pattern, keys should be atoms and values should be ground terms. The following keys are pre-defined and may be processed specially by Logtalk:
</p>
<blockquote>
<dl>
<dt><code>comment</code></dt>
<dd>Comment describing entity purpose (an atom).</dd>
<dt><code>author</code></dt>
<dd>Entity author (an atom).</dd>
<dt><code>version</code></dt>
<dd>Version number (a number).</dd>
<dt><code>date</code></dt>
<dd>Date of last modification (formatted as Year/Month/Day).</dd>
<dt><code>parnames</code></dt>
<dd>Parameter names for parametric entities (a list of atoms).</dd>
</dl>
</blockquote>
<p>
For example:
</p>
<pre>
:- info([
version is 2.1,
author is 'Paulo Moura',
date is 2000/4/20,
comment is 'Building representation.',
diagram is 'UML Class Diagram #312']).
</pre>
<p>
Use only the keywords that make sense for your application and remember that you are free to invent your own keywords.
</p>
<h3>Predicate directives<a name="predicate"></a></h3>
<p>
Arbitrary user-defined predicate information can be represented using the
<a title="Consult reference manual" href="../refman/directives/info2.html"><code>info/2</code></a> directive:
</p>
<pre>
:- info(Functor/Arity, [
Key1 is Value1,
Key2 is Value2,
...]).
</pre>
<p>
Keys should be atoms and values should be ground terms. The following keys are pre-defined and may be processed specially by Logtalk:
</p>
<blockquote>
<dl>
<dt><code>comment</code></dt>
<dd>Comment describing predicate purpose (an atom).</dd>
<dt><code>argnames</code></dt>
<dd>Names of predicate arguments for pretty print output (a list of atoms).</dd>
<dt><code>allocation</code></dt>
<dd>Objects where we should define the predicate. Some possible values are <code>container</code>, <code>descendants</code>, <code>instances</code>, <code>classes</code>, <code>subclasses</code>, and <code>any</code>.</dd>
<dt><code>redefinition</code></dt>
<dd>Describes if the predicate can be redefined and in what way. Some possible values are <code>never</code>, <code>free</code>, <code>specialize</code>, <code>call_super_first</code>, <code>call_super_last</code>.</dd>
</dl>
</blockquote>
<p>
For example:
</p>
<pre>
:- info(color/1, [
comment is 'Table of defined colors.',
argnames is ['Color'],
constraint is 'Only a maximum of four visible colors allowed.']).
</pre>
<p>
Use only the keywords that make sense for your application and remember that you are free to invent your own keywords.
</p>
<h2>Processing and viewing documenting files<a name="processing"></a></h2>
<p>
The XML documenting files are (by default) automatically generated when you compile a Logtalk entity. For example, assuming the default filename extensions, compiling a <code>sort1.lgt</code> file generates a <code>sort1.pl</code> Prolog file and a <code>sort1.xml</code> XML file. The filename extension for each kind of file can be changed in the config files via the <code>'$lgt_file_extension'/2</code> predicate.
</p>
<p>
Each XML file contains references to two other files, a XML specification file and a XSL style-sheet file. The XML specification file can be either a DTD file (<code>logtalk.dtd</code>) or a XML Scheme file (<code>logtalk.xsd</code>). The <a href="http://www.w3.org/Style/XSL/">XSL</a> style-sheet file is responsible for converting the XML files to some desired format such as HTML or PDF. The default names for the XML specification file and the XSL style-sheet file are defined in the configuration files. The <code>xml</code> sub-directory in the Logtalk installation directory contains the XML specification files described above, along with several sample XSL style-sheet files and sample scripts for converting XML documenting files to several formats. Please read the <code>NOTES</code> file included in the directory for details. You may use the supplied sample files as a starting point for generating the documentation of your Logtalk applications.
</p>
<p>
There is a set of compilers options, used with the Logtalk <a title="Consult reference manual" href="../refman/builtins/logtalk_load2.html"><code>logtalk_load/2</code></a> or the <a title="Consult reference manual" href="../refman/builtins/logtalk_compile2.html"><code>logtalk_compile/2</code></a> built-in predicates, that can be used to control the generation of the XML documentation files. Please see the <a href="running.html#options">Running Logtalk</a> section of this manual for details.
</p>
<div class="navbottom">
<a href="errors.html">previous</a> | <a href="../glossary.html">glossary</a> | <a href="installing.html">next</a>
</div>
<div class="copyright">
Copyright © <a href="mailto:pmoura@logtalk.org">Paulo Moura</a> — <a href="http://www.logtalk.org">Logtalk.org</a>
</div>
<div class="footer">
<p><span class="bleft"><a href="http://validator.w3.org/check/referer">XHTML</a> + <a href="http://jigsaw.w3.org/css-validator/check/referer">CSS</a></span><span class="bright">Last updated on: August 6, 2004</span></p>
</div>
</body>
</html>