:- 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).

