Commit 00e323a1 authored by Carlos Garnacho's avatar Carlos Garnacho

docs: Use xi:include to optionally load ontology explanations

Less toggles on the doc generation tool, more seamless documentation
blending. Sounds like win-win.
parent 13cac55d
email-mimeparts-overview.png
feeds-overview.png
images-overview.png
location-overview.png
message-class-overview.png
notation.png
overview.png
radio-overview.png
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
referred 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.
<!--
Usual ids:
xxx-ontology for the whole ontology
xxx-explanation
xxx-classes
xxx-properties
-->
<section id="xxx-explanation">
<title>Overview</title>
<sect2 id="xxx-introduction">
<title>Introduction</title>
<!-- Content -->
<!-- list of terms -->
<variablelist>
<varlistentry>
<term>item name</term>
<listitem><para>description</para></listitem>
</varlistentry>
</variablelist>
</sect2>
<refsect2 id="xxx-special-remarks">
<title>Special remarks</title>
<para>Example of raw sparQL<para>
<code>
INSERT {
&lt;test://1&gt; a nco:PersonContact .
}
</code>
</refsect2>
<refsect2 id="xxx-related-information">
<title>Related information</title>
<para>
<ulink url="http://mail.gnome.org/mailman/listinfo/tracker-list">External link</ulink>
<link linkend="xxx-class">Internal link</link>
</para>
</refsect2>
<refsect2 id="xxxx-graphical-overview">
<figure id="nmm-ontology-graph">
<title>Graphical Overview</title>
<graphic fileref="images-overview.png" format="PNG"></graphic>
</figure>
<para>Notation defined <link linkend="ontology-notation">in this page</link></para>
</refsect2>
</section>
<html>
<head>
<link rel="stylesheet" type="text/css" href="./resources/nie-maemo.css" />
<title>Nepomuk & Tracker ontologies</title>
</head>
<body>
<div class="head">
<div class="nav">
<a href="http://www.tracker-project.org"> <img alt="Tracker logo" src="./resources/tracker-logo.png" /></a>
<a href="http://www.maemo.org"> <img alt="MAEMO logo" src="./resources/maemo-logo.gif" /></a>
<a href="http://nepomuk.semanticdesktop.org"> <img alt="Nepomuk logo" src="./resources/nepomuk-logo.png" /></a>
</div>
</div>
<h1>Tracker & Nepomuk</h1>
<p><a href="http://www.tracker-project.org">Tracker</a> is a central repository of user information, that provides two big benefits for the desktop: <emph>Share</emph> data between applications (it doesn't matter the source once it is stored in the repository) and <emph>Link</emph> information from different sources (mixing contacts with files, location, activities and whatnot).</p>
<p>This central repository can work only with a very well defined data model, that applications can rely to store and recover their information. That data model is defined using a semantic web artifact called <emph>ontology</emph>. An ontology defines the concepts (classes) and properties (attributes) that the items in the repository can be/have.</p>
<p>There is an EU-funded project called <a href="http://nepomuk.semanticdesktop.org/">Nepomuk</a>, where a core of ontologies to model the Desktop were defined. This set was a very good starting point for Tracker but new requirements and heavy development in collaboration with applications provided a very valuable feedback, in form of fixes and extensions. Some of this work is already submitted for approval in the upstream version, but the process is long and hard, so the Tracker ontologies are diverging slowly.</p>
<p>This documentation describes the Tracker flavour of Nepomuk ontologies. The big picture and basic concepts are the same as in the original Nepomuk, but "hell and heaven are in the details". All classes, properties and restrictions included in these pages should work in Tracker. Any error in this documentation can be reported in the Tracker <a href="http://mail.gnome.org/mailman/listinfo/tracker-list">Mailing list</a> or <a href="https://bugzilla.gnome.org/enter_bug.cgi?product=tracker">bugzilla</a>.</p>
<p>This is just documentation about the ontologies. For more information about Tracker technical details and implementation, please refer to the Tracker <a href="http://live.gnome.org/Tracker/Documentation/">Documentation wiki</a> page in GNOME</p>.
<h1>Ontologies</h1>
<p>Tracker uses a some patched Nepomuk ontologies, with other extensions developed in Maemo:</p>
<ul>
<li><a href="./nie/index.html">NIE</a>: Nepomuk Information Element. The "super" ontology that defines the basic blocks. It contains the most generic superclasses, and all other ontologies refine those concepts in different domains. </li>
<li><a href="./nco/index.html">NCO</a>: Nepomuk Contacts Ontology, talking about the Contacts domain (including phone numbers). Extended by tracker to support IM Contacts.</li>
<li><a href="./nmo/index.html">NMO</a>: Nepomuk Messaging Ontology, defining the messaging model. Extended by tracker to support calls, SMS and complete Email message representation.</li>
<li><a href="./nfo/index.html">NFO</a>: Nepomuk File Ontology. Basic file description. Extended by tracker to improve playlists support.</li>
<li><a href="./nao/index.html">NAO</a>: Nepomuk Annotation Ontology. Tag support everywhere in the ontologies.</li>
<li><a href="./mto/index.html">MTO</a>: Maemo Transfers Ontology, to represent uploads/downloads.</li>
<li><a href="./nmm/index.html">NMM</a>: Nepomuk Multimedia Ontology (Maemo proposal to replace/complement NID3/NEXIF). Includes music, images, video and radio.</li>
<li><a href="./mfo/index.html">MFO</a>: Maemo Feeds Ontology, for feeds and podcasts</li>
<li><a href="./mlo/index.html">MLO</a>: Maemo Location Ontology: Very Early Draft of a location ontology.</li>
<li><a href="./tracker/index.html">Tracker</a>/<a href="./maemo/index.html">maemo</a>: Specific tracker/maemo internal properties</li>
</ul>
<p>There is a special case with the calendar ontology. We have two possible solutions and still is not clear which one works better:</p>
<ul>
<li><a href="./ncal/index.html">NCAL</a>: Nepomuk Calendar Ontology. Original Nepomuk ontology, translation in ontology form of the ical spec. It is 100% compatible with ical but very difficult to use.</li>
<li><a href="./scal/index.html">SCAL</a>: Simplified Calendar Ontology. Custom made ontology for calendar. Compatible with ical (maybe some rough edges to fix), easier to handle, and probably more efficient in some scenarios.</li>
</ul>
<a name="Notation">
<h2>Notation</h2>
<p>Brief description of the notation used in the diagrams</p>
<img src="./notation.png">
</html>
AUTOMAKE_OPTIONS = 1.6
# The original Ontology explanation files
ONTOLOGY_EXPLANATIONS = \
$(top_srcdir)/docs/ontologies/mfo/explanation.xml \
$(top_srcdir)/docs/ontologies/nmm/explanation.xml \
$(top_srcdir)/docs/ontologies/mlo/explanation.xml \
$(top_srcdir)/docs/ontologies/nie/explanation.xml \
$(top_srcdir)/docs/ontologies/nmm/explanation.xml \
$(top_srcdir)/docs/ontologies/nco/explanation.xml \
$(top_srcdir)/docs/ontologies/nmo/explanation.xml
ONTOLOGY_INTRODUCTIONS = \
mfo-introduction.xml \
mlo-introduction.xml \
nco-introduction.xml \
nie-introduction.xml \
nmm-introduction.xml \
nmo-introduction.xml \
xsd-introduction.xml
# Generation of the ontology XML files.
gen-doc.stamp: $(ONTOLOGY_EXPLANATIONS)
gen-doc.stamp: $(ONTOLOGY_INTRODUCTIONS)
$(MKDIR_P) xml
$(top_srcdir)/docs/tools/gen-doc.sh $(top_builddir)/docs/tools/ttl2sgml $(top_builddir)/docs/tools/ttlresource2sgml $(top_srcdir)/src/ontologies/nepomuk $(top_srcdir)/docs/ontologies xml/
$(top_srcdir)/docs/tools/gen-doc.sh $(top_builddir)/docs/tools/ttl2sgml $(top_builddir)/docs/tools/ttlresource2sgml $(top_srcdir)/src/ontologies/nepomuk xml/
$(AM_V_GEN) touch $@
version.xml: gen-doc.stamp
......@@ -49,7 +49,7 @@ include $(top_srcdir)/gtk-doc.make
# by gtk-doc
EXTRA_DIST += \
version.xml.in \
$(ONTOLOGY_EXPLANATIONS) \
$(ONTOLOGY_INTRODUCTIONS) \
meson.build
CLEANFILES += \
......
......@@ -23,15 +23,14 @@ set -e
if [ $# -lt 5 ]; then
echo "Insufficient arguments provided"
echo "Usage: $0 <ttl2sgml> <ttlres2sgml> <ontology-data-dir> <ontology-info-dir> <build-dir>"
echo "Usage: $0 <ttl2sgml> <ttlres2sgml> <ontology-data-dir> <build-dir>"
exit 1;
fi
TTL2SGML=$1
TTLRES2SGML=$2
ONTOLOGIES_DATA_DIR=$3
ONTOLOGIES_INFO_DIR=$4
BUILD_DIR=$5
BUILD_DIR=$4
if [ ! -e $BUILD_DIR ]; then
mkdir -p $BUILD_DIR
......@@ -44,8 +43,7 @@ for f in `find $ONTOLOGIES_DATA_DIR -name "*.description"` ; do
TMPNAME=${f%.description}
PREFIX=${TMPNAME#*-}
$TTL2SGML -d $f -o $BUILD_DIR/$PREFIX-ontology.xml \
-e $ONTOLOGIES_INFO_DIR/$PREFIX/explanation.xml
$TTL2SGML -d $f -o $BUILD_DIR/$PREFIX-ontology.xml
done
echo "Done"
......@@ -27,7 +27,6 @@
static gchar *desc_file = NULL;
static gchar *output_file = NULL;
static gchar *explanation_file = NULL;
static GOptionEntry entries[] = {
{ "desc", 'd', 0, G_OPTION_ARG_FILENAME, &desc_file,
......@@ -38,10 +37,6 @@ static GOptionEntry entries[] = {
"File to write the output (default stdout)",
NULL
},
{ "explanation", 'e', 0, G_OPTION_ARG_FILENAME, &explanation_file,
"Verbosy explanation file in HTML format to include in the webpage",
NULL
},
{ NULL }
};
......@@ -96,7 +91,7 @@ main (gint argc, gchar **argv)
g_free (ttl_file);
g_free (dirname);
ttl_sgml_print (description, ontology, f, explanation_file);
ttl_sgml_print (description, ontology, f);
ttl_loader_free_ontology (ontology);
ttl_loader_free_description (description);
......
......@@ -124,20 +124,6 @@ print_sgml_header (FILE *f, OntologyDescription *desc)
g_fprintf (f, "</varlistentry>\n");
}
static void
print_sgml_explanation (FILE *f, const gchar *explanation_file)
{
gchar *raw_content;
gsize length;
if (explanation_file && g_file_test (explanation_file, G_FILE_TEST_EXISTS)) {
if (!g_file_get_contents (explanation_file, &raw_content, &length, NULL)) {
g_error ("Unable to load '%s'", explanation_file );
}
g_fprintf (f, "%s", raw_content);
}
}
static void
print_sgml_footer (FILE *f)
{
......@@ -212,8 +198,7 @@ print_ontology_class (Ontology *ontology,
void
ttl_sgml_print (OntologyDescription *description,
Ontology *ontology,
FILE *f,
const gchar *explanation_file)
FILE *f)
{
GHashTableIter iter;
gchar *upper_name;
......@@ -224,8 +209,8 @@ ttl_sgml_print (OntologyDescription *description,
qname_init (description->baseUrl, description->localPrefix, NULL);
print_sgml_header (f, description);
/* FIXME: make desc files sgml */
print_sgml_explanation (f, explanation_file);
g_fprintf (f, "<xi:include href='../%s-introduction.xml'><xi:fallback/></xi:include>",
description->localPrefix);
g_fprintf (f, "<section id='%s-classes'>\n", description->localPrefix);
g_fprintf (f, "<title>%s Ontology Classes</title>\n", upper_name);
......
......@@ -28,10 +28,7 @@ G_BEGIN_DECLS
void ttl_sgml_print (OntologyDescription *description,
Ontology *ontology,
FILE *output,
const gchar *explanation_file);
FILE *output);
G_END_DECLS
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment