2003-09-29 Havoc Pennington <hp@pobox.com>

	* configure.in: split checks for Doxygen from XML docs, check for
	xmlto

	* doc/Makefile.am: XML-ify all the docs, and add a blank
	dbus-tutorial.xml

6 files changed, 179 insertions, 91 deletions

diff --git a/ChangeLog b/ChangeLog
index 30b1dd7f..575d3568 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,13 @@
 2003-09-29  Havoc Pennington  <hp@pobox.com>
 
+	* configure.in: split checks for Doxygen from XML docs, check for
+	xmlto
+
+	* doc/Makefile.am: XML-ify all the docs, and add a blank
+	dbus-tutorial.xml
+
+2003-09-29  Havoc Pennington  <hp@pobox.com>
+
 	* Merge dbus-object-names branch. To see the entire patch 
 	do cvs diff -r DBUS_OBJECT_NAMES_BRANCHPOINT -r dbus-object-names,
 	it's huuuuge though.
diff --git a/configure.in b/configure.in
index 9665cb03..8a2c7aad 100644
--- a/configure.in
+++ b/configure.in
@@ -30,7 +30,8 @@ AC_ARG_ENABLE(ansi,             [  --enable-ansi         enable -ansi -pedantic
 AC_ARG_ENABLE(verbose-mode,     [  --enable-verbose-mode support verbose debug mode],enable_verbose_mode=$enableval,enable_verbose_mode=$USE_MAINTAINER_MODE)
 AC_ARG_ENABLE(asserts,          [  --enable-asserts      include assertion checks],enable_asserts=$enableval,enable_asserts=$USE_MAINTAINER_MODE)
 AC_ARG_ENABLE(checks,           [  --enable-checks       include sanity checks on public API],enable_checks=$enableval,enable_checks=yes)
-AC_ARG_ENABLE(docs,             [  --enable-docs         build documentation (requires Doxygen and jade)],enable_docs=$enableval,enable_docs=auto)
+AC_ARG_ENABLE(xml-docs,         [  --enable-xml-docs     build XML documentation (requires xmlto)],enable_xml_docs=$enableval,enable_xml_docs=auto)
+AC_ARG_ENABLE(doxygen-docs,     [  --enable-doxygen-docs     build DOXYGEN documentation (requires Doxygen)],enable_doxygen_docs=$enableval,enable_doxygen_docs=auto)
 AC_ARG_ENABLE(gcov,             [  --enable-gcov         compile with coverage profiling instrumentation (gcc only)],enable_gcov=$enableval,enable_gcov=no)
 AC_ARG_ENABLE(abstract-sockets, [  --enable-abstract-sockets  use abstract socket namespace (linux only)],enable_abstract_sockets=$enableval,enable_abstract_sockets=auto)
 AC_ARG_ENABLE(gcj,              [  --enable-gcj          build gcj bindings],enable_gcj=$enableval,enable_gcj=no)
@@ -685,34 +686,62 @@ fi
 AC_SUBST(DBUS_X_CFLAGS)
 AC_SUBST(DBUS_X_LIBS)
 
-### Documentation
+### Doxygen Documentation
 
 AC_PATH_PROG(DOXYGEN, doxygen, no)
-AC_PATH_PROG(DB2HTML, db2html, no)
 
-AC_MSG_CHECKING([whether to build documentation])
+AC_MSG_CHECKING([whether to build Doxygen documentation])
 
-if test x$DOXYGEN = xno -o x$DB2HTML = xno ; then
-    have_docs_tools=no
+if test x$DOXYGEN = xno ; then
+    have_doxygen=no
 else
-    have_docs_tools=yes
+    have_doxygen=yes
 fi
 
-if test x$enable_docs = xauto ; then
-    if test x$have_docs_tools = xno ; then
-        enable_docs=no
+if test x$enable_doxygen_docs = xauto ; then
+    if test x$have_doxygen = xno ; then
+        enable_doxygen_docs=no
     else
-        enable_docs=yes
+        enable_doxygen_docs=yes
     fi
 fi
 
-if test x$enable_docs = xyes; then
-    if test x$have_docs_tools = xno; then
-	AC_MSG_ERROR([Building docs explicitly required, but Doxygen or db2html not found])
+if test x$enable_doxygen_docs = xyes; then
+    if test x$have_doxygen = xno; then
+	AC_MSG_ERROR([Building Doxygen docs explicitly required, but Doxygen not found])
     fi
 fi
 
-AM_CONDITIONAL(DBUS_DOCS_ENABLED, test x$enable_docs = xyes)
+AM_CONDITIONAL(DBUS_DOXYGEN_DOCS_ENABLED, test x$enable_doxygen_docs = xyes)
+AC_MSG_RESULT(yes)
+
+### XML Documentation
+
+AC_PATH_PROG(XMLTO, xmlto, no)
+
+AC_MSG_CHECKING([whether to build XML documentation])
+
+if test x$XMLTO = xno ; then
+    have_xmlto=no
+else
+    have_xmlto=yes
+fi
+
+if test x$enable_xml_docs = xauto ; then
+    if test x$have_xmlto = xno ; then
+        enable_xml_docs=no
+    else
+        enable_xml_docs=yes
+    fi
+fi
+
+if test x$enable_xml_docs = xyes; then
+    if test x$have_xmlto = xno; then
+	AC_MSG_ERROR([Building XML docs explicitly required, but xmlto not found])
+    fi
+fi
+
+AM_CONDITIONAL(DBUS_XML_DOCS_ENABLED, test x$enable_xml_docs = xyes)
 AC_MSG_RESULT(yes)
 
 #### Have to go $localstatedir->$prefix/var->/usr/local/var   
@@ -941,7 +970,7 @@ echo "
 	cxxflags:		  ${CXXFLAGS}
 	64-bit int:		  ${DBUS_INT64_TYPE}
         Doxygen:                  ${DOXYGEN}
-        db2html:                  ${DB2HTML}"
+        xmlto:                    ${XMLTO}"
 
 if test x$enable_gcj = xyes ; then
 echo \
@@ -975,7 +1004,8 @@ echo "
         Building Python bindings: ${have_python}
         Building GTK+ tools:      ${have_gtk}
         Building X11 code:        ${enable_x11}
-        Building documentation:   ${enable_docs}
+        Building Doxygen docs:    ${enable_doxygen_docs}
+        Building XML docs:        ${enable_xml_docs}
         Using XML parser:         ${with_xml}
         Init scripts style:       ${with_init_scripts}
         Abstract socket names:    ${have_abstract_sockets}
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 5bd9fb1e..7bd392a6 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,38 +1,30 @@
 EXTRA_DIST= 					\
 	dbus-specification.html			\
-	dbus-specification.sgml			\
+	dbus-specification.xml			\
 	dbus-test-plan.html			\
-	dbus-test-plan.sgml			\
+	dbus-test-plan.xml			\
+	dbus-tutorial.html			\
+	dbus-tutorial.xml			\
 	dcop-howto.txt				\
 	file-boilerplate.c
 
-if DBUS_DOCS_ENABLED
-all-local: dbus-specification.html dbus-test-plan.html
+HTML_FILES=					\
+	dbus-specification.html			\
+	dbus-test-plan.html			\
+	dbus-tutorial.html
+
+if DBUS_XML_DOCS_ENABLED
+all-local: $(HTML_FILES)
 endif
 
-## Debian db2html outputs to stdout, so we collect stdout and use 
-## it if we didn't get the proper output
+dbus-specification.html: dbus-specification.xml
+	$(XMLTO) html-nochunks $<
 
-dbus-specification.html: dbus-specification.sgml
-	rm -f $@ &&							\
-	$(DB2HTML) -o . --nochunks $< > $@.stdout &&			\
-	(test -e $@ && rm -f $@.stdout || mv $@.stdout $@) &&		\
-	rm -rf $(srcdir)/dbus-specification/stylesheet-images &&	\
-	(if test -d $(srcdir)/dbus-specification ; then			\
-	rmdir $(srcdir)/dbus-specification ; fi)
+dbus-test-plan.html: dbus-test-plan.xml
+	$(XMLTO) html-nochunks $<
 
-dbus-test-plan.html: dbus-test-plan.sgml
-	rm -f $@ &&						\
-	$(DB2HTML) -o . --nochunks $< > $@.stdout &&		\
-	(test -e $@ && rm -f $@.stdout || mv $@.stdout $@) &&	\
-	rm -rf $(srcdir)/dbus-test-plan/stylesheet-images &&	\
-	(if test -d $(srcdir)/dbus-test-plan ; then		\
-	rmdir $(srcdir)/dbus-test-plan ; fi)
+dbus-tutorial.html: dbus-tutorial.xml
+	$(XMLTO) html-nochunks $<
 
 maintainer-clean-local:
-	rm -f dbus-test-plan.html
-	rm -rf dbus-test-plan/stylesheet-images
-	test -d dbus-test-plan && rmdir dbus-test-plan
-	rm -f dbus-specification.html
-	rm -rf dbus-specification/stylesheet-images
-	test -d dbus-specification && rmdir dbus-specification
+	rm -f $(HTML_FILES)
diff --git a/doc/dbus-specification.sgml b/doc/dbus-specification.xml
index 696c3f45..698e35a2 100644
--- a/doc/dbus-specification.sgml
+++ b/doc/dbus-specification.xml
@@ -1,7 +1,11 @@
-<!doctype article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
+[
 ]>
+
 <article id="index">
-  <artheader>
+  <articleinfo>
     <title>D-BUS Specification</title>
     <releaseinfo>Version 0.8</releaseinfo>
     <date>06 September 2003</date>
@@ -10,7 +14,7 @@
 	<firstname>Havoc</firstname>
 	<surname>Pennington</surname>
 	<affiliation>
-	  <orgname>Red Hat, Inc</orgname>
+	  <orgname>Red Hat, Inc.</orgname>
 	  <address>
 	    <email>hp@pobox.com</email>
 	  </address>
@@ -30,14 +34,14 @@
 	<firstname>Alexander</firstname>
 	<surname>Larsson</surname>
 	<affiliation>
-	  <orgname>Red Hat, Inc</orgname>
+	  <orgname>Red Hat, Inc.</orgname>
 	  <address>
             <email>alexl@redhat.com</email>
           </address>
 	</affiliation>
       </author>
     </authorgroup>
-  </artheader>
+  </articleinfo>
 
   <sect1 id="introduction">
     <title>Introduction</title>
@@ -75,10 +79,10 @@
     </para>
     <para>
       The base D-BUS protocol is a peer-to-peer protocol, specified in <xref
-      linkend="message-protocol">. That is, it is a system for one application
+      linkend="message-protocol"/>. That is, it is a system for one application
       to talk to a single other application. However, the primary intended
       application of D-BUS is the D-BUS <firstterm>message bus</firstterm>,
-      specified in <xref linkend="message-bus">. The message bus is a special
+      specified in <xref linkend="message-bus"/>. The message bus is a special
       application that accepts connections from multiple other applications, and
       forwards messages among them.
     </para>
@@ -111,7 +115,7 @@
       <title>Header Encoding</title>
       <para>
         Following the mandatory fields, there are zero or more named fields (see
-        <xref linkend="message-protocol-header-fields">), and then nul bytes
+        <xref linkend="message-protocol-header-fields"/>), and then nul bytes
         padding the header such that its total length in bytes is a multiple of
         8.
       </para>
@@ -119,7 +123,7 @@
         The header MUST begin with the following mandatory fields in the following
         order:
         <informaltable>
-          <tgroup cols=2>
+          <tgroup cols="2">
             <thead>
               <row>
                 <entry>Size</entry>
@@ -185,7 +189,7 @@
       <para>
         Types that can appear in the second byte of the header:
         <informaltable>
-          <tgroup cols=3>
+          <tgroup cols="3">
             <thead>
               <row>
                 <entry>Conventional name</entry>
@@ -228,7 +232,7 @@
       <para>
         Flags that can appear in the third byte of the header:
         <informaltable>
-          <tgroup cols=3>
+          <tgroup cols="3">
             <thead>
               <row>
                 <entry>Conventional name</entry>
@@ -255,7 +259,7 @@
       <title>Header Fields</title>
       <para>
         In addition to the required header information mentioned 
-        in <xref linkend="message-protocol-header-encoding">, 
+        in <xref linkend="message-protocol-header-encoding"/>, 
           the header may contain zero or more named 
           header fields. Future versions of this protocol
           specification may add new fields. Implementations must
@@ -269,7 +273,7 @@
         of which are defined below. Following the name, the field MUST have
         a type code represented as a single unsigned byte, and then a
         properly-aligned value of that type.  See <xref
-        linkend="message-protocol-arguments"> for a description of how each
+        linkend="message-protocol-arguments"/> for a description of how each
         type is encoded. If an implementation sees a header field name that
         it does not understand, it MUST ignore that field.
       </para>
@@ -277,7 +281,7 @@
       <para>
         Here are the currently-defined named header fields:
         <informaltable>
-          <tgroup cols=3>
+          <tgroup cols="3">
             <thead>
               <row>
                 <entry>Conventional Name</entry>
@@ -326,7 +330,7 @@
                 <entry>UINT32</entry>
                 <entry>The serial number of the message this message is a reply
                 to. (The serial number is one of the mandatory header fields,
-                see <xref linkend="message-protocol-header-encoding">.)</entry>
+                see <xref linkend="message-protocol-header-encoding"/>.)</entry>
               </row>
               <row>
                 <entry>SERVICE</entry>
