Go to the first, previous, next, last section, table of contents.
Author(s): Manuel Hermenegildo.
Version: 1.9#29 (1999/11/24, 16:47:1 MET)
Version of last change: 1.9#25 (1999/11/23, 0:39:18 MET)
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).
- DECLARATION: comment/2:
-
This declaration provides one of the main means for adding
machine readable comments to programs (the other one is adding
documentation strings to assertions).
- PROPERTY: docstring/1:
-
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.
- 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)
- Description:
Text
is a documentation string.
- PROPERTY: stringcommand/1:
-
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.
- 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.
@uref{URL}
-
introduces at point a reference to the
Universal Resource Locator (i.e., a
WWW address '
URL'.
@uref{
text}{
URL}
-
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.
- 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.
@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.
@footnote{
text}
-
places text in a
footnote.
@today
-
prints the current
date.
@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.
- Accents and special characters:
The following commands can be used to insert
accents and
special characters.
@`{o}
-
=>
ò
@'{o}
-
=>
ó
@^{o}
-
=>
ô
@..{o}
-
=>
ö
@~{o}
-
=>
õ
@={o}
-
=>
@=o
@.{o}
-
=>
@dotaccent{o}
@u{o}
-
=>
@u{o}
@v{o}
-
=>
@v{o}
@H{o}
-
=>
@H{o}
@t{oo}
-
=>
@tieaccent{oo}
@c{o}
-
=>
@,{o}
@d{o}
-
=>
@udotaccent{o}
@b{o}
-
=>
@ubaraccent{o}
@oe
-
=>
@oe{}
@OE
-
=>
@OE{}
@ae
-
=>
@ae{}
@AE
-
=>
@AE{}
@aa
-
=>
@aa{}
@AA
-
=>
@AA{}
@o
-
=>
@o{}
@O
-
=>
@O{}
@l
-
=>
@l{}
@L
-
=>
@L{}
@ss
-
=>
@ss{}
@?
-
=>
@questiondown{}
@!
-
=>
@exclamdown{}
@i
-
=>
@dotless{i}
@j
-
=>
@dotless{j}
@copyright
-
=>
©
@iso
-
=>
* ISO *
@bullet
-
=>
*
@result
-
=>
=>
- 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.
@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.
Usage: stringcommand(CO)
- Description:
CO
is a structure denoting a command that is admissible in strings inside assertions.
- REGTYPE: version_descriptor/1:
-
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)
- Description:
Descriptor
is a complete version descriptor.
- The following properties should hold globally:
Defines a regular type.
(
regtype/1
)
- REGTYPE: filetype/1:
-
Intended uses of a file:
filetype(module).
filetype(user).
filetype(include).
filetype(package).
filetype(part).
Usage: filetype(Type)
- Description:
Type
describes the intended use of a file.
- The following properties should hold globally:
Defines a regular type.
(
regtype/1
)
- REGTYPE: version_number/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)
- Description:
Version
is a complete version number
- The following properties should hold globally:
Defines a regular type.
(
regtype/1
)
- REGTYPE: ymd_date/1:
-
A Year/Month/Day structure denoting a date:
ymd_date(Y/M/D) :-
int(Y),
int(M),
int(D).
.
Usage: ymd_date(Date)
- Description:
Date
is a Year/Month/Day structure denoting a date.
- The following properties should hold globally:
Defines a regular type.
(
regtype/1
)
- REGTYPE: time_struct/1:
-
A struture containing time information:
time_struct(Hours:Minutes*Seconds+TimeZone) :-
int(Hours),
int(Minutes),
int(Seconds),
atm(TimeZone).
Usage: time_struct(Time)
- Description:
Time
contains time information.
- The following properties should hold globally:
Defines a regular type.
(
regtype/1
)
- REGTYPE: version_maintenance_type/1:
-
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)
- Description:
Type
a type of version maintenance for a file.
- The following properties should hold globally:
Defines a regular type.
(
regtype/1
)
Go to the first, previous, next, last section, table of contents.