[tracker] Include diagrams in png in the generated documentation

[Ivan Frade <ifrade src gnome org>]

commit 14bd86e0291064205a96f21924566d075492b3b0
Author: Ivan Frade <ivan frade nokia com>
Date:   Wed Jan 27 20:32:57 2010 +0200

    Include diagrams in png in the generated documentation

 docs/ontologies/README.ontologiesdoc |   52 +++++++++++++++++++---------------
 docs/reference/ontology/Makefile.am  |   11 ++++++-
 docs/tools/Makefile.am               |   26 ++++++++++------
 3 files changed, 54 insertions(+), 35 deletions(-)
---
diff --git a/docs/ontologies/README.ontologiesdoc b/docs/ontologies/README.ontologiesdoc
index 3fc552d..148159e 100644
--- a/docs/ontologies/README.ontologiesdoc
+++ b/docs/ontologies/README.ontologiesdoc
@@ -7,39 +7,45 @@ Expected documents/format
 =========================
 
 1) There should be one directory per ontology prefix.
-2) In that directory, there must be a file called 'explanation.html'
-   This file will be copied as-it-is into the ontology webpage
-3) That file can link to any other files in the same directory
-   All files in the directory will be copied together in the final web
-   directory (*)
+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 _in two places_
+    - docs/tools/Makefile.am (ONTOLOGY_DIAGRAMS variable)
+    - docs/reference/ontology/Makefile.am (ONTOLOGY_DIAGRAMS variable)
 
 (*) .dia files will be exported as PNG.
 
-Explanation.html
+Explanation.xml
 ================
 
- It must be a file in HTML format with <h2> as "biggest" elements (i.e. sections).
-It will be copied as-it-is into the ontology HTML page, so it shouldn't include all
-HTML headers (i.e. it is NOT a valid HTML document).
+ 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 can be linked using
+ The classes/properties inside the ontology has id's with the
+following schema:
 
-   <a href="#ClassName">
+   [prefix-ontology]-[name-property-or-class]
 
- and classes/properties in other ontologies with
+ so the property "nmm:length" has the id "nmm-length" and
+the class "nmm:MusicPiece" has the id "nmm-MusicPiece".
 
-   <a href="../ontology-prefix/index.html#ClassName">
+ 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:
 
- Dia diagrams (x.dia) in the directory will be converted automatically
- in png, and should be linked using the png extension:
+ E.G. <graphic fileref="images-overview.png" ...
 
-    <a href="x.png">
-
-
- To include verbatim examples in SparQL or turtle format, use the
-<pre> HTML tag, and all "<" and ">" inside it must be written as
-"&lt;" and "%gt;".
-
- The file "explanation.html.template" can be used as starting point.
+ The file "explanation.xml.template" contains an example of the usual
+sections in the documentation and the most common docbook elements.
diff --git a/docs/reference/ontology/Makefile.am b/docs/reference/ontology/Makefile.am
index ee2a7cc..b6b4096 100644
--- a/docs/reference/ontology/Makefile.am
+++ b/docs/reference/ontology/Makefile.am
@@ -33,8 +33,15 @@ content_files =						\
 
 expand_content_files =
 
+ONTOLOGY_DIAGRAMS = 					\
+	notation.png					\
+	feeds-overview.png				\
+	radio-overview.png				\
+	images-overview.png				\
+	overview.png
+
 # Images to copy into HTML directory
-HTML_IMAGES = ontology.png notation.png
+HTML_IMAGES = ontology.png notation.png $(ONTOLOGY_DIAGRAMS)
 
 # Extra options to supply to gtkdoc-fixref
 FIXXREF_OPTIONS =
@@ -42,4 +49,4 @@ FIXXREF_OPTIONS =
 include $(top_srcdir)/gtk-doc.make
 
 # Other files to distribute
-EXTRA_DIST += version.xml.in ontology.png
+EXTRA_DIST += version.xml.in $(HTML_IMAGES)
diff --git a/docs/tools/Makefile.am b/docs/tools/Makefile.am
index 0667134..d6335cc 100644
--- a/docs/tools/Makefile.am
+++ b/docs/tools/Makefile.am
@@ -51,20 +51,26 @@ ontology.png: ontology.dot
 	$(AM_V_GEN)$(GRAPHVIZ_FDP) -Tpng -o ontology.png ontology.dot
 	cp ontology.png $(top_builddir)/docs/reference/ontology/
 
-notation.png: 								
-	dia -t png ../ontologies/notation.dia 				
-	cp notation.png $(top_builddir)/docs/reference/ontology/
-
-resources:
-	cp `find $(top_builddir)/docs/ontologies -name "*.dia"` /tmp
+#
+# The origianal diagram but with .png extension
+# Horrible, i know.
+#
+ONTOLOGY_DIAGRAMS=							\
+	../ontologies/notation.png					\
+	../ontologies/mfo/feeds-overview.png				\
+	../ontologies/nmm/radio-overview.png				\
+	../ontologies/nmm/images-overview.png				\
+	../ontologies/nie/overview.png
+
+.dia.png:
+	dia -t png $<
+	cp $(notdir $(<:.dia=.png)) $(top_builddir)/docs/reference/ontology
 
 BUILT_SOURCES = 							\
 	ontology.png							\
-	notation.png							\
 	gen-doc.stamp
 
 EXTRA_DIST = 								\
-	$(BUILT_SOURCES)						\
 	gen-doc.sh
 
 DISTCLEANFILES = 							\
@@ -72,6 +78,6 @@ DISTCLEANFILES = 							\
 	$(top_builddir)/docs/reference/ontology/notation.png		\
 	$(top_builddir)/docs/reference/ontology/ontology.png
 
-CLEANFILES = $(BUILT_SOURCES)
+CLEANFILES = $(BUILT_SOURCES) $(notdir $(ONTOLOGY_DIAGRAMS:.dia=.png))
 
-make-hook: ontology-graph ontology.dot ontology.png notation.png resources
+make-hook: ontology-graph ontology.dot ontology.png