@@ -334,7 +338,7 @@
                 <entry>STRING</entry>
                 <entry>The name of the service this message should be routed to. 
                 Only used in combination with the message bus, see 
-                <xref linkend="message-bus">.</entry>
+                <xref linkend="message-bus"/>.</entry>
               </row>
               <row>
                 <entry>SENDER_SERVICE</entry>
@@ -373,7 +377,7 @@
       </para>
       <para>
         <informaltable>
-          <tgroup cols=3>
+          <tgroup cols="3">
             <thead>
               <row>
                 <entry>Type name</entry>
@@ -442,7 +446,7 @@
       <para>
         The types are encoded as follows:
         <informaltable>
-          <tgroup cols=2>
+          <tgroup cols="2">
             <thead>
               <row>
                 <entry>Type name</entry>
@@ -771,10 +775,10 @@
 
         <itemizedlist>
 	  <listitem><para>AUTH [mechanism] [initial-response]</para></listitem>
-	  <listitem><para>CANCEL</para></listitem
-	                                  <listitem><para>BEGIN</para></listitem>
-	                                  <listitem><para>DATA &lt;data in base 64 encoding&gt;</para></listitem>
-	                                  <listitem><para>ERROR [human-readable error explanation]</para></listitem>
+	  <listitem><para>CANCEL</para></listitem>
+	  <listitem><para>BEGIN</para></listitem>
+	  <listitem><para>DATA &lt;data in base 64 encoding&gt;</para></listitem>
+	  <listitem><para>ERROR [human-readable error explanation]</para></listitem>
 	</itemizedlist>
 
         From server to client are as follows:
