Author(s): Manuel Hermenegildo.
Version: 1.9#50 (2000/4/18, 3:22:13 CEST)
Version of last change: 1.9#30 (1999/12/5, 20:30:56 CET)
This defines the admissible uses of the
comment/2
declaration (which is used mainly for adding
machine readable comments to programs), the
formatting commands which can be used in the text strings inside these comments, and some related properties and data types. These declarations are ignored by the compiler in the same way as classical comments. Thus, they can be used to document the program source in place of (or in combination with) the normal comments typically inserted in the code by programmers. However, because they are more structured and they are machine-readable, they can also be used to generate printed or on-line documentation automatically, using the
lpdoc
automatic documentation generator. These
textual comments are meant to be complementary to the formal statements present in
assertions (see the
assertions
library).
comments
)comment/2
declarations that this library defines is to include instead the
assertions
package, which provides efficient support for all assertion- and comment-related declarations, using one of the following declarations, as appropriate:
:- module(...,...,[assertions]). :- use_package(assertions).
comments
)This declaration provides one of the main means for adding machine readable comments to programs (the other one is adding documentation strings to assertions).
Defines the format of the character strings which can be used in machine readable comments (
comment/2
declarations) and assertions. These character strings can include certain
formatting commands.
@
", "{
," and "}
". To produce these characters the following
escape sequences should be used, respectively: @@
, @{
, and @}
.
@
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.
Defines the set of structures which can result from parsing a formatting command admissible in comment strings inside assertions.
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.
@index{
text}
@cindex{
text}
@concept{
text}
@pred{
predname}
@op{
operatorname}
@decl{
declname}
@lib{
libname}
@apl{
aplname}
@file{
filename}
@var{
varname}
pred/1
declaration, such names should be enclosed in @var
commands for the automatic documentation system to work correctly.
@cite{keyword}
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}
@uref{URL}
@uref{
text}{
URL}
@email{
address}
@email{
text}{
address}
@comment{
text}
@begin{itemize}
@item
command.
@item
@end{itemize}
@begin{enumerate}
@item
command.
@end{enumerate}
@begin{description}
@item{
itemtext}
command.
@item{
itemtext}
@end{description}
@begin{verbatim}
@end{verbatim}
@begin{cartouche}
@end{cartouche}
@section{
text}
info
format, do not use :
or -
or ,
in section, subsection, title (chapter), etc. headings.
@subsection{
text}
@footnote{
text}
@today
@hfill
@bf{
text}
@em{
text}
@tt{
text}
@key{
key}
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}
@p
@noindent
@`{o}
@'{o}
@^{o}
@..{o}
@~{o}
@={o}
@.{o}
@u{o}
@v{o}
@H{o}
@t{oo}
@c{o}
@d{o}
@b{o}
@oe
@OE
@ae
@AE
@aa
@AA
@o
@O
@l
@L
@ss
@?
@!
@i
@j
@copyright
@iso
@bullet
@result
@include{
filename}
@includeverbatim{
filename}
@
's, etc.
@includefact{
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}
@image{
epsfile}
@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.
Usage: stringcommand(CO)
CO
is a structure denoting a command that is admissible in strings inside assertions.
A structure denoting a complete version description:
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.
Intended uses of a file:
filetype(module). filetype(user). filetype(include). filetype(package). filetype(part).
Usage: filetype(Type)
Type
describes the intended use of a file.
comments
)
Version
is a structure denoting a complete version number (major version, minor version, and patch number):
version_number(Major*Minor+Patch) :- int(Major), int(Minor), int(Patch).
Usage: version_number(Version)
Version
is a complete version number
A Year/Month/Day structure denoting a date:
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.
A struture containing time information:
time_struct(Hours:Minutes*Seconds+TimeZone) :- int(Hours), int(Minutes), int(Seconds), atm(TimeZone).
Usage: time_struct(Time)
Time
contains time information.
Possible kinds of version maintenance for a file:
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 comment(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.
Go to the first, previous, next, last section, table of contents.