[tracker/wip/carlosg/domain-ontologies: 56/93] docs: Use xi:include to optionally load ontology explanations

[Carlos Garnacho <carlosg src gnome org>]

commit f397de90e291b995ebaf5ad9344b37b02a9d75bf
Author: Carlos Garnacho <carlosg gnome org>
Date:   Thu Jun 15 16:27:29 2017 +0200

    docs: Use xi:include to optionally load ontology explanations
    
    Less toggles on the doc generation tool, more seamless documentation
    blending. Sounds like win-win.

 docs/ontologies/.gitignore                         |    8 --
 docs/ontologies/README.ontologiesdoc               |   74 --------------------
 docs/ontologies/explanation.xml.template           |   59 ----------------
 docs/ontologies/index.html                         |   57 ---------------
 docs/reference/ontology/Makefile.am                |   22 +++---
 .../ontology/mfo-introduction.xml}                 |    0
 .../ontology/mlo-introduction.xml}                 |    0
 .../ontology/nco-introduction.xml}                 |    0
 .../ontology/nie-introduction.xml}                 |    0
 .../ontology/nmm-introduction.xml}                 |    0
 .../ontology/nmo-introduction.xml}                 |    0
 .../ontology/xsd-introduction.xml}                 |    0
 docs/tools/gen-doc.sh                              |    8 +--
 docs/tools/ttl2sgml.c                              |    7 +--
 docs/tools/ttl_sgml.c                              |   21 +-----
 docs/tools/ttl_sgml.h                              |    5 +-
 16 files changed, 19 insertions(+), 242 deletions(-)
---
diff --git a/docs/reference/ontology/Makefile.am b/docs/reference/ontology/Makefile.am
index 0053fb1..6414e51 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
similarity index 100%
rename from docs/ontologies/mfo/explanation.xml
rename to docs/reference/ontology/mfo-introduction.xml
diff --git a/docs/ontologies/mlo/explanation.xml b/docs/reference/ontology/mlo-introduction.xml
similarity index 100%
rename from docs/ontologies/mlo/explanation.xml
rename to docs/reference/ontology/mlo-introduction.xml
diff --git a/docs/ontologies/nco/explanation.xml b/docs/reference/ontology/nco-introduction.xml
similarity index 100%
rename from docs/ontologies/nco/explanation.xml
rename to docs/reference/ontology/nco-introduction.xml
diff --git a/docs/ontologies/nie/explanation.xml b/docs/reference/ontology/nie-introduction.xml
similarity index 100%
rename from docs/ontologies/nie/explanation.xml
rename to docs/reference/ontology/nie-introduction.xml
diff --git a/docs/ontologies/nmm/explanation.xml b/docs/reference/ontology/nmm-introduction.xml
similarity index 100%
rename from docs/ontologies/nmm/explanation.xml
rename to docs/reference/ontology/nmm-introduction.xml
diff --git a/docs/ontologies/nmo/explanation.xml b/docs/reference/ontology/nmo-introduction.xml
similarity index 100%
rename from docs/ontologies/nmo/explanation.xml
rename to docs/reference/ontology/nmo-introduction.xml
diff --git a/docs/ontologies/xsd/explanation.xml b/docs/reference/ontology/xsd-introduction.xml
similarity index 100%
rename from docs/ontologies/xsd/explanation.xml
rename to docs/reference/ontology/xsd-introduction.xml
diff --git a/docs/tools/gen-doc.sh b/docs/tools/gen-doc.sh
index 10e0634..b10142f 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 5da1194..065d445 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 df6fc4f..6096c9a 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 3cf7a31..b2d9f23 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