docs: Use xi:include to optionally load ontology explanations

Less toggles on the doc generation tool, more seamless documentation
blending. Sounds like win-win.

16 files changed, 19 insertions, 242 deletions

diff --git a/docs/ontologies/.gitignore b/docs/ontologies/.gitignore
deleted file mode 100644
index 29bc799ac..000000000
--- a/docs/ontologies/.gitignore
+++ /dev/null
@@ -1,8 +0,0 @@
-email-mimeparts-overview.png
-feeds-overview.png
-images-overview.png
-location-overview.png
-message-class-overview.png
-notation.png
-overview.png
-radio-overview.png
diff --git a/docs/ontologies/README.ontologiesdoc b/docs/ontologies/README.ontologiesdoc
deleted file mode 100644
index 17ca7b3ca..000000000
--- a/docs/ontologies/README.ontologiesdoc
+++ /dev/null
@@ -1,74 +0,0 @@
-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.
-
- 
diff --git a/docs/ontologies/explanation.xml.template b/docs/ontologies/explanation.xml.template
deleted file mode 100644
index 5699ee91e..000000000
--- a/docs/ontologies/explanation.xml.template
+++ /dev/null
@@ -1,59 +0,0 @@
-<!--
- 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>
diff --git a/docs/ontologies/index.html b/docs/ontologies/index.html
deleted file mode 100644
index 8a635edcf..000000000
--- a/docs/ontologies/index.html
+++ /dev/null
@@ -1,57 +0,0 @@
-<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>
diff --git a/docs/reference/ontology/Makefile.am b/docs/reference/ontology/Makefile.am
index 0053fb13e..6414e5160 100644
--- a/docs/reference/ontology/Makefile.am
+++ b/docs/reference/ontology/Makefile.am
@@ -1,19 +1,19 @@
 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 +=                                          \
diff --git a/docs/ontologies/mfo/explanation.xml b/docs/reference/ontology/mfo-introduction.xml
index d78aff3e1..d78aff3e1 100644
--- a/docs/ontologies/mfo/explanation.xml
+++ b/docs/reference/ontology/mfo-introduction.xml
diff --git a/docs/ontologies/mlo/explanation.xml b/docs/reference/ontology/mlo-introduction.xml
index 0940da721..0940da721 100644
--- a/docs/ontologies/mlo/explanation.xml
+++ b/docs/reference/ontology/mlo-introduction.xml
diff --git a/docs/ontologies/nco/explanation.xml b/docs/reference/ontology/nco-introduction.xml
index b60e6f451..b60e6f451 100644
--- a/docs/ontologies/nco/explanation.xml
+++ b/docs/reference/ontology/nco-introduction.xml
diff --git a/docs/ontologies/nie/explanation.xml b/docs/reference/ontology/nie-introduction.xml
index d1e4e6647..d1e4e6647 100644
--- a/docs/ontologies/nie/explanation.xml
+++ b/docs/reference/ontology/nie-introduction.xml
diff --git a/docs/ontologies/nmm/explanation.xml b/docs/reference/ontology/nmm-introduction.xml
index 0da24c25e..0da24c25e 100644
--- a/docs/ontologies/nmm/explanation.xml
+++ b/docs/reference/ontology/nmm-introduction.xml
diff --git a/docs/ontologies/nmo/explanation.xml b/docs/reference/ontology/nmo-introduction.xml
index 48a2dfb85..48a2dfb85 100644
--- a/docs/ontologies/nmo/explanation.xml
+++ b/docs/reference/ontology/nmo-introduction.xml
diff --git a/docs/ontologies/xsd/explanation.xml b/docs/reference/ontology/xsd-introduction.xml
index 6fab3bdb7..6fab3bdb7 100644
--- a/docs/ontologies/xsd/explanation.xml
+++ b/docs/reference/ontology/xsd-introduction.xml
diff --git a/docs/tools/gen-doc.sh b/docs/tools/gen-doc.sh
index 10e06342e..b10142f9a 100755
--- a/docs/tools/gen-doc.sh
+++ b/docs/tools/gen-doc.sh
@@ -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"
diff --git a/docs/tools/ttl2sgml.c b/docs/tools/ttl2sgml.c
index 5da1194b1..065d445bf 100644
--- a/docs/tools/ttl2sgml.c
+++ b/docs/tools/ttl2sgml.c
@@ -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);
diff --git a/docs/tools/ttl_sgml.c b/docs/tools/ttl_sgml.c
index df6fc4f5d..6096c9a98 100644
--- a/docs/tools/ttl_sgml.c
+++ b/docs/tools/ttl_sgml.c
@@ -125,20 +125,6 @@ print_sgml_header (FILE *f, OntologyDescription *desc)
 }
 
 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)
 {
 	g_fprintf (f,"</chapter>\n");
@@ -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);
diff --git a/docs/tools/ttl_sgml.h b/docs/tools/ttl_sgml.h
index 3cf7a31ee..b2d9f23f6 100644
--- a/docs/tools/ttl_sgml.h
+++ b/docs/tools/ttl_sgml.h
@@ -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