Documentation Mark-up Language and Declarations

• All printable characters are admissible in documentation strings except “@”, “{,” and “}”. To produce these characters the following escape sequences should be used, respectively: @@, @{, and @}.

• In order to allow better formatting of on-line and printed manuals, in addition to normal text, certain formatting commands can be used within these strings. The syntax of all these commands is:

  @command

  (followed by either a space or {}), or

  @command{body}

  where command is the command name and body is the (possibly empty) command body.

  The set of commands currently admitted can be found in the documentation for the predicate stringcommand/1.

Usage:docstring(Text)

Text is a documentation string.

In order to make it possible to produce documentation in a wide variety of formats, the command set is kept small. The names of the commands are intended to be reminiscent of the commands used in the LaTeX text formatting system, except that “@” is used instead of “\.” Note that \ would need to be escaped in ISO-Prolog strings, which would make the source less readable (and, in any case, many ideas in LaTeX were taken from scribe, where the escape character was indeed @!).

The following are the currently admissible commands.

• Formatting commands:

  The following commands are used to format certain words or sentences in a special font, build itemized lists, introduce sections, include examples, etc.

  @comment{text}

  text will be treated as a comment and will be ignored.

  @begin{itemize}

  marks the beginning of an itemized list. Each item should be in a separate paragraph and preceded by an @item command.

  @item

  marks the beginning of a new item in an itemized list.

  @end{itemize}

  marks the end of an itemized list.

  @begin{enumerate}

  marks the beginning of an enumerated list. Each item should be in a separate paragraph and preceded by an @item command.

  @end{enumerate}

  marks the end of an enumerated list.

  @begin{description}

  marks the beginning of a description list, i.e., a list of items and their description (this list describing the different allowable commads is in fact a description list). Each item should be in a separate paragraph and contained in an @item{itemtext} command.

  @item{itemtext}

  marks the beginning of a new item in description list, and contains the header for the item.

  @end{description}

  marks the end of a description list.

  @begin{verbatim}

  marks the beginning of fixed format text, such as a program example. A fixed-width, typewriter-like font is used.

  @end{verbatim}

  marks the end of formatted text.

  @begin{cartouche}

  marks the beginning of a section of text in a framed box, with round corners.

  @end{cartouche}

  marks the end of a section of text in a framed box.

  @begin{alert}

  marks the beginning of a section of text in a framed box, for alert messages.

  @end{alert}

  marks the end of the alert message.

  @section{text}

  starts a section whose title is text. Due to a limitation of the info format, do not use : or - or , in section, subsection, title (chapter), etc. headings.

  @subsection{text}

  starts a subsection whose title is text.

  @subsubsection{text}

  starts a subsubsection whose title is text.

  @footnote{text}

  places text in a footnote.

  @hfill

  introduces horizontal filling space (may be ignored in certain formats).

  @bf{text}

  text will be formatted in bold face or any other strong face.

  @em{text}

  text will be formatted in italics face or any other emphasis face.

  @tt{text}

  text will be formatted in a fixed-width font (i.e., typewriter-like font).

  @key{key}

  key is the identifier of a keyboard key (i.e., a letter such as a, or a special key identifier such as RET or DEL) and will be formatted as LFD or in a fixed-width, typewriter-like font.

  @sp{N}

  generates N blank lines of space. Forces also a paragraph break.

  @p

  forces a paragraph break, in the same way as leaving one or more blank lines.

  @noindent

  used at the beginning of a paragraph, states that the first line of the paragraph should not be indented. Useful, for example, for avoiding indentation on paragraphs that are continuations of other paragraphs, such as after a verbatim.

• Indexing commands:

  The following commands are used to mark certain words or sentences in the text as concepts, names of predicates, libraries, files, etc. The use of these commands is highly recommended, since it results in very useful indices with little effort.

  @index{text}

  text will be printed in an emphasized font and will be included in the concept definition index (and also in the usage index). This command should be used for the first or definitional appearance(s) of a concept. The idea is that the concept definition index can be used to find the definition(s) of a concept.

  @cindex{text}

  text will be included in the concept index (and also in the usage index), but it is not printed. This is used in the same way as above, but allows sending to the index a different text than the one that is printed in the text.

  @concept{text}

  text will be printed (in a normal font). This command is used to mark that some text is a defined concept. In on-line manuals, a direct access to the corresponding concept definition may also be generated. A pointer to the place in which the @concept command occurs will appear only in the usage index.

  @pred{predname}

  predname (which should be in functor/arity form) is the name of a predicate and will be printed in fixed-width, typewriter-like font. This command should be used when referring to a predicate (or a property or type) in a documentation string. A reference will be included in the usage index. In on-line manuals, a direct access to the corresponding predicate definition may also be generated.

  @op{operatorname}

  operatorname (which should be in functor/arity form) is the name of an operator and will be printed in fixed-width, typewriter-like font. This command should be used when referring to an operator in a documentation string. A reference will be included in the usage index. In on-line manuals, a direct access to the corresponding operator definition may also be generated.

  @decl{declname}

  declname (which should be in functor/arity form) is the name of a declaration and will be printed in fixed-width, typewriter-like font. This command should be used when referring to a declaration in a documentation string. A reference will be included in the usage index. In on-line manuals, a direct access to the corresponding declaration definition may also be generated.

  @lib{libname}

  libname is the name of a library and will be printed in fixed-width, typewriter-like font. This command should be used when referring to a module or library in a documentation string. A reference will be included in the usage index. In on-line manuals, a direct access to the corresponding module definition may also be generated.

  @apl{aplname}

  aplname is the name of an application and will be printed in fixed-width, typewriter-like font. This command should be used when referring to an application in a documentation string. A reference will be included in the usage index.

  @file{filename}

  filename is the name of a file and will be printed in fixed-width, typewriter-like font. This command should be used when referring to a file in a documentation string. A reference will be included in the usage index.

  @var{varname}

  varname is the name of a variable and will be formatted in an emphasized font. Note that when referring to variable names in a pred/1 declaration, such names should be enclosed in @var commands for the automatic documentation system to work correctly.

