build: Modernise the API reference

Let's use modern, idiomatic gtk-doc to generate the API reference:

 - use XInclude
 - stop using SGML mode with XML files
 - drop version.xml and use the gtk-doc package entities

diff --git a/configure.ac b/configure.ac
index 49065be..870844b 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -198,7 +198,7 @@ AC_DEFINE_UNQUOTED(GETTEXT_PACKAGE, ["$GETTEXT_PACKAGE"],
 GOBJECT_INTROSPECTION_CHECK([1.32.0])
 
 # Documentation support
-GTK_DOC_CHECK([1.13])
+GTK_DOC_CHECK([1.25])
 
 # define a MAINT-like variable REBUILD which is set if Perl
 # and awk are found, so autogenerated sources can be rebuilt
@@ -267,7 +267,6 @@ win32/vs12/Makefile
 win32/vs14/Makefile
 win32/vs15/Makefile
 docs/Makefile
-docs/version.xml
 config.h.win32
 ])
 

diff --git a/docs/Makefile.am b/docs/Makefile.am
index 88c122b..21ab956 100644 (file)
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -1,18 +1,16 @@
 ## Process this file with automake to produce Makefile.in
 
-AUTOMAKE_OPTIONS = 1.6
-
 # The name of the module.
-DOC_MODULE=atk
+DOC_MODULE = atk
 
 # The top-level SGML file.
-DOC_MAIN_SGML_FILE=atk-docs.sgml
+DOC_MAIN_SGML_FILE = atk-docs.xml
 
 # Extra options to supply to gtkdoc-scan
-SCAN_OPTIONS=--deprecated-guards=G_DISABLE_DEPRECATED
+SCAN_OPTIONS = --deprecated-guards=ATK_DISABLE_DEPRECATED
 
 # The directory containing the source code (if it contains documentation).