@@ -1203,7 +1207,7 @@
   <sect1 id="standard-messages">
     <title>Standard Peer-to-Peer Messages</title>
     <para>
-      See <xref linkend="message-protocol-types-notation"> for details on 
+      See <xref linkend="message-protocol-types-notation"/> for details on 
        the notation used in this section.
     </para>
     <sect2 id="standard-messages-ping">
@@ -1232,7 +1236,7 @@
         </programlisting>
         Message arguments:
         <informaltable>
-          <tgroup cols=3>
+          <tgroup cols="3">
             <thead>
               <row>
                 <entry>Argument</entry>
@@ -1283,7 +1287,7 @@
       </para>
       <para>
         Messages may have a <literal>SERVICE</literal> field (see <xref
-                                                                  linkend="message-protocol-header-fields">).  When the message bus
+                                                                  linkend="message-protocol-header-fields"/>).  When the message bus
           receives a message, if the <literal>SERVICE</literal> field is absent, the
           message is taken to be a standard peer-to-peer message and interpreted
           by the message bus itself. For example, sending
@@ -1396,7 +1400,7 @@
         daemon looks for <firstterm>service description files</firstterm>.
         Service description files define a mapping from service names to
         executables. Different kinds of message bus will look for these files
-        in different places, see <xref linkend="message-bus-types">.
+        in different places, see <xref linkend="message-bus-types"/>.
       </para>
       <para>
         [FIXME the file format should be much better specified than
@@ -1439,7 +1443,7 @@
       <para>
         The executable being launched may want to know whether the message bus
         activating it is one of the well-known message buses (see <xref
-        linkend="message-bus-types">). To facilitate this, the bus MUST also set
+        linkend="message-bus-types"/>). To facilitate this, the bus MUST also set
         the <literal>DBUS_ACTIVATION_BUS_TYPE</literal> environment variable if it is one
         of the well-known buses. The currently-defined values for this variable
         are <literal>system</literal> for the systemwide message bus,
