:- export comment/2,
docstring/1,stringcommand/1,
version_descriptor/1.
:- comment(title,"Enhancing Documentation with Machine-Readable Comments").
:- comment(author,"Manuel Hermenegildo").
:- comment(module,"This defines the admissible uses of the
@decl{comment/2} declaration (which is used mainly for adding
@concept{machine readable comments} to programs), the
@concept{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 @apl{lpdoc} automatic documentation
generator. These @index{textual comments} are meant to be
complementary to the formal statements present in
@index{assertions} (see the @lib{assertions} library).
").
:- comment(usage,"It is not necessary to use this library in user
programs. Recognition of comments is handled automatically by
xsbdoc and the XSB compiler.
").
% ----------------------------------------------------------------------------
% Comment-related definitions
% ----------------------------------------------------------------------------
:- comment(comment/2,"This declaration provides one of the main means
for adding @index{machine readable comments} to programs (the
other one is adding @index{documentation strings} to assertions).").
:- pred comment(title,TitleText)
:: [success_prop(docstring(TitleText)),
comment("Provides a @index{title} for the library or
application. When generating documentation automatically, the
text in @var{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 tables of content, etc. There should be at most one of
these declarations per module.
@item @em{Example:}
@begin{verbatim}
:- comment(title,""Documentation-Oriented Assertions"").
@end{verbatim}
")].
:- pred comment(subtitle,SubTitleText)
:: [success_prop(docstring(SubTitleText)),
comment("Provides @index{subtitle} lines. This can be, e.g., an
explanation of the application to add to the title, the address
of the author(s) of the application, etc. Several of these
declarations can appear per
module, which is useful for, say, multiple line addresses.
@item @em{Example:}
@begin{verbatim}
:- comment(subtitle,""A Reference Manual"").
@end{verbatim}
")].
:- pred comment(author,AuthorText)
::[success_prop(docstring(AuthorText)),
comment("Specifies the @index{author}(s) of the module or application. If
present, the text in @var{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 @concept{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 or subtitle comment.
@item @em{Example:}
@begin{verbatim}
:- comment(author,""Alan Robinson"").
@end{verbatim}
")].
:- pred comment(ack,AckText)
::[success_prop(docstring(AckText)),
comment("Provides @index{acknowledgements} for the module. If present,
the
text in @var{AckText} will be placed in the corresponding chapter
or section. There can be only one of these declarations per
module.
@item @em{Example:}
@begin{verbatim}
:- comment(ack,""Module was written by Alan, but others helped."").
@end{verbatim}
")].
:- pred comment(copyright,CopyrightText)
::[success_prop(docstring(CopyrightText)),
comment("Provides a @index{copyright} text. This normally appears
somewhere towards the beginning of a printed manual. There should
be at most one of these declarations per module.
@item @em{Example:}
@begin{verbatim}
:- comment(copyright,""Copyright @copyright{} 2001 FSF."").
@end{verbatim}
")].
:- pred comment(summary,SummaryText)
:: [success_prop(docstring(SummaryText)),
comment("Provides a brief global explanation of the application or
library. The text in @var{SummaryText} will be used as the
@index{abstract} for the whole manual. There should be at most
one of these declarations per module.
@item @em{Example:}
@begin{verbatim}
:- comment(summary,""This is a @@bf@{very@} important library."").
@end{verbatim}
")].
:- pred comment(module,CommentText)
:: [success_prop(docstring(CommentText)),
comment("Provides the main comment text for the module or
application. Tthe
text in @var{CommentText} will be used as the
@index{introduction} or @index{main body} @cindex{module comment}
of the corresponding chapter or manual. There should be at most
one of these declarations per module. @var{CommentText} may use
subsections if substructure is needed.
@item @em{Example:}
@begin{verbatim}
:- comment(module,""This module is the @@lib@{comments@} library."").
@end{verbatim}
")].
:- pred comment(appendix,CommentText)
::[success_prop(docstring(CommentText)),
comment("Provides additional comments text for a module or
application. The
text in @var{CommentText} will be used in one of the last
sections or appendices @cindex{appendix} of the corresponding
chapter or manual. There should be at most one of these
declarations per module. @var{CommentText} may use subsections if
substructure is needed.
@item @em{Example:}
@begin{verbatim}
:- comment(appendix,""Other module functionality..."").
@end{verbatim}
")].
:- pred comment(usage,CommentText)
:: [success_prop(docstring(CommentText)),
comment("Provides a description of how the library should be
loaded. Normally, this information is gathered automatically when
generating documentation automatically. This declaration is meant
for use when the module needs to be treated in some special way.
There should be at most one of these declarations per module.
@item @em{Example:}
@begin{verbatim}
:- comment(usage,""Do not use: still in development!"").
@end{verbatim}
")].
:- pred comment(PredName,CommentText)
:: [success_prop(docstring(CommentText)),
comment("Provides an introductory comment for a given predicate,
function, property, type, etc., denoted by @var{PredName}. The
text
in @var{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.
@item @em{Example:}
@begin{verbatim}
:- comment(comment/2,""This declaration provides one of the main
means for adding @@concept@{machine readable comments@} to
programs."").
@end{verbatim}
")].
:- pred comment(bug,CommentText)
:: [success_prop(docstring(CommentText)),
comment("Documents a known @index{bug} or @index{planned improvement}
in the module or application. Several of these declarations can
appear per module. When generating documentation automatically,
the text in the @var{Text} fields will be used as items in an
itemized list of module or application bugs.
@item @em{Example:}
@begin{verbatim}
:- comment(bug,""Comment text still has to be written by user."").
@end{verbatim}
")].
:- pred comment(Version,CommentText)
:: [success_prop((version_descriptor(Version),docstring(CommentText))),
comment( "Provides a means for keeping a @index{log of
changes}. @var{Version} contains the @index{version number} and
date corresponding to the change and @var{CommentText} an
explanation of the change. Several of these declarations can
appear per module. When generating documentation automatically,
the texts in the different @var{CommentText} fields typically
appear as items in an itemized list of changes. The
@concept{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).
@item @em{Example:}
@begin{verbatim}
:- comment(version(1*1+21,1998/04/18,15:05*01+'EST'), ""Added some
missing comments. (Manuel Hermenegildo)"").
@end{verbatim}
")].
:- pred comment(doinclude,PredName)
:: [comment( "This usage provides control over which predicates
are included in the documentation. Normally, only exported
predicates are documented. A declaration @tt{:-
comment(doinclude,}@var{PredName}@tt{).} forces documentation for
predicate @var{PredName} to be
included even if @var{PredName} is not exported (and is not included in a
@tt{document_export/1} statement).
@item @em{Example:}
@begin{verbatim}
:- comment(doinclude,p/3).
@end{verbatim}
")].
:- pred comment(doinclude,PredName)
:: [comment("As above, but allows the second argument of @tt{:-
comment(doinclude,...)} to be a list of predicate names.")].
:- pred comment(hide,PredName)
:: [comment("This usage has an effect opposite to the previous usage: it
signals that an exported predicate should @em{not} be
included in the documentation.
@item @em{Example:}
@begin{verbatim}
:- comment(hide,p/3).
@end{verbatim}
")].
:- pred comment(hide,PredName)
:: [comment("A different usage which allows the second argument of @tt{:-
comment(hide,...)} to be a list of predicate names.")].
% ----------------------------------------------------------------------------
% Types and properties
% ----------------------------------------------------------------------------
:- comment(version_descriptor/1,"A structure denoting a complete
version description: @includedef{version_descriptor/1}").
/*
:- regtype version_descriptor(Descriptor)
# "@var{Descriptor} is a complete 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).
% ----------------------------------------------------------------------------
:- comment(doinclude,version_number/1).
:- comment(version_number/1,"@var{Version} is a structure
denoting a complete version number (major version, minor version,
and patch number):
@includedef{version_number/1}
").
/*
:- regtype version_number(Version)
# "@var{Version} is a complete version number".
*/
version_number(Major*Minor+Patch) :-
int(Major),
int(Minor),
int(Patch).
% ----------------------------------------------------------------------------
:- comment(doinclude,ymd_date/1).
:- comment(ymd_date/1,"A Year/Month/Day structure denoting a date:
@includedef{ymd_date/1}.").
/*
:- regtype ymd_date(Date)
# "@var{Date} is a Year/Month/Day structure denoting a date.".
*/
ymd_date(Y/M/D) :-
int(Y),
int(M),
int(D).
% ----------------------------------------------------------------------------
:- comment(doinclude,time_struct/1).
:- comment(time_struct/1,"A struture containing time information:
@includedef{time_struct/1}").
/*
:- regtype time_struct(Time) # "@var{Time} contains time information.".
*/
time_struct(Hours:Minutes*Seconds+TimeZone) :-
int(Hours),
int(Minutes),
int(Seconds),
atm(TimeZone).
% ----------------------------------------------------------------------------
/*
:- comment(doinclude,version_maintenance_type/1).
:- comment(version_maintenance_type/1,"Possible kinds of version
maintenance for a file:
@includedef{version_maintenance_type/1}
@begin{itemize}
@item @tt{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 @tt{comment(version(...),...)} declaration.
@item @tt{off}: no version numbering maintained.
@item @tt{dir(Path)}: version numbering is maintained (globally) in
directory @var{Path}. This is useful for maintaining a common
global version for an application which involves several files.
@end{itemize}
The automatic maintenance of version numbers is not (yet)
implemented for XSB.
\comment{
The automatic maintenance of version numbers is typically done by
the CIAO @apl{emacs} mode.
}
").
:- regtype version_maintenance_type(Type) # "@var{Type} a type of
version maintenance for a file.".
version_maintenance_type(on).
version_maintenance_type(off).
version_maintenance_type(dir(Path)) :-
atm(Path).
*/
% ----------------------------------------------------------------------------
:- comment(doinclude,docstring/1).
:- comment(docstring/1,"Defines the format of the character strings
which can be used in machine readable comments (@decl{comment/2}
declarations) and assertions. These character strings can include
certain @index{formatting commands}.
@begin{itemize}
@item All printable characters are admissible in documentation
strings except ``@tt{@@}'', ``@tt{@{},'' and ``@tt{@}}''. To
produce these characters the following @index{escape sequences}
should be used, respectively: @tt{@@@@}, @tt{@@@{}, and @tt{@@@}}.
@item 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 @cindex{syntax of
formatting commands} of all these commands is:
@tt{@@}@em{command}
(followed by either a space or @tt{@{@}}), or
@tt{@@}@em{command}@tt{@{}@em{body}@tt{@}}
where @em{command} is the command name and @em{body} is the
(possibly empty) command body.
The set of commands currently admitted can be found in the
documentation for the predicate @pred{stringcommand/1}.
@end{itemize}
").
:- prop docstring(Text) # "@var{Text} is a @em{documentation string}.".
docstring(CO) :-
docstring(CO,[]).
:- set_prolog_flag(multi_arity_warnings, off).
docstring --> ""
| normalchar, !, docstring
| escapeseq, !, docstring
| "@", Com, " ",
{C =.. [Com,""], stringcommand(C) }, docstring
| "@", Com, "{", Body, "}",
{C =.. [Com,Body], stringcommand(C) }, docstring.
:- set_prolog_flag(multi_arity_warnings, on).
normalchar --> "X", {X \== 0'@, X \== 0'{, X \== 0'} }.
escapeseq --> "@{"
| "@}"
| "@@".
:- comment(doinclude,stringcommand/1).
:- prop stringcommand(CO) # "@var{CO} is a structure denoting a
command that is admissible in strings inside assertions.".
:- comment(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
@concept{LaTeX} text formatting system, except that ``@tt{@@}'' is
used instead of ``@tt{\\}.'' Note that @tt{\\} 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
@concept{scribe}, where the escape character was indeed @tt{@@}!).
The following are the currently admissible commands.
@begin{itemize}
@item @bf{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.
@begin{description}
@item{@tt{@@index@{}@em{text}@tt{@}}} @cindex{@@index command}
@em{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
@em{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.
@item{@tt{@@cindex@{}@em{text}@tt{@}}} @cindex{@@cindex command}
@em{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 string than the
one that is printed in the text.
@item{@tt{@@concept@{}@em{text}@tt{@}}} @cindex{@@concept command}
@em{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.
@item{@tt{@@pred@{}@em{predname}@tt{@}}} @cindex{@@pred command}
@em{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.
@item{@tt{@@op@{}@em{operatorname}@tt{@}}} @cindex{@@op command}
@em{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.
@comment{
@item{@tt{@@decl@{}@em{declname}@tt{@}}} @cindex{@@decl command}
@em{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.
}
@item{@tt{@@lib@{}@em{libname}@tt{@}}} @cindex{@@lib command}
@em{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.
@item{@tt{@@apl@{}@em{aplname}@tt{@}}} @cindex{@@apl command}
@em{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.
@item{@tt{@@file@{}@em{filename}@tt{@}}} @cindex{@@file command}
@em{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.
@item{@tt{@@var@{}@em{varname}@tt{@}}} @cindex{@@var command}
@em{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{pred/1} declaration, such names should be enclosed in
@tt{@@var} commands for the automatic documentation system to work
correctly.
@end{description}
@item @bf{Referencing commands:}
The following commands are used to
introduce @index{bibliographic citations} and @index{references} to
@index{sections}, @index{urls}, @index{email addresses}, etc.
@begin{description}
@item{@tt{@@cite@{@em{keyword}@}}} @cindex{@@cite command}
@em{keyword} is the identifier of a @index{bibliographic entry}.
Such entry is assumed to reside in on of a number of @apl{bibtex}
files (@index{.bib files}) @cindex{bibtex}. A reference in brackets
(@bf{[ ]}) is inserted in the text an the full reference is
included at the end, with all other references, in an appendix. For
example, @tt{@@cite@{iso-prolog@}} will introduce a citation to a
bibliographic entry whose keyword is @tt{iso-prolog}. The list of
bibliography files which will be searched for a match is determined
by the @tt{BIBFILES} variable of the @apl{lpdoc} @file{SETTINGS}
file.
@item{@tt{@@ref@{@em{section title}@}}} @cindex{@@ref command}
introduces at point a reference to the section or node @em{section
title}, where @em{section title} must be the exact @em{text} of the
section title.
@item{@tt{@@uref@{@em{URL}@}} @cindex{@@uref command}
introduces at point a reference to the @index{Universal Resource
Locator} (i.e., a @index{WWW address} '@index{URL}'.
@item{@tt{@@uref@{}@em{text}@tt{@}@{}@em{URL}@tt{@}}}
@cindex{@@uref command} introduces at point a reference to the
@concept{Universal Resource Locator} @concept{URL}, associated to
the text @em{text}.
@item{@tt{@@email@{}@em{address}@tt{@}}} @cindex{@@email command}
introduces at point a reference to @index{email address}
@em{address}.
@item{@tt{@@email@{}@em{text}@tt{@}@{}@em{address}@tt{@}}}
@cindex{@@email command} introduces at point a reference to the
@concept{email address} @concept{address}, associated to the text
@em{text}.
@end{description}
@item @bf{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.
@begin{description}
@item{@tt{@@comment@{}@em{text}@tt{@}}} @cindex{@@comment command}
@em{text} will be treated as a @index{comment} and will be ignored.
@item{@tt{@@begin@{itemize@}}} @cindex{@@begin@{itemize@} command}
marks the beginning of an @index{itemized list}. Each item should
be in a separate paragraph and preceded by an @tt{@@item} command.
@item{@tt{@@item}} @cindex{@@item command} marks the
beginning of a new @index{item in an itemized list}.
@item{@tt{@@end@{itemize@}}}} @cindex{@@end@{itemize@} command}
marks the end of an itemized list.
@item{@tt{@@begin@{enumerate@}}} @cindex{@@begin@{enumerate@}
command} marks the beginning of an @index{enumerated list}. Each
item should be in a separate paragraph and preceded by an
@tt{@@item} command.
@item{@tt{@@end@{enumerate@}}} @cindex{@@end@{enumerate@}
command} marks the end of an enumerated list.
@item{@tt{@@begin@{description@}}} @cindex{@@begin@{description@}
command} marks the beginning of a @index{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
@tt{@@item@{}@em{itemtext}@tt{@}} command.
@item{@tt{@@item@{}@em{itemtext}@tt{@}}} @cindex{@@item command}
marks the beginning of a @index{new item in description list}, and
contains the header for the item.
@item{@tt{@@end@{description@}}} @cindex{@@end@{description@}
command} marks the end of a description list.
@item{@tt{@@begin@{verbatim@}}} @cindex{@@begin@{verbatim@}
command} marks the beginning of @index{fixed format text},
@cindex{verbatim text} such as a program example. A fixed-width,
typewriter-like font is used.
@item{@tt{@@end@{verbatim@}}} @cindex{@@end@{verbatim@} command}
marks the end of formatted text.
@item{@tt{@@begin@{cartouche@}}} @cindex{@@begin@{cartouche@}
command} marks the beginning of a section of text in a
@index{framed box}, with round corners.
@item{@tt{@@end@{cartouche@}}} @cindex{@@end@{cartouche@} command}
marks the end of a section of text in a @concept{framed box}.
@item{@tt{@@section@{}@em{text}@tt{@}}} @cindex{@@section command}
starts a @index{section} whose title is @em{text}. Due to a limitation of
the @apl{info} format, do not use @tt{:} or @tt{-} or @tt{,} in
section, subsection, title (chapter), etc. headings.
@item{@tt{@@subsection@{}@em{text}@tt{@}}} @cindex{@@subsection
command} starts a @index{subsection} whose title is @em{text}.
@item{@tt{@@footnote@{}@em{text}@tt{@}}} @cindex{@@footnote
command} places @em{text} in a @index{footnote}.
@item{@tt{@@today}} @cindex{@@today command} prints the
current @index{date}.
@item{@tt{@@hfill}} @cindex{@@hfill command} introduces horizontal
filling space @cindex{spcae, horizontal fill} (may be ignored in
certain formats).
@item{@tt{@@bf@{}@em{text}@tt{@}}} @cindex{@@bf command} @em{text}
will be formatted in @index{bold face} or any other @index{strong
face}.
@item{@tt{@@em@{}@em{text}@tt{@}}} @cindex{@@em command} @em{text}
will be formatted in @index{italics face} or any other
@index{emphasis face}.
@item{@tt{@@tt@{}@em{text}@tt{@}}} @cindex{@@tt command} @em{text}
will be formatted in a @index{fixed-width font} (i.e.,
@index{typewriter-like font}).
@item{@tt{@@key@{}@em{key}@tt{@}}} @cindex{@@key command} @em{key}
is the identifier of a @index{keyboard key} (i.e., a letter such as
@tt{a}, or a special key identifier such as @tt{RET} or @tt{DEL})
and will be formatted as @key{LFD} or in a fixed-width,
typewriter-like font.
@item{@tt{@@sp@{}@em{N}@tt{@}}} @cindex{@@sp command} generates
@em{N} @index{blank lines} of space. @cindex{space, extra lines}
Forces also a paragraph break.
@item{@tt{@@p}} @cindex{@@p command} forces a @index{paragraph
break}, in the same way as leaving one or more blank lines.
@item{@tt{@@noindent}} @cindex{@@noindent command} used at the
beginning of a paragraph, states that the first line of the
paragraph should not be indented. @cindex{indentation, avoiding}
Useful, for example, for @index{avoiding indentation} on paragraphs
that are continuations of other paragraphs, such as after a
verbatim.
@end{description}
@item @bf{Accents and special characters:}
The following commands can be used to insert @index{accents} and
@index{special characters}.
@begin{description}
@item{@tt{@@`@{o@}}} @result @cindex{@@` command} @`{o}
@item{@tt{@@'@{o@}}} @result @cindex{@@' command} @'{o}
@item{@tt{@@^@{o@}}} @result @cindex{@@^ command} @^{o}
@item{@tt{@@..@{o@}}} @result @cindex{@@.. command} @..{o}
@item{@tt{@@~@{o@}}} @result @cindex{@@~ command} @~{o}
@item{@tt{@@=@{o@}}} @result @cindex{@@= command} @={o}
@item{@tt{@@.@{o@}}} @result @cindex{@@. command} @.{o}
@item{@tt{@@u@{o@}}} @result @cindex{@@u command} @u{o}
@item{@tt{@@v@{o@}}} @result @cindex{@@v command} @v{o}
@item{@tt{@@H@{o@}}} @result @cindex{@@H command} @H{o}
@item{@tt{@@t@{oo@}}} @result @cindex{@@t command} @t{oo}
@item{@tt{@@c@{o@}}} @result @cindex{@@c command} @c{o}
@item{@tt{@@d@{o@}}} @result @cindex{@@d command} @d{o}
@item{@tt{@@b@{o@}}} @result @cindex{@@b command} @b{o}
@item{@tt{@@oe}} @result @cindex{@@oe command} @oe{}
@item{@tt{@@OE}} @result @cindex{@@OE command} @OE{}
@item{@tt{@@ae}} @result @cindex{@@ae command} @ae{}
@item{@tt{@@AE}} @result @cindex{@@AE command} @AE{}
@item{@tt{@@aa}} @result @cindex{@@aa command} @aa{}
@item{@tt{@@AA}} @result @cindex{@@AA command} @AA{}
@item{@tt{@@o}} @result @cindex{@@o command} @o{}
@item{@tt{@@O}} @result @cindex{@@O command} @O{}
@item{@tt{@@l}} @result @cindex{@@l command} @l{}
@item{@tt{@@L}} @result @cindex{@@L command} @L{}
@item{@tt{@@ss}} @result @cindex{@@ss command} @ss{}
@item{@tt{@@?}} @result @cindex{@@? command} @?{}
@item{@tt{@@!}} @result @cindex{@@! command} @!{}
@item{@tt{@@i}} @result @cindex{@@i command} @i{}
@item{@tt{@@j}} @result @cindex{@@j command} @j{}
@item{@tt{@@copyright}} @result @cindex{@@copyright command} @copyright{}
@item{@tt{@@iso}} @result @cindex{@@iso command} @iso{}
@item{@tt{@@bullet}} @result @cindex{@@bullet command} @bullet{}
@item{@tt{@@result}} @result @cindex{@@result command} @result{}
@end{description}
@item @bf{Inclusion commands:}
@cindex{including code} @cindex{including files} @cindex{including images}
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.
@begin{description}
@item{@tt{@@include@{}@em{filename}@tt{@}}} @cindex{@@include
command} the contents of @em{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.
@item{@tt{@@includeverbatim@{}@em{filename}@tt{@}}}
@cindex{@@includeverbatim command} 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 @tt{@@}'s, etc.
@item{@tt{@@includefact@{}@em{factname}@tt{@}}}
@cindex{@@includefact command} it is assumed that the file being
documented contains a fact of the predicate @em{factname}@tt{/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 @index{sharing pieces
of text} between the documentation and the running code. An example
is the text which explains the @index{usage of a command} (options,
etc.).
@item{@tt{@@includedef@{}@em{predname}@tt{@}}} @cindex{@@includedef
command} it is assumed that the file being documented contains a
definition for the predicate @em{predname}. The clauses defining
this predicate will be included in-line, in verbatim mode, as if
they were part of the documentation string. @cindex{including a
predicate definition}
@item{@tt{@@image@{}@em{epsfile}@tt{@}}} @cindex{@@image command}
@index{including an image} at point, @cindex{images, inserting}
contained in file @em{epsfile}. The @index{image file} should be in
@index{encapsulated postscript} format.
@item{@cindex{images, scaling}
@tt{@@image@{}@em{epsfile}@tt{@}@{}@em{width}@tt{@}@{}@em{height}@tt{@}}}
@cindex{@@image command} same as above, but @em{width} and
@em{height} should be integers which provide a size (in points) to
which the image will be scaled.
@end{description}
@end{itemize}
").
%% Approximate... (specially, calls to string/1)
stringcommand(concept(B) ) :- string(B).
stringcommand(cindex(B) ) :- string(B).
stringcommand(cite(B) ) :- string(B).
stringcommand(pred(B) ) :- string(B).
stringcommand(op(B) ) :- string(B).
stringcommand(decl(B) ) :- string(B).
stringcommand(lib(B) ) :- string(B).
stringcommand(apl(B) ) :- string(B).
stringcommand(file(B) ) :- string(B).
stringcommand(var(B) ) :- string(B).
stringcommand(comment(B) ) :- string(B).
stringcommand(begin("itemize") ).
stringcommand(item("") ).
stringcommand(item(B) ) :- string(B).
stringcommand(end("itemize") ).
stringcommand(begin("enumerate")).
stringcommand(end("enumerate") ).
stringcommand(begin("description")).
stringcommand(end("description") ).
stringcommand(begin("verbatim") ).
stringcommand(end("verbatim") ).
stringcommand(begin("cartouche")).
stringcommand(end("cartouche") ).
stringcommand(section(B) ) :- string(B).
stringcommand(subsection(B) ) :- string(B).
stringcommand(footnote(B) ) :- string(B).
stringcommand(ref(B) ) :- string(B).
stringcommand(uref(B) ) :- string(B).
stringcommand(uref(A,B) ) :- string(A),string(B).
stringcommand(email(B) ) :- string(B).
stringcommand(email(A,B) ) :- string(A),string(B).
stringcommand(image(B) ) :- string(B).
stringcommand(image(A,B,C) ) :- string(A),string(B),string(C).
stringcommand(today("") ).
stringcommand(hfill("") ).
stringcommand(bf(B) ) :- string(B).
stringcommand(em(B) ) :- string(B).
stringcommand(tt(B) ) :- string(B).
stringcommand(key(B) ) :- string(B).
stringcommand('`'([_X]) ).
stringcommand(''''([_X]) ).
stringcommand('^'([_X]) ).
stringcommand('..'([_X]) ).
stringcommand('~'([_X]) ).
stringcommand('='([_X]) ).
stringcommand('.'([_X]) ).
stringcommand('u'([_X]) ).
stringcommand('v'([_X]) ).
stringcommand('H'([_X]) ).
stringcommand('t'([_X,_Y]) ).
stringcommand('c'([_X]) ).
stringcommand('d'([_X]) ).
stringcommand('b'([_X]) ).
stringcommand('oe'("") ).
stringcommand('OE'("") ).
stringcommand('ae'("") ).
stringcommand('AE'("") ).
stringcommand('aa'("") ).
stringcommand('AA'("") ).
stringcommand('o'("") ).
stringcommand('O'("") ).
stringcommand('l'("") ).
stringcommand('L'("") ).
stringcommand('ss'("") ).
stringcommand('?'("") ).
stringcommand('!'("") ).
stringcommand('i'("") ).
stringcommand('j'("") ).
stringcommand(copyright("") ).
stringcommand(iso("") ).
stringcommand(bullet("") ).
stringcommand(result("") ).
stringcommand(include(B) ) :- string(B).
stringcommand(includeverbatim(B)) :- string(B).
stringcommand(includefact(B) ) :- string(B).
stringcommand(includedef(B) ) :- string(B).
%% -------------------------------------------------------------------------
end_of_file.
:- comment(usage,"It is not necessary to use this library in user
programs. The recommended procedure in order to make use of the
@decl{comment/2} declarations that this library defines is to
include instead the @lib{assertions} package, which provides
efficient support for all assertion- and comment-related
declarations, using one of the following declarations, as appropriate:
@begin{verbatim}
:- module(...,...,[assertions]).
:- use_package(assertions).
@end{verbatim}
").
:- pred comment(CommentType,VersionMaintenanceType)
:: [comment( "Defines the type of version maintenance that should be performed
by the @apl{emacs} CIAO mode.
@item @em{Example:}
@begin{verbatim}
:- comment(version_maintenance,dir('../version')).
@end{verbatim}
Version control info is kept in directory @tt{../version}. See
the definition of @pred{version_maintenance_type/1} for more
information on the different version maintenance modes. See the
documentation on the @index{emacs CIAO mode} in the CIAO manual
for information on how to automatically insert version control
@decl{comment/2} declarations in files.
The version maintenance mode can also be set alternatively by
inserting a comment such as:
@begin{verbatim}
%% Local Variables:
%% mode: CIAO
%% update-version-comments: ""off""
%% End:
@end{verbatim}
The lines above instruct emacs to put the buffer visiting the
file in @concept{emacs CIAO mode} and to turn version
maintenance off. Setting the version maintenance mode in this
way has the disadvantage that @apl{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 @index{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.
")].
:- pred comment(filetype,FileType) => =(filetype) * filetype
# "Provides a way of defining the intended use of the file. This
use is normally easily inferred from the contents of the file
itself, and therefore such a declaration is in general not
needed. The exception is the special case of @concept{include
files} and CIAO @concept{packages}, which are typically
indistiguishable from normal @em{user} files (i.e., files which
are not modules), but are however quite different in their form
of use (they are loaded via @decl{include/1} or
@decl{use_package/1} declarations instead of
@decl{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 @decl{comment/2} declaration
of this kind strictly only needs to be added to user-type files.
@em{Example:}
@begin{verbatim}
:- comment(filetype,user).
@end{verbatim}
There is another special case: the value @tt{part}. This
@em{filetype} is used to flag files which serve as introductions
to boundaries between major @index{parts in large
documents}. See @ref{Splitting large documents into parts} for
details.
".
:- pred comment(CommentType,FileName) => =(nodoc) * atm
# "Do not document anything that comes from a file whose name
(after taking away the path and the suffix) is
@var{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.
@item @em{Example:}
@begin{verbatim}
:- comment(nodoc,assertions).
@end{verbatim}
".
:- comment(filetype/1,"Intended uses of a file: @includedef{filetype/1}").
/*
:- regtype filetype(Type)
# "@var{Type} describes the intended use of a file.".
*/
filetype(module).
filetype(user).
filetype(include).
filetype(package).
filetype(part).
syntax highlighted by Code2HTML, v. 0.9.1