Skip to content
Fetching latest commit…
Cannot retrieve the latest commit at this time.
..
Failed to load latest commit information.
mfo
mlo
nco
nie
nmm
nmo
xsd
.gitignore
README.ontologiesdoc
explanation.xml.template
index.html
notation.dia

README.ontologiesdoc

Documentation for ontologies
============================

This directory contains verbose documentation explaining each ontology.

Expected documents/format
=========================

1) There should be one directory per ontology prefix.
2) In that directory, there must be a file called 'explanation.xml'
   This file will be copied as-it-is into the documentation general XML
3) There is a predefined id schema for the elements in ontology
   and the document itself, so it is easy to link them from anywhere.
4) Images and other resources (*) linked in the documentation must be
   added: 
    - docs/reference/ontology/Makefile.am (ONTOLOGY_DIAGRAMS variable)

(*) .dia files will be exported as PNG.

Explanation.xml
================

 It must be a file in docbook format (i.e. XML), with an outer element
<section>. Inside the section all the usual docbook elements can be
used freely.

 The file will be included raw in another XML file, so it cannot
contain the usual XML headers (i.e. it won't be a valid XML file).
Anyway, all other XML rules (encodings and so on) are still valid.

 The classes/properties inside the ontology has id's with the
following schema:

   [prefix-ontology]-[name-property-or-class]

 so the property "nfo:duration" has the id "nfo-duration" and
the class "nmm:MusicPiece" has the id "nmm-MusicPiece".

 The ids are global and can be referenced anywhere else in the
documentation. To avoid collisions, use the ontology prefix when
defining a new id in the explanation document.

 All images (don't forget point 4. explained above) are copied in the
root HTML directory, so internally in the documentation must be
refered using just the filename:

 E.G. <graphic fileref="images-overview.png" ...

 The file "explanation.xml.template" contains an example of the usual
sections in the documentation and the most common docbook elements.

How to build/rebuild the documentation
======================================

There are two steps:

1) run make in docs/tools.
   This will generate from the .ontology, .description and
   explanation.xml files a docbook document. That generated document
   (and all the images referenced there) will be copied into
   docs/reference/ontology

   make check the gen-doc.stamp file to decide when it needs to
   rebuild. Remove that file after modifying any of the inputs to
   force a rebuild.

2) run make in docs/reference/ontology
   This will take all the XML generated in the previous step, and
   use the gtk-doc magic to build first a docbook XML and then export
   it as HTML, devhelp and other formats.

   The HTML result is (surprise!) in the html folder.

 
Something went wrong with that request. Please try again.