@@ -1530,7 +1534,7 @@
           </programlisting>
           Reply arguments:
           <informaltable>
-            <tgroup cols=3>
+            <tgroup cols="3">
               <thead>
                 <row>
                   <entry>Argument</entry>
@@ -1573,7 +1577,7 @@
           </programlisting>
           Reply arguments:
           <informaltable>
-            <tgroup cols=3>
+            <tgroup cols="3">
               <thead>
                 <row>
                   <entry>Argument</entry>
@@ -1604,7 +1608,7 @@
           </programlisting>
           Message arguments:
           <informaltable>
-            <tgroup cols=3>
+            <tgroup cols="3">
               <thead>
                 <row>
                   <entry>Argument</entry>
@@ -1623,7 +1627,7 @@
           </informaltable>
           Reply arguments:
           <informaltable>
-            <tgroup cols=3>
+            <tgroup cols="3">
               <thead>
                 <row>
                   <entry>Argument</entry>
@@ -1655,7 +1659,7 @@
           </programlisting>
           Message arguments:
           <informaltable>
-            <tgroup cols=3>
+            <tgroup cols="3">
               <thead>
                 <row>
                   <entry>Argument</entry>
@@ -1679,7 +1683,7 @@
           </informaltable>
           Reply arguments:
           <informaltable>
