Author(s): Manuel Hermenegildo.
Version: 1.9#55 (2001/11/27, 22:33:9 CET)
Version of last change: 1.9#51 (2001/5/19, 11:43:22 CEST)
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
)
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
)This declaration provides one of the main means for adding machine readable comments to programs (the other one is adding documentation strings to assertions).
Usage 1: :- comment(CommentType,TitleText)
.
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.
:- comment(title,"Documentation-Oriented Assertions").
Usage 2: :- comment(CommentType,SubTitleText)
.
SubTitleText
will be used accordingly. Several of these declarations can appear per module, which is useful for, e.g., multiple line addresses.
:- comment(subtitle,"A Reference Manual").
CommentType
and subtitle
unify.
(= /2
)
SubTitleText
is a documentation string.
(docstring/1
)
Usage 3: :- comment(CommentType,AuthorText)
.
AuthorText
will be placed in the corresponding chapter or front page. There can be more than one of these declarations per module. In order for
author indexing to work properly, please use one author declaration per author. If more explanation is needed (who did what when, etc.) use an acknowledgements comment.
:- comment(author,"Alan Robinson").
CommentType
and author
unify.
(= /2
)
AuthorText
is a documentation string.
(docstring/1
)
Usage 4: :- comment(CommentType,AckText)
.
AckText
will be placed in the corresponding chapter or section. There can be only one of these declarations per module.
:- comment(ack,"Module was written by Alan, but others helped.").
CommentType
and ack
unify.
(= /2
)
AckText
is a documentation string.
(docstring/1
)
Usage 5: :- comment(CommentType,CopyrightText)
.
:- comment(copyright,"Copyright © 2001 FSF.").
CommentType
and copyright
unify.
(= /2
)
CopyrightText
is a documentation string.
(docstring/1
)
Usage 6: :- comment(CommentType,SummaryText)
.
SummaryText
will be used as the
abstract for the whole manual. There should be at most one of these declarations per module.
:- comment(summary,"This is a @bf{very} important library.").
CommentType
and summary
unify.
(= /2
)
SummaryText
is a documentation string.
(docstring/1
)
Usage 7: :- comment(CommentType,CommentText)
.
CommentText
will be used as the
introduction or
main body
of the corresponding chapter or manual. There should be at most one of these declarations per module. CommentText
may use subsections if substructure is needed.
:- comment(module,"This module is the @lib{comments} library.").
CommentType
and module
unify.
(= /2
)
CommentText
is a documentation string.
(docstring/1
)
Usage 8: :- comment(CommentType,CommentText)
.
CommentText
will be used in one of the last sections or appendices
of the corresponding chapter or manual. There should be at most one of these declarations per module. CommentText
may use subsections if substructure is needed.
:- comment(appendix,"Other module functionality...").
CommentType
and appendix
unify.
(= /2
)
CommentText
is a documentation string.
(docstring/1
)
Usage 9: :- comment(CommentType,CommentText)
.
:- comment(usage,"Do not use: still in development!").
CommentType
and usage
unify.
(= /2
)
CommentText
is a documentation string.
(docstring/1
)
Usage 10: :- comment(PredName,CommentText)
.
PredName
. When generating documentation for the module automatically, the text in Text
will be used as the introduction of the corresponding predicate/function/... description. There should be at most one of these declarations per predicate, function, property, or type.
:- comment(comment/2,"This declaration provides one of the main means for adding @concept{machine readable comments} to programs.").
PredName
is a Name/Arity structure denoting a predicate name:
predname(P/A) :- atm(P), nnegint(A).(
predname/1
)
CommentText
is a documentation string.
(docstring/1
)
Usage 11: :- comment(CommentType,CommentText)
.
Text
fields will be used as items in an itemized list of module or application bugs.
:- comment(bug,"Comment text still has to be written by user.").
CommentType
and bug
unify.
(= /2
)
CommentText
is a documentation string.
(docstring/1
)
Usage 12: :- comment(Version,CommentText)
.
Version
contains the
version number and date corresponding to the change and CommentText
an explanation of the change. Several of these declarations can appear per module. When generating documentation automatically, the texts in the different CommentText
fields typically appear as items in an itemized list of changes. The
emacs Ciao mode helps tracking version numbers by prompting for version comments when files are saved. This mode requires version comments to appear in reverse chronological order (i.e., the topmost comment should be the most recent one).
:- comment(version(1*1+21,1998/04/18,15:05*01+'EST'), "Added some missing comments. (Manuel Hermenegildo)").
Version
is a complete version descriptor.
(version_descriptor/1
)
CommentText
is a documentation string.
(docstring/1
)
Usage 13: :- comment(CommentType,VersionMaintenanceType)
.
emacs
Ciao mode.
:- comment(version_maintenance,dir('../version')).Version control info is kept in directory
../version
. See the definition of
version_maintenance_type/1
for more information on the different version maintenance modes. See the documentation on the
emacs Ciao mode in the Ciao manual for information on how to automatically insert version control
comment/2
declarations in files.
The version maintenance mode can also be set alternatively by inserting a comment such as:
%% Local Variables: %% mode: CIAO %% update-version-comments: "off" %% End:The lines above instruct emacs to put the buffer visiting the file in emacs Ciao mode and to turn version maintenance off. Setting the version maintenance mode in this way has the disadvantage that
lpdoc
will not be aware of the type of version maintenance being performed (the lines above are comments for Prolog). However, this can be useful in fact for setting the
version maintenance mode for packages and other files meant for inclusion in other files, since that way the settings will not affect the file in which the package is included.
CommentType
and version_maintenance
unify.
(= /2
)
VersionMaintenanceType
a type of version maintenance for a file.
(version_maintenance_type/1
)
Usage 14: :- comment(CommentType,PredName)
.
:- comment(doinclude,
PredName
).
forces documentation for predicate (or type, property, function, ...) PredName
to be included even if PredName
is not exported. Also, if PredName
is reexported from another module, a declaration :- comment(doinclude,
PredName
).
will force the documenation for PredName
to appear directly in this module.
:- comment(doinclude,p/3).
CommentType
and doinclude
unify.
(= /2
)
PredName
is a Name/Arity structure denoting a predicate name:
predname(P/A) :- atm(P), nnegint(A).(
predname/1
)
Usage 15: :- comment(CommentType,PredName)
.
:- comment(doinclude,...)
to be a list of predicate names.
CommentType
and doinclude
unify.
(= /2
)
PredName
is a list of predname
s.
(list/2
)
Usage 16: :- comment(CommentType,PredName)
.
:- comment(hide,p/3).
CommentType
and hide
unify.
(= /2
)
PredName
is a Name/Arity structure denoting a predicate name:
predname(P/A) :- atm(P), nnegint(A).(
predname/1
)
Usage 17: :- comment(CommentType,PredName)
.
:- comment(hide,...)
to be a list of predicate names.
CommentType
and hide
unify.
(= /2
)
PredName
is a list of predname
s.
(list/2
)
Usage 18: :- comment(CommentType,FileType)
.
include/1
or
use_package/1
declarations instead of
ensure_loaded/1
) and effect (since they are included, they 'export' operators, declarations, etc.). Typically, it is assumed by default that files which are not modules will be used as include files or packages. Thus, a
comment/2
declaration of this kind strictly only needs to be added to user-type files.
Example:
:- comment(filetype,user).There is another special case: the value
part
. This filetype is used to flag files which serve as introductions to boundaries between major
parts in large documents. See section Splitting large documents into parts for details.
CommentType
and filetype
unify.
(= /2
)
FileType
describes the intended use of a file.
(filetype/1
)
Usage 19: :- comment(CommentType,FileName)
.
FileName
. This is used for example when documenting packages to avoid the documenter from including documentation of certain other packages which the package being documented uses.
:- comment(nodoc,assertions).
CommentType
and nodoc
unify.
(= /2
)
FileName
is an atom.
(atm/1
)
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.