Documentation mark-up language and doc declarations

Defines the format of the character strings which can be used in machine readable comments (doc/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 @}.

  Note that in strings, each \ character must be escaped (with \, \\), so to get one backslash four backslashes (\\\\) have to be used, i.e., in a string \\\\ is used to represent \\, and that is the command that will output a \ character.

• 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. Alternatively, \ can be used instead of {} (escaped if appears in strings).

  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. Both ``@'' and ``\'' are allowed in command names. Note that ``\'' needs to be escaped in strings, which makes the source less readable. In such case it is recommended using ``@'' (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.

• 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.

  @begin{note}

  marks the beginning of a section of text in a framed box, for note messages.

  @end{note}

  marks the end of the note message.

  @begin{alert}

  marks the beginning of a section of text in a framed box, for alert messages.

  @end{alert}

  marks the end of the alert message.

  @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.

  @subsubsection{text}

  starts a subsubsection whose title is text.

  @footnote{text}

  places text in a footnote.

  @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.

• 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 one 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 bibfile/1 fact of the doccfg 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.

  @href{URL}

  introduces at point a reference to the Universal Resource Locator (i.e., a WWW address 'URL'.

  @href{URL}{text}

  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.

  @author{text}

  text will be printed (in a normal font). This command is used to reference the name of an author (not necessarily establishing the module authorship).

• Date and Version:

  @today

  prints the current date.

  @version

  prints the version of the current manual.

• Mathematics:

  The following commands are used to format text in mathematical .

  @math{text}

  in-line typeset the text formula.

  @begin{displaymath}

  marks the beginning of a formula (useful for long formulas).

  @end{displaymath}

  marks the end of the (long) formula.

  @defmathcmd{cmd}{n}{def}

  defines the math command cmd, taking n arguments, which is expanded as def. Arguments are denotated as #1, ..., #n inside def.

  @defmathcmd{cmd}{def}

  defines the math command cmd, which is expanded as def (with no arguments).

• 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.

  @includecode{filename}

  the contents of filename will be included in-line and represented in verbatim mode (without @begin{verbatim} and @end{verbatim}). Commands within the file are not interpreted. This is useful for including code fragments in documentation.

  @includecode{lang}{filename}

  same as above, but the contents of filename will be included in-line and represented in language lang.

  @includeverbatim{filename}

  (DEPRECATED) as above, but the contents of the file are not necessarily represented in verbatim mode. Note that this only means that the file will be included as is. If you want the string to be represented in verbatim mode in the output, you must surround the @includeverbatim{filename} with @begin{verbatim} and @end{verbatim}.

  @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, in verbatim mode, 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.

• Accents and special characters:

  The following commands can be used to insert accents and special characters.

  @`{o}

  ⇒ ò

  @'{o}

  ⇒ ó

  @^{o}

  ⇒ ô

  @..{o}

  ⇒ ö

  @"{o}

  ⇒ ö

  @~{o}

  ⇒ õ

  @={o}

  ⇒ ō

  @.{o}

  ⇒ ȯ

  @u{o}

  ⇒ ŏ

  @v{o}

  ⇒ ǒ

  @H{o}

  ⇒ ő

  @t{oo}

  ⇒ o͡o

  @c{o}

  ⇒ o̧

  @d{o}

  ⇒ ọ

  @b{o}

  ⇒ o̱

  @oe

  ⇒ œ

  @OE

  ⇒ Œ

  @ae

  ⇒ æ

  @AE

  ⇒ Æ

  @aa

  ⇒ å

  @AA

  ⇒ Å

  @o

  ⇒ ø

  @O

  ⇒ Ø

  @l

  ⇒ ł

  @L

  ⇒ Ł

  @ss

  ⇒ ß

  @?

  ⇒ ¿

  @!

  ⇒ ¡

  @i

  ⇒ ı

  @j

  ⇒ ȷ

  @copyright

  ⇒ ©

  @iso

  ⇒ ISO

  @bullet

  ⇒ º

  @result

  ⇒ ⇒

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_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(application).
filetype(part).
filetype(documentation).

Usage:filetype(Type)

Type describes the intended use of a file.

The defined stability levels that can be attached to files:

stability_level(devel).
stability_level(alpha).
stability_level(beta).
stability_level(prod).
stability_level(devel(L)) :-
    docstring(L).
stability_level(alpha(L)) :-
    docstring(L).
stability_level(beta(L)) :-
    docstring(L).
stability_level(prod(L)) :-
    docstring(L).

Usage:stability_level(Level)

Level describes a level of stability.

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::- doc(CommentType,TitleText).

Provides a title for the module, library, or application. When generating documentation automatically, the text in 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.

• Example:

:- doc(title,"Documentation-oriented assertions").

• The following properties should hold upon exit:
  (= /2)title=CommentType
  (docstring/1)TitleText is a documentation string.

Usage 2::- doc(CommentType,SubtitleText).

Provides a subtitle, an explanatory or alternate title. The subtitle will be displayed under the proper title.

• Example:

:- doc(title,"Dr. Strangelove").
:- doc(subtitle,"How I Learned to Stop Worrying and Love the Bomb").

• The following properties should hold upon exit:
  (= /2)subtitle=CommentType
  (docstring/1)SubtitleText is a documentation string.

Usage 3::- doc(CommentType,SubtitleText).

Provides additional 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. When generating documentation automatically, the text in SubtitleText will be used accordingly. Several of these declarations can appear per module, which is useful for, e.g., multiple line addresses.

• Example:

:- doc(subtitle_extra,"A Reference Manual").
:- doc(subtitle_extra,"Technical Report 1/1.0").

• The following properties should hold upon exit:
  (= /2)subtitle_extra=CommentType
  (docstring/1)SubtitleText is a documentation string.

Usage 4::- doc(CommentType,LogoName).

The name of the logo image for the manual.

• The following properties should hold upon exit:
  (= /2)logo=CommentType
  (term/1)LogoName is any term.

Usage 5::- doc(CommentType,AuthorText).

Provides the author(s) of the module or application. If present, when generating documentation for the module automatically, the text in 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.

• Example:

:- doc(author,"Alan Robinson").

• The following properties should hold upon exit:
  (= /2)author=CommentType
  (docstring/1)AuthorText is a documentation string.

Usage 6::- doc(CommentType,Text).

Provides the physical and electronic address, or any other contact information for the authors of the module or application.

• Example:

:- doc(address,"Syracuse University").

• The following properties should hold upon exit:
  (= /2)address=CommentType
  (docstring/1)Text is a documentation string.

Usage 7::- doc(CommentType,AckText).

Provides acknowledgements for the module. If present, when generating documentation for the module automatically, the text in AckText will be placed in the corresponding chapter or section. There can be only one of these declarations per module.

• Example:

:- doc(ack,"Module was written by Alan, but others helped.").

• The following properties should hold upon exit:
  (= /2)ack=CommentType
  (docstring/1)AckText is a documentation string.

Usage 8::- doc(CommentType,StabilityText).

Provides a stability level for the module. If present, when generating documentation for the module automatically, the level of stability of the module will be documented. There can be only one of these declarations per module. The second argument should be an atom, out of a number of predefined stability levels. The text included is predefined for each level. Alternatively, one of the admissible atoms can be used as the functor with a single argument, which contains the text to be included.

• Examples:

:- doc(stability,devel).
:- doc(stability,alpha).
:- doc(stability,beta).
:- doc(stability,prod).
:- doc(stability,alpha("My own comment on stability.")).

• The following properties should hold upon exit:
  (= /2)stability=CommentType
  (stability_level/1)StabilityText describes a level of stability.

Usage 9::- doc(CommentType,CopyrightText).

Provides a copyright text. This normally appears somewhere towards the beginning of a printed manual. There should be at most one of these declarations per module.

• Example:

:- doc(copyright,"Copyright @copyright{} 2001 FSF.").

• The following properties should hold upon exit:
  (= /2)copyright=CommentType
  (docstring/1)CopyrightText is a documentation string.

Usage 10::- doc(CommentType,SummaryText).

Provides a brief global explanation of the application or library. The text in SummaryText will be used as the abstract for the whole manual. There should be at most one of these declarations per module.

• Example:

:- doc(summary,"This is a @@bf@{very@} important library.").

• The following properties should hold upon exit:
  (= /2)summary=CommentType
  (docstring/1)SummaryText is a documentation string.

Usage 11::- doc(CommentType,CommentText).

Provides the main comment text for the module or application. When generating documentation automatically, the text in 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 sections if substructure is needed.

• Example:

:- doc(module,"This module is the @@lib@{comments@} library.").

• The following properties should hold upon exit:
  (= /2)module=CommentType
  (docstring/1)CommentText is a documentation string.

Usage 12::- doc(CommentType,CommentText).

Provides additional comments text for a module or application. When generating documentation automatically, the text in 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.

• Example:

:- doc(appendix,"Other module functionality...").

• The following properties should hold upon exit:
  (= /2)appendix=CommentType
  (docstring/1)CommentText is a documentation string.

Usage 13::- doc(CommentType,CommentText).

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.

• Example:

:- doc(usage,"Do not use: still in development!").

• The following properties should hold upon exit:
  (= /2)usage=CommentType
  (docstring/1)CommentText is a documentation string.

Usage 14::- doc(CommentType,Section).

Insert a program section with name Section. Sectioning commands allow a structured separation of the program into parts. The division is only for documentation purposes, so visibility and scope of definitions is not affected by sectioning commands.

• Example:

:- doc(section,"Main Steps of the Algorithm").

• The following properties should hold upon exit:
  (= /2)section=CommentType
  (docstring/1)Section is a documentation string.

Usage 15::- doc(CommentType,SubSection).

Insert a program subsection with name SubSection (see program section command for more details).

• Example:

:- doc(subsection,"Auxiliary Definitions").

• The following properties should hold upon exit:
  (= /2)subsection=CommentType
  (docstring/1)SubSection is a documentation string.

Usage 16::- doc(CommentType,SubSubSection).

Insert a program subsubsection with name SubSubSection (see program section command for more details).

• Example:

:- doc(subsubsection,"Auxiliary Definitions").

• The following properties should hold upon exit:
  (= /2)subsubsection=CommentType
  (docstring/1)SubSubSection is a documentation string.

Usage 17::- doc(PredName,CommentText).

Provides an introductory comment for a given predicate, function, property, type, etc., denoted by 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.

• Example:

:- doc(doc/2,"This declaration provides one of the main 
   means for adding @@concept@{machine readable comments@} to 
   programs.").

• The following properties should hold upon exit:
  (predname/1)PredName is a predicate name.
  (docstring/1)CommentText is a documentation string.

Usage 18::- doc(CommentType,CommentText).

Documents a known bug or planned improvement in the module or application. Several of these declarations can appear per module. When generating documentation automatically, the text in the Text fields will be used as items in an itemized list of module or application bugs.

• Example:

:- doc(bug,"Comment text still has to be written by user.").

• The following properties should hold upon exit:
  (= /2)bug=CommentType
  (docstring/1)CommentText is a documentation string.

Usage 19::- doc(Version,CommentText).

Provides a means for keeping a log of changes. 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).

• Example:

:- doc(version(1*1+21,1998/04/18,15:05*01+'EST'), "Added some
   missing comments.  (Manuel Hermenegildo)").

• The following properties should hold upon exit:
  (version_descriptor/1)Version is a complete version descriptor.
  (docstring/1)CommentText is a documentation string.

Usage 20::- doc(CommentType,VersionMaintenanceType).

Defines the type of version maintenance that should be performed by the emacs Ciao mode.

• Example:

:- doc(version_maintenance,dir('../version')).

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{doc/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 @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.

• The following properties should hold upon exit:
  (= /2)version_maintenance=CommentType
  (version_maintenance_type/1)VersionMaintenanceType is a type of version maintenance for a file.

Usage 21::- doc(CommentType,PredName).

This is a special case that is used to control which predicates are included in the documentation. Normally, only exported predicates are documented. A declaration :- doc(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 :- doc(doinclude,PredName). will force the documenation for PredName to appear directly in this module.

• Example:

:- doc(doinclude,p/3).

• The following properties should hold upon exit:
  (= /2)doinclude=CommentType
  (predname/1)PredName is a predicate name.

Usage 22::- doc(CommentType,PredName).

A different usage which allows the second argument of :- doc(doinclude,...) to be a list of predicate names.

• The following properties should hold upon exit:
  (= /2)doinclude=CommentType
  (list/2)PredName is a list of prednames.

Usage 23::- doc(CommentType,PredName).

This is similar to the previous usage but has the opposite effect: it signals that an exported predicate should not be included in the documentation.

• Example:

:- doc(hide,p/3).

• The following properties should hold upon exit:
  (= /2)hide=CommentType
  (predname/1)PredName is a predicate name.

Usage 24::- doc(CommentType,PredName).

A different usage which allows the second argument of :- doc(hide,...) to be a list of predicate names.

• The following properties should hold upon exit:
  (= /2)hide=CommentType
  (list/2)PredName is a list of prednames.

Usage 25::- doc(CommentType,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 include files and Ciao packages, which are typically indistiguishable from normal user files (i.e., files which are not modules), but are however quite different in their form of use (they are loaded via 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 doc/2 declaration of this kind strictly only needs to be added to user-type files.

Example:

:- doc(filetype,user).

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.

• The following properties should hold upon exit:
  (= /2)filetype=CommentType
  (filetype/1)FileType describes the intended use of a file.

Usage 26::- doc(CommentType,FileName).

Do not document anything that comes from a file whose name (after taking away the path and the suffix) is 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.

• Example:

:- doc(nodoc,regtypes).

• The following properties should hold upon exit:
  (= /2)nodoc=CommentType
  (atm/1)FileName is an atom.

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 doc(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 is a type of version maintenance for a file.