2.2.3 Package Entry

A package entry describes an actual contribution. Let's now look at a real example (at least it was at some point).

type:          package
id:            mogul:/duchier/expat
author:        mogul:/duchier/denys
blurb:         A SAX-like XML processor using Jame Clark's expat library, and a parser derived from it.
url-pkg:       http://fox.ps.uni-sb.de/~denys/mogul/pub/tar/duchier-expat.tgz
url-doc:       http://fox.ps.uni-sb.de/~denys/mogul/pub/doc/duchier/expat/index.html
url-doc-extra: [API] http://www.ps.uni-sb.de/~duchier/mogul/pub/doc/duchier/expat/API/ozdoc.css
url-doc-extra: [API] http://www.ps.uni-sb.de/~duchier/mogul/pub/doc/duchier/expat/API/page.gif
provides:      [xml] x-ozlib://duchier/xml/expat/Processor.ozf
provides:      [xml] x-ozlib://duchier/xml/expat/Parser.ozf
requires:      x-ozlib://duchier/op/InputSource.ozf
content-type:  text/html
<P>This is an interface to <A HREF="http://www.jclark.com/">James
Clark</A>'s <TT>expat</TT> library for parsing XML documents.
Module <TT>Processor.ozf</TT> exports a class that implements a
SAX-like processor which can be used e.g. as shown below.
SAX events are invoked as methods.  Each application should specialize
these methods to do something useful.

This is the entry for package mogul:/duchier/expat (in section mogul:/duchier of course). It has an author header that refers to the database entry with id mogul:/duchier/denys. An arbitrary number of author and contact headers can be supplied. The blurb provides a very short description of the package. url-pkg provides a url to a downloadable archive of the package. In the example this corresponds to a source distribution, but in general the header could be repeated to indicate different urls for binary distributions for different platforms. url-doc is a url to online documentation for the package.

url-doc-extra headers are for extra files necessary for viewing the documentation, such as stylesheets and graphics (e.g. gif files). It is necessary to specify such files separately when there is no hyperlink to them in the HTML documentation: in such a case they are not automatically downloaded.

url-doc-extra: [API] http://www.ps.uni-sb.de/~duchier/mogul/pub/doc/duchier/expat/API/ozdoc.css

Optionally, a subdirectory name maybe supplied between square brackets (here [API]) to indicate that the file should be placed in this subdirectory when it is downloaded rather than in the main doc directory.

There are 2 provides headers.

provides:      [xml] x-ozlib://duchier/xml/expat/Processor.ozf
provides:      [xml] x-ozlib://duchier/xml/expat/Parser.ozf

They indicate that the package provides the following 2 URIs (corresponding here to Oz functors):


Furthermore, the annotation [xml] indicates that these URIs should be listed in the MOGUL Category xml. Assigning categories to modules makes it easier for users to locate relevant packages. Since a proliferation of categories would be counter productive, the MOGUL Librarian ignores any category that is not official. The current official categories can be found in a MOGUL Archive, e.g.:

Introduction of new categories is mediated by the Mozart Consortium and should be proposed and discussed on the mozart user group.

The requires header indicates that the package also needs another module identified by the given URI:

requires:      x-ozlib://duchier/op/InputSource.ozf

The MOGUL Librarian automatically creates a hyperlink to the package that provides this needed module.

Finally, the entry has a non-empty body containing some documentation. It should be a 1 page description of the purpose of the package. The actual documentation (see url-doc) may be much more extensive. Header content-type indicates how to interpret the body. The MOGUL Librarian only understands content types text/plain (the default) and text/html.

Denys Duchier
Version 1.3.0 (20040413)