---+ ClioPatria source-code roadmap

This interface runs PlDoc, the SWI-Prolog literate-programming interface
on top of ClioPatria. You can use the top-left menu to browse files in a
given directory and the top-right menu to search for predicates.

The main directories in ClioPatria are listed below. Note that you can
get an overview of the Prolog files in them by selecting a directory
from the top-left menu.

    $ api :
    Provides HTTP handlers that return JSON or XML that is typically
    not for human consumption.

    $ applications :
    Provides HTTP handlers for (typically) HTML pages for human
    consumption.

    $ user :
    User-handling code: manage users, OpenID services, preferences, etc.

    $ client :
    Provides (Sesame compatible) client code.  This is not part
    of ClioPatria, but is often used in similar contexts.  Note
    that a SPARQL client is part of the SWI-Prolog semweb package.

    $ components :
    DCG-rules that produce HTML.  These are reusable components to
    build _applications_.

    $ config-enabled :
    This directory holds (small) files that configure the server.
    Example and template files are in config-available.  See
    config-enabled/README.txt and config-available/README.txt.

    $ entailment :
    Entailment modules provide an alternative definition of rdf/3 that
    included triples entailed by reasoning.  The various entailment
    modules provide a different amount of reasoning.

    $ lib :
    Reusable code which we envision might become part of the SWI-Prolog
    libraries.  This directory is made available through the alias
    =library= and files in it can thus be loaded using e.g.,

        ==
	:- use_module(library(semweb/rdf_abstract)).
	==

    $ ontologies :
    Some core-ontologies that are used in nearly many domains where
    ClioPatria is being deployed.  Note that you can load these ontologies
    using the menu-item *|File/Load base ontology|*.

    $ rdfql :
    Implementation for RDF query languages: SPARQL and SeRQL. The
    provided functionality is typically only used through the HTTP-API.

    $ skin :
    Defined skins.  Notable skins/cliopatria.pl defines the (hookable)
    overall ClioPatria page-layout.

    $ test :
    Test-framework, notably to verify SPARQL compliance.

    $ web :
    Web-pages used by the server: CSS, Icons, JavaScript and YUI files.

---++ Source files in the top-directory

    $ cliopatria.pl :
    Loads the required components of the system. This notably excludes
    development features.  See run.pl.

    $ hooks.pl :
    Provides declarations for hooks into ClioPatria. Hooks are multifile
    predicates that can be defined to change the behaviour of some part
    of ClioPatria.

    $ parms.pl :
    Central definition of file-paths, web-paths and settings. Should
    normally not be changed.  Application-specific settings go into
    settings.db.

    $ run.pl[.in] :
    Demo startup-file.  Copy and edit to build your application.

    $ setup.pl / configure :
    Localization script to create <file> from <file>.in.  Used to create
    run.pl from run.pl.in.  Can be used to localise your new application
    startup.

---++ Other toplevel files

The files below are located in the directory from which ClioPatria is
started.  They are initially absent and may be deleted to restore the
initial state.

    $ users.db :
    The user-database.  It is formatted in Prolog.  Passwords are hashed
    using crypt/2.  The default is to use (portable) Unix MD5-hashes.
    Administration is done through the web-interface.

    $ settings.db :
    Contains settings that do not have their default value. The settings
    can be changed through the web-interface when logged-in with
    administrative privileges. The file run.pl[.in] shows how
    application defaults can be changed.

    $ RDF-store :
    Directory that holds the persistent RDF store.