-            <tgroup cols=3>
+            <tgroup cols="3">
               <thead>
                 <row>
                   <entry>Argument</entry>
@@ -1702,7 +1706,7 @@
           specified can be the following values logically ORed together:
 
           <informaltable>
-            <tgroup cols=3>
+            <tgroup cols="3">
               <thead>
                 <row>
                   <entry>Identifier</entry>
@@ -1738,7 +1742,7 @@
           The return value can be one of the following values:
 
           <informaltable>
-            <tgroup cols=3>
+            <tgroup cols="3">
               <thead>
                 <row>
                   <entry>Identifier</entry>
@@ -1781,7 +1785,7 @@
           </programlisting>
           Message arguments:
           <informaltable>
-            <tgroup cols=3>
+            <tgroup cols="3">
               <thead>
                 <row>
                   <entry>Argument</entry>
@@ -1818,7 +1822,7 @@
           </programlisting>
           Message arguments:
           <informaltable>
-            <tgroup cols=3>
+            <tgroup cols="3">
               <thead>
                 <row>
                   <entry>Argument</entry>
@@ -1860,7 +1864,7 @@
           </programlisting>
           Message arguments:
           <informaltable>
-            <tgroup cols=3>
+            <tgroup cols="3">
               <thead>
                 <row>
                   <entry>Argument</entry>
