Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
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.