• Referencing commands:

  The following commands are used to introduce bibliographic citations and references to sections, urls, email addresses, etc.

  @cite{keyword}

  keyword is the identifier of a bibliographic entry. Such entry is assumed to reside in on of a number of bibtex files (.bib files) . A reference in brackets ([ ]) is inserted in the text an the full reference is included at the end, with all other references, in an appendix. For example, @cite{iso-prolog} will introduce a citation to a bibliographic entry whose keyword is iso-prolog. The list of bibliography files which will be searched for a match is determined by the BIBFILES variable of the lpdoc SETTINGS file.

  @ref{section title}

  introduces at point a reference to the section or node section title, where section title must be the exact text of the section title.

  @href{URL}

  introduces at point a reference to the Universal Resource Locator (i.e., a WWW address 'URL'.

  @href{URL}{text}

  introduces at point a reference to the Universal Resource Locator URL, associated to the text text.

  @email{address}

  introduces at point a reference to email address address.

  @email{text}{address}

  introduces at point a reference to the email address address, associated to the text text.

  @author{text}

  text will be printed (in a normal font). This command is used to reference the name of an author (not necessarily establishing the module authorship).

• Date and Version:

  @today

  prints the current date.

  @version

  prints the version of the current manual.

• Mathematics:

  The following commands are used to format text in mathematical .

  @math{text}

  in-line typeset the text formula.

  @begin{displaymath}

  marks the beginning of a formula (useful for long formulas).

  @end{displaymath}

  marks the end of the (long) formula.

  @defmathcmd{cmd}{n}{def}

  defines the math command cmd, taking n arguments, which is expanded as def. Arguments are denotated as #1, ..., #n inside def.

  @defmathcmd{cmd}{def}

  defines the math command cmd, which is expanded as def (with no arguments).

• Inclusion commands:

  The following commands are used to include code or strings of text as part of documentation. The latter may reside in external files or in the file being documented. The former must be part of the module being documented. There are also commands for inserting and scaling images.

  @include{filename}

  the contents of filename will be included in-line, as if they were part of the string. This is useful for common pieces of documentation or storing in a separate file long explanations if they are perceived to clutter the source file.

  @includeverbatim{filename}

  as above, but the contents of the file are included verbatim, i.e., commands within the file are not interpreted. This is useful for including code examples which may contain @'s, etc. Note that this only means that the file will be included as is. If you want the string to be represented in verbatim mode in the output, you must surround the @includeverbatim{filename} with @begin{verbatim} and @end{verbatim}.

  @includefact{factname}

  it is assumed that the file being documented contains a fact of the predicate factname/1, whose argument is a character string. The contents of that character string will be included in-line, as if they were part of the documentation string. This is useful for sharing pieces of text between the documentation and the running code. An example is the text which explains the usage of a command (options, etc.).

  @includedef{predname}

  it is assumed that the file being documented contains a definition for the predicate predname. The clauses defining this predicate will be included in-line, in verbatim mode, as if they were part of the documentation string.

  @image{epsfile}

  including an image at point, contained in file epsfile. The image file should be in encapsulated postscript format.

  @image{epsfile}{width}{height}

  same as above, but width and height should be integers which provide a size (in points) to which the image will be scaled.

• Accents and special characters:

  The following commands can be used to insert accents and special characters.

  @`{o}

  ⇒ ò

  @'{o}

  ⇒ ó

  @^{o}

  ⇒ ô

  @..{o}

  ⇒ ö

  @"{o}

  ⇒ ö

  @~{o}

  ⇒ õ

  @={o}

  ⇒ o

  @.{o}

  ⇒ o

  @u{o}

  ⇒ o

  @v{o}

  ⇒ o

  @H{o}

  ⇒ o

  @t{oo}

  ⇒ oo

  @c{o}

  ⇒ o

  @d{o}

  ⇒ o

  @b{o}

  ⇒ o

  @oe

  ⇒ œ

  @OE

  ⇒ Œ

  @ae

  ⇒ æ

  @AE

  ⇒ Æ

  @aa

  ⇒ å

  @AA

  ⇒ Å

  @o

  ⇒ ø

  @O

  ⇒ Ø

  @l

  ⇒ l

  @L

  ⇒ L

  @ss

  ⇒ ß

  @?

  ⇒ ¿

  @!

  ⇒ ¡

  @i

  ⇒ i

  @j

  ⇒ j

  @copyright

  ⇒ ©

  @iso

  ⇒ ISO

  @bullet

  ⇒ º

  @result

  ⇒ ⇒

Usage:stringcommand(CO)

CO is a structure denoting a command that is admissible in strings inside assertions.

version_descriptor([]).
version_descriptor(version(Version,Date)) :-
        version_number(Version),
        ymd_date(Date).
version_descriptor(version(Version,Date,Time)) :-
        version_number(Version),
        ymd_date(Date),
        time_struct(Time).

Usage:version_descriptor(Descriptor)

Descriptor is a complete version descriptor.

filetype(module).
filetype(user).
filetype(include).
filetype(package).
filetype(part).

Usage:filetype(Type)

Type describes the intended use of a file.

Usage 1::- doc(CommentType,TitleText).

Provides a title for the module, library, or application. When generating documentation automatically, the text in TitleText will be used appropriately (e.g., in the cover page as document title or as chapter title if part of a larger document). This will also be used as a brief description of the manual in on-line indices. There should be at most one of these declarations per module.

:- doc(title,"Documentation-Oriented Assertions").

:- doc(title,"Dr. Strangelove").
:- doc(subtitle,"How I Learned to Stop Worrying and Love the Bomb").

:- doc(subtitle_extra,"A Reference Manual").
:- doc(subtitle_extra,"Technical Report 1/1.0").

:- doc(author,"Alan Robinson").

:- doc(address,"Syracuse University").

:- doc(ack,"Module was written by Alan, but others helped.").

:- doc(copyright,"Copyright © 2001 FSF.").

:- doc(summary,"This is a @bf{very} important library.").

:- doc(module,"This module is the @lib{comments} library."). 

:- doc(appendix,"Other module functionality..."). 

:- doc(usage,"Do not use: still in development!"). 

:- doc(section,"Main Steps of the Algorithm").

:- doc(subsection,"Auxiliary Definitions").

:- doc(subsubsection,"Auxiliary Definitions").

:- doc(doc/2,"This declaration provides one of the main 
   means for adding @concept{machine readable comments} to 
   programs."). 

:- doc(bug,"Comment text still has to be written by user.").

:- doc(version(1*1+21,1998/04/18,15:05*01+'EST'), "Added some
   missing comments.  (Manuel Hermenegildo)").

:- doc(version_maintenance,dir('../version')).

%% Local Variables: 
%% mode: CIAO
%% update-version-comments: "off"
%% End:

:- doc(doinclude,p/3).

:- doc(hide,p/3).

:- doc(filetype,user).

:- doc(nodoc,assertions).

version_number(Major*Minor+Patch) :-
        int(Major),
        int(Minor),
        int(Patch).

Usage:version_number(Version)

Version is a complete version number

ymd_date(Y/M/D) :-
        int(Y),
        int(M),
        int(D).

Usage:ymd_date(Date)

Date is a Year/Month/Day structure denoting a date.

time_struct(Hours:Minutes*Seconds+TimeZone) :-
        int(Hours),
        int(Minutes),
        int(Seconds),
        atm(TimeZone).

Usage:time_struct(Time)

Time contains time information.

version_maintenance_type(on).
version_maintenance_type(off).
version_maintenance_type(dir(Path)) :-
        atm(Path).

• on: version numbering is maintained locally in the file in which the declaration occurs, i.e., an independent version number is kept for this file and the current version is given by the most recent doc(version(...),...) declaration.

• off: no version numbering maintained.

• dir(Path): version numbering is maintained (globally) in directory Path. This is useful for maintaining a common global version for an application which involves several files.

The automatic maintenance of version numbers is typically done by the Ciao emacs mode.

Usage:version_maintenance_type(Type)

Type a type of version maintenance for a file.