@@ -1898,7 +1902,7 @@
           </programlisting>
           Message arguments:
           <informaltable>
-            <tgroup cols=3>
+            <tgroup cols="3">
               <thead>
                 <row>
                   <entry>Argument</entry>
@@ -1936,7 +1940,7 @@
           </programlisting>
           Message arguments:
           <informaltable>
-            <tgroup cols=3>
+            <tgroup cols="3">
               <thead>
                 <row>
                   <entry>Argument</entry>
@@ -1960,7 +1964,7 @@
           </informaltable>
         Reply arguments:
         <informaltable>
-          <tgroup cols=3>
+          <tgroup cols="3">
             <thead>
               <row>
                 <entry>Argument</entry>
@@ -1977,7 +1981,7 @@
             </tbody>
           </tgroup>
         </informaltable>
-          Tries to launch the executable associated with a service. For more information, see <xref linkend="message-bus-activation">.
+          Tries to launch the executable associated with a service. For more information, see <xref linkend="message-bus-activation"/>.
 
             [FIXME need semantics in much more detail here; for example, 
             if I activate a service then send it a message, is the message 
@@ -1986,7 +1990,7 @@
         <para>
           The return value can be one of the following values:
     <informaltable>
-            <tgroup cols=3>
+            <tgroup cols="3">
               <thead>
                 <row>
                   <entry>Identifier</entry>
@@ -2170,7 +2174,7 @@
           An application is said to <firstterm>own</firstterm> a service if the
           message bus has associated the application with the service name.
           Services may also have <firstterm>secondary owners</firstterm> (see
-          <xref linkend="term-secondary-owner">).
+          <xref linkend="term-secondary-owner"/>).
         </para>
       </glossdef>
     </glossentry>
@@ -2187,7 +2191,7 @@
       <glossdef>
         <para>
           ".service files" tell the bus how to activate a particular service.
-          See <xref linkend="term-activation">
+          See <xref linkend="term-activation"/>
         </para>
       </glossdef>
     </glossentry>
diff --git a/doc/dbus-test-plan.sgml b/doc/dbus-test-plan.xml
index 755ed22a..bcb9b3e6 100644
--- a/doc/dbus-test-plan.sgml
+++ b/doc/dbus-test-plan.xml
@@ -1,7 +1,11 @@
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
+[
 ]>
+
 <article id="index">
-  <artheader>
+  <articleinfo>
     <title>D-BUS Test Plan</title>
     <date>14 February 2003</date>
     <authorgroup>
@@ -14,7 +18,7 @@
 	</affiliation>
       </author>
     </authorgroup>
-  </artheader>
+  </articleinfo>
   <sect1 id="introduction">
     <title>Introduction</title>
     <para>
diff --git a/doc/dbus-tutorial.xml b/doc/dbus-tutorial.xml
new file mode 100644
index 00000000..10cfc79f
--- /dev/null
+++ b/doc/dbus-tutorial.xml
@@ -0,0 +1,50 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
+[
+]>
+
+<article id="index">
+  <articleinfo>
+    <title>D-BUS Tutorial</title>
+    <releaseinfo>Version 0.1</releaseinfo>
+    <date>29 September 2003</date>
+    <authorgroup>
+      <author>
+	<firstname>Havoc</firstname>
+	<surname>Pennington</surname>
+	<affiliation>
+	  <orgname>Red Hat, Inc.</orgname>
+	  <address>
+	    <email>hp@pobox.com</email>
+	  </address>
+	</affiliation>
+      </author>
+    </authorgroup>
+  </articleinfo>
+
+  <sect1 id="introduction">
+    <title>Introduction</title>
+    <para>
+      D-BUS blah blah blah
+      <itemizedlist>
+        <listitem>
+          <para>
+            foo
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            bar
+          </para>
+        </listitem>
+      </itemizedlist>
+    </para>
+    <para>
+      blah blah blah
+    </para>
+    <para>
+      blah blah blah
+    </para>
+  </sect1>
+</article>