-DOC_SOURCE_DIR=$(top_srcdir)/atk $(top_builddir)/atk
+DOC_SOURCE_DIR = $(top_srcdir)/atk $(top_builddir)/atk
 
 # Used for dependencies
 HFILE_GLOB = $(top_srcdir)/atk/*.h
@@ -28,18 +26,21 @@ IGNORE_HFILES =     \
 AM_CPPFLAGS =                  \
        -I$(top_srcdir)         \
        -I$(top_builddir)       \
+       -DATK_DISABLE_DEPRECATION_WARNINGS \
        $(DEP_CFLAGS)
 
-GTKDOC_LIBS = $(top_builddir)/atk/libatk-$(ATK_API_VERSION).la \
-              $(DEP_LIBS)
+GTKDOC_LIBS = \
+       $(top_builddir)/atk/libatk-$(ATK_API_VERSION).la \
+       $(DEP_LIBS)
 
 # gtkdoc-mkdb related varaibles
-MKDB_OPTIONS =--sgml-mode
-content_files =                \
-       version.xml
+MKDB_OPTIONS =
+
+content_files =
+
 HTML_IMAGES =
 
 include $(top_srcdir)/gtk-doc.make
 
 # Other files to distribute
-EXTRA_DIST += version.xml.in
+#EXTRA_DIST +=

diff --git a/docs/atk-docs.sgml b/docs/atk-docs.xml
similarity index 54%
rename from docs/atk-docs.sgml
rename to docs/atk-docs.xml
index 2d9991e..f3dfcce 100644 (file)
--- a/docs/atk-docs.sgml
+++ b/docs/atk-docs.xml
@@ -1,44 +1,16 @@
 <?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-  <!ENTITY atk-AtkAction SYSTEM "xml/atkaction.xml">
-  <!ENTITY atk-AtkComponent SYSTEM "xml/atkcomponent.xml">
-  <!ENTITY atk-AtkDocument SYSTEM "xml/atkdocument.xml">
-  <!ENTITY atk-AtkEditabletext SYSTEM "xml/atkeditabletext.xml">
-  <!ENTITY atk-AtkGObjectAccessible SYSTEM "xml/atkgobjectaccessible.xml">
-  <!ENTITY atk-AtkHyperlink SYSTEM "xml/atkhyperlink.xml">
-  <!ENTITY atk-AtkHyperlinkImpl SYSTEM "xml/atkhyperlinkimpl.xml">
-  <!ENTITY atk-AtkHypertext SYSTEM "xml/atkhypertext.xml">
-  <!ENTITY atk-AtkImage SYSTEM "xml/atkimage.xml">
-  <!ENTITY atk-AtkMisc SYSTEM "xml/atkmisc.xml">
-  <!ENTITY atk-AtkNoOpObject SYSTEM "xml/atknoopobject.xml">
-  <!ENTITY atk-AtkNoOpObjectFactory SYSTEM "xml/atknoopobjectfactory.xml">
-  <!ENTITY atk-AtkPlug SYSTEM "xml/atkplug.xml">
-  <!ENTITY atk-AtkObject SYSTEM "xml/atkobject.xml">
-  <!ENTITY atk-AtkObjectFactory SYSTEM "xml/atkobjectfactory.xml">
-  <!ENTITY atk-AtkRange SYSTEM "xml/atkrange.xml">
-  <!ENTITY atk-AtkRegistry SYSTEM "xml/atkregistry.xml">
-  <!ENTITY atk-AtkRelation SYSTEM "xml/atkrelation.xml">
-  <!ENTITY atk-AtkRelationSet SYSTEM "xml/atkrelationset.xml">
-  <!ENTITY atk-AtkSelection SYSTEM "xml/atkselection.xml">
-  <!ENTITY atk-AtkSocket SYSTEM "xml/atksocket.xml">
-  <!ENTITY atk-AtkState SYSTEM "xml/atkstate.xml">
-  <!ENTITY atk-AtkStateSet SYSTEM "xml/atkstateset.xml">
-  <!ENTITY atk-AtkStreamableContent SYSTEM "xml/atkstreamablecontent.xml">
-  <!ENTITY atk-AtkTable SYSTEM "xml/atktable.xml">
-  <!ENTITY atk-AtkTableCell SYSTEM "xml/atktablecell.xml">
-  <!ENTITY atk-AtkText SYSTEM "xml/atktext.xml">
-  <!ENTITY atk-AtkUtil SYSTEM "xml/atkutil.xml">
-  <!ENTITY atk-AtkValue SYSTEM "xml/atkvalue.xml">
-  <!ENTITY atk-AtkWindow SYSTEM "xml/atkwindow.xml">
-  <!ENTITY atk-AtkVersion SYSTEM "xml/atkversion.xml">
-  <!ENTITY version SYSTEM "version.xml">
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+  <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
+  %gtkdocentities;
 ]>
 
 <book>
   <bookinfo>
     <title>ATK - Accessibility Toolkit</title>
-    <releaseinfo>for ATK &version;</releaseinfo>
+    <releaseinfo>for ATK &package_version;</releaseinfo>
   </bookinfo>
 
   <chapter id="overview">
@@ -66,61 +38,61 @@
 
   <chapter id="base-object">
     <title>Base accessibility object</title>
-    &atk-AtkObject;
+    <xi:include href="xml/atkobject.xml"/>
   </chapter>
 
   <chapter id="toolkit">
     <title>Event and toolkit support</title>
-    &atk-AtkUtil;
+    <xi:include href="xml/atkutil.xml"/>
   </chapter>
 
   <chapter id="interfaces">
     <title>ATK Interfaces</title>
-    &atk-AtkAction;
-    &atk-AtkComponent;
-    &atk-AtkDocument;
-    &atk-AtkEditabletext;
-    &atk-AtkHyperlinkImpl;
-    &atk-AtkHypertext;
-    &atk-AtkImage;
-    &atk-AtkSelection;
-    &atk-AtkStreamableContent;
-    &atk-AtkTable;
-    &atk-AtkTableCell;
-    &atk-AtkText;
-    &atk-AtkValue;
-    &atk-AtkWindow;
+    <xi:include href="xml/atkaction.xml"/>
+    <xi:include href="xml/atkcomponent.xml"/>
+    <xi:include href="xml/atkdocument.xml"/>
+    <xi:include href="xml/atkeditabletext.xml"/>
+    <xi:include href="xml/atkhyperlinkimpl.xml"/>
+    <xi:include href="xml/atkhypertext.xml"/>
+    <xi:include href="xml/atkimage.xml"/>
+    <xi:include href="xml/atkselection.xml"/>
+    <xi:include href="xml/atkstreamablecontent.xml"/>
+    <xi:include href="xml/atktable.xml"/>
+    <xi:include href="xml/atktablecell.xml"/>
+    <xi:include href="xml/atktext.xml"/>
+    <xi:include href="xml/atkvalue.xml"/>
+    <xi:include href="xml/atkwindow.xml"/>
   </chapter>
 
   <chapter id="data">
     <title>Basic accessible data types</title>
-    &atk-AtkRange;
-    &atk-AtkRelation;
-    &atk-AtkRelationSet;
-    &atk-AtkState;
-    &atk-AtkStateSet;
+    <xi:include href="xml/atkrange.xml"/>
+    <xi:include href="xml/atkrelation.xml"/>
+    <xi:include href="xml/atkrelationset.xml"/>
+    <xi:include href="xml/atkstate.xml"/>
+    <xi:include href="xml/atkstateset.xml"/>
   </chapter>
 
   <chapter id="accessibles">
     <title>Custom accessible objects</title>
-    &atk-AtkGObjectAccessible;
-    &atk-AtkHyperlink;
-    &atk-AtkNoOpObject;
-    &atk-AtkPlug;
-    &atk-AtkSocket;
+    <xi:include href="xml/atkgobjectaccessible.xml"/>
+    <xi:include href="xml/atkhyperlink.xml"/>
+    <xi:include href="xml/atknoopobject.xml"/>
+    <xi:include href="xml/atkplug.xml"/>
+    <xi:include href="xml/atksocket.xml"/>
   </chapter>
 
   <chapter id="utilities">
     <title>Utilities</title>
-    &atk-AtkNoOpObjectFactory;
-    &atk-AtkObjectFactory;
-    &atk-AtkRegistry;
-    &atk-AtkVersion;
+    <xi:include href="xml/atknoopobjectfactory.xml"/>
+    <xi:include href="xml/atkobjectfactory.xml"/>
+    <xi:include href="xml/atkregistry.xml"/>
+    <xi:include href="xml/atkversion.xml"/>
   </chapter>
 
   <chapter id="deprecated">
     <title>Deprecated Interfaces</title>
-    &atk-AtkMisc;
+    <xi:include href="xml/atkmisc.xml"/>
   </chapter>
 
   <index id="api-index-full">
@@ -168,5 +140,7 @@
   <index id="api-index-2-12" role="2.12">
     <title>Index of new symbols in 2.12</title>
   </index>
+
+  <xi:include href="xml/annotation-glossary.xml"><xi:fallback/></xi:include>
 </book>
 

diff --git a/docs/meson.build b/docs/meson.build
index d2dac1c..fb26d40 100644 (file)
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -1,18 +1,11 @@
 subdir('xml')
 
-version_xml_conf = configuration_data()
-version_xml_conf.set('ATK_VERSION', meson.project_version())
-configure_file(input: 'version.xml.in',
-               output: 'version.xml',
-               configuration: version_xml_conf)
-
 private_headers = [
   'atkmarshal.h',
   'atkintl.h',
 ]
 
 content_files = [
-  'version.xml',
 ]
 
 html_images = [
@@ -23,7 +16,7 @@ glib_docpath = join_paths(glib_prefix, 'share', 'gtk-doc', 'html')
 docpath = join_paths(atk_datadir, 'gtk-doc', 'html')
 
 gnome.gtkdoc('atk',
-             main_xml: 'atk-docs.sgml',
+             main_xml: 'atk-docs.xml',
              src_dir: [
                join_paths(meson.source_root(), 'atk'),
                join_paths(meson.build_root(), 'atk'),
@@ -37,7 +30,6 @@ gnome.gtkdoc('atk',
                '--ignore-headers=' + ' '.join(private_headers),
              ],
              mkdb_args: [
-               '--sgml-mode',
                '--output-format=xml',
              ],
              fixxref_args: [

diff --git a/docs/version.xml.in b/docs/version.xml.in
deleted file mode 100644 (file)
index e2242c8..0000000
--- a/docs/version.xml.in
+++ /dev/null
@@ -1 +0,0 @@
-@ATK_VERSION@