This document is intended to describe various aspects of the development process in the DLV project.


Table of Contents


Maintainers

These are the current maintainers of various parts of the system. All non-trivial changes must be approved by someone with write privilege for the corresponding part.

Blanket Write Gerald, Wolfgang
Basic datastructures Gerald
Dependency Graph Handler
Parser Gerald, Wolfgang
Rewriting Wolfgang
Grounding Simona
Model Generator Gerald, Wolfgang
Model Checker Gerald
Aggregates Gerald, Tina, Peppe
Reasoning Frontends, Queries Gerald
Diagnosis Frontend Gerald, Wolfgang
Planning Frontend Axel
SQL Frontend Wolfgang
GUI Wolfgang
Testsuite all (for invasive changes check with Gerald, Wolfgang)
Manual Gerald, Wolfgang, Peppe
Web pages Gerald, Wolfgang

Command-line Options for Internal Usage

The following command-line options are intended for debugging purposes only and considered undocumented, i.e., subject to change.

--depgraph Print the various dependency graphs.
-stats++ Print more statistics than -stats.

CVS: Hints and Guidelines

http://www.pfeifer.com/gerald/cvs.html has some hints and guidelines on CVS usage. Following these is mandatory for DLV development.


Rolling a Release

The "May 16 2003" release (for sparc-sun-solaris2.9) can be built and put up on the web as follows, assuming there is a checked out tree in a subdirectory called dlv:


Formatting C++ Sources -- style.el

Tabs and Whitespace

First of all note that it is now policy not to use tabs when indenting code. This simply has been causing too many troubles with various tools.

To tell Emacs or XEmacs not to use tabs for indentation, set the variable indent-tabs-mode to nil. You can do that by adding '(indent-tabs-mode nil) to (custom-set-variables ...) in .emacs. So, if you do not have a custom-set-variables yet, add (custom-set-variables '(indent-tabs-mode nil)).

Intendation

For those Emacs freaks among us, Robert has developed a C indentation style named dl, which embodies the style used throughout the sources and is contained in dlv/style.el.

To use this style, simply add the following to your .emacs file:

(require 'cc-mode)
(load-library "${path-to-checked-out-dlv-sources}/style.el")

where ${path-to-checked-out-dlv-sources} should be replaced by the full path to your DLV sources. To find out this path, you can run pwd in the directory holding your DLV sources.

The dl style is already turned on automatically upon loading of most DLV source files, but you can manually switch styles with the c-set-style command.

Please remember to correctly indent all sources!

FIXME

Please document pieces of code which should be rewritten, reviewed or redesigned by a comment starting with the word FIXME. This makes maintainance and debugging a hell of a lot easier.


Installing DocBook

Installing DocBook on a FreeBSD System

Install the packages jade, docbook-410, and dsssl-docbook-modular, and set SGML_CATALOG_FILES to /usr/local/share/sgml/catalog.

Installing DocBook on a Debian GNU/Linux System

Debian 2.2 ("potato")

Just install the package docbook-stylesheets, all other necessary packages will be installed automagically. Additionally installing package docbook-stylesheets-doc is recommended.

In the Makefile, you should set:
STYLESHEETS=/usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh/

Debian 3.0 ("woody")

Just install the package docbook-dsssl, all other necessary packages will be installed automagically. Additionally installing package docbook-dsssl-doc is recommended.

In the Makefile, you should set:
STYLESHEETS=/usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh/

Installing DocBook on a SuSE GNU/Linux System

SuSE 7.2

You need the package docbook-dsssl-stylesheets (Disclaimer: I did not install the machine by myself, so this is a guess. -WF).

Unfortunately it seems that the default catalogs for jade are not configured correctly by default, so you must set the environment variable SGML_CATALOG_FILES by yourself, e.g. in .cshrc or .bashrc. The catalog files are /usr/share/sgml/CATALOG.*, but unfortunately again it seems that some of them are broken in the default installation. To overcome this I only use the catalog files /usr/share/sgml/CATALOG.doc* (dirty, but works).

So, for tcsh add the following to .cshrc:

setenv SGML_CATALOG_FILES `echo /usr/share/sgml/CATALOG.doc* | sed -e 's# /usr/share/sgml/CATALOG#:/usr/share/sgml/CATALOG#g'`



For bash this would be

export SGML_CATALOG_FILES=`echo /usr/share/sgml/CATALOG.doc* | sed -e 's# /usr/share/sgml/CATALOG#:/usr/share/sgml/CATALOG#g'`



In the Makefile, you should set:
STYLESHEETS=/usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.64

Installing DocBook on a Red Hat GNU/Linux System

Red Hat 7.1 Professional

This distribution already contains the sgml-tools and the docbook-dsssl-stylesheets packages,
but the default installation doesn't install both of them so make sure you have the docbook-dsssl-stylesheets
installed in the /usr/share/sgml/docbook/directory.

In the Makefile, you should set:
STYLESHEETS=/usr/share/sgml/docbook/docbook-dsssl-stylesheets-1.59


Editing DocBook sources with emacs

This is again intended for the emacs freaks among us.

psgml

The best idea is to use psgml. Current versions of Emacs (20.x) and XEmacs (21.x) already ship with a complete psgml package.

psgml and the DocBook DTD

In order to make the DocBook DTD (and others) available, you should set the environment variable SGML_CATALOG_FILES properly as described in the previous section.

Having this environment variable set enables psgml to parse the DocBook DTD.

Caching the DocBook DTD

This parsing takes some time, but there is a mechanism in psgml, which allows caching of parsed DTDs. A file similar to a CATALOG file tells psgml where to find those cached parsed DTDs. To use this feature for DocBook, add the following to your .emacs file:

(setq sgml-local-ecat-files '("/home/faber/share/emacs/ECAT"))
(setq sgml-recompile-out-of-date-cdtd nil)

The second line prevents you from overwriting the cached DTD (this would not be possible anyway).

Recommended psgml Settings

We recommend the following settings (in other words, this should go into your .emacs files):

(setq sgml-indent-data t)
(setq sgml-auto-insert-required-elements t)
(setq sgml-insert-missing-element-comment nil)
(setq sgml-balanced-tag-edit t)
(setq sgml-auto-activate-dtd t)
(setq sgml-set-face t)

The first line is probably most important: It forces indentation for everything, not only tags.

The second line inserts all required elements if you add elements with C-c C-e or C-c <. Very useful.

The third line turns off the feature that a comment is inserted after C-c C-e or C-c < if there's one required element, but a choice of several, which we find annoying.

The fourth line also inserts the corresponding end tag automatically if you insert a start tag.

The fifth line forces the DTD to be parsed immediately and not after some action which needs it is requested. If you don't do this, you will experience some annoying delay if you take any action which requires the parsing of the DTD. With this line, the parsing is done when the buffer is created, which is the time where one expects such delays.

The sixth line turns on some default syntax highlighting. Very useful, but it can even be enhanced! This heavily depends on personal taste, so we can just give examples.

For example, Wolfgang uses the following settings:

(set-face-foreground (make-face 'dim) "tan") (set-face-foreground (make-face 'comment) "slateblue") (setq sgml-markup-faces '((start-tag . dim) (end-tag . dim) (ignored . dim) (comment . comment)))

psgml Documentation

There is a nice manual. It is available in info-format (/home/faber/info/psgml.info), or as Postscript document (/home/faber/doc/psgml.ps).

DocBook Documentation

Links:


Formatting Tcl/Tk Sources -- tcl-add-on.el

As always, this is for emacs.

A while ago, the Tcl Style Guide has been written. Jeffrey Hobbs posted an add-on for the tcl-mode to comp.lang.tcl a while later. (Find the posting at Google Groups.)

To use it, put the following line into your .emacs file:

(load "/home/faber/share/emacs/site-lisp/tcl-add-on.el")

For documentation, the best thing is if you have a look into the code. Note that currently the tcl sources are not formatted with this style, since most of it was written before the style guide was even written. Future extensions should make use of it nevertheless.


Gerald Pfeifer (pfeifer@dbai.tuwien.ac.at)
with lots of help by
Robert Bihlmeyer (robbe@orcus.priv.at)
Wolfgang Faber (faber@kr.tuwien.ac.at)