11 Motivation of choices

Literate programming is an established field. The TeX source is one of the first and best known examples of this approach, where input files are a mixture of TeX and Pascal source. External tools are used to untangle the common source and process one branch to produce the documentation, while the other is compiled to produce the program.

A program and its documentation consists of various different parts:

• The program text itself. This is the minimum that must be handed to the compiler to create an executable (module).
• Meta information about the program: author, modifications, license, etc.
• Documentation about the overall structure and purpose of the source.
• Description of the interface: public predicates, their types, modes and whether or not they are deterministic as wel as an informative text on each public predicate.
• Description of key private predicates necessary to understand how the public interface is realised.

Structured comments or directives

Comments can be added through Prolog directives, a route taken by Ciao Prolog with lpdoc Hermenegildo, 2000 and Logtalk Moura, 2003. We feel structured comments are a better alternative for the following reasons:

• Prolog programmers are used to writing comments as Prolog comments.
• Using Prolog strings requires unnatural escape sequences for string quotes and long literal values tend to result in hard to find quote-mismatches. Python uses comments in long strings, solving this problem by using three double quotes to open and close long comments.
• Comments should not look like code, as that makes it more difficult to find the actual code.

We are aware that the above problems can be dealt with using syntax-aware editors. Only a few editors are sufficiently powerful to support this correctly, though, and we do not expect the required advanced modes to be widely available. If comments are used, we do not need to force users into using a particular editor.

Wiki or HTML

JavaDoc uses HTML as markup inside the structured comments. Although HTML is more widely known than ---for example--- LaTeX or TeXinfo, we think the Wiki approach is sufficiently widely known today. Using text with minimal layout conventions taken largely from plaintext newsnet and E-mail, Wiki input is much easier to read in the source-file than HTML without syntax support from an editor.

Types and modes

Types and modes are not a formal part of the Prolog language. Nevertheless, their role goes beyond pure documentation. The test-system can use information about non-determinism to validate that deterministic calls are indeed deterministic. Type information can be used to analyse coverage from the test-suite, to generate runtime type verification or to perform static type-analysis. We have chosen to use a structured comment with formal syntax for the following reasons:

• As comments, they stay together with the comment block of a predicate. We feel it is best to keep documentation as close as possible to the source.
• As we parse them separately, we can pick up argument names and create a readable syntax without introducing possibly conflicting operators.
• As comments, they do not introduce incompatibilities with other Prolog systems.

Few requirements

SWI-Prolog aims at platform independence. We want tools to rely as much as possible on Prolog itself. Therefore, the entire infrastructure is written in Prolog. Output as HTML is suitable for browsing and not very high quality printing on virtually all platforms. Output to LaTeX requires more infrastructure for processing and allows for producing high-quality PDF documents.