diff --git a/ChangeLog b/ChangeLog index 30b1dd7f..575d3568 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,11 @@ +2003-09-29 Havoc Pennington + + * 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 * Merge dbus-object-names branch. To see the entire patch 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 similarity index 97% rename from doc/dbus-specification.sgml rename to doc/dbus-specification.xml index 696c3f45..698e35a2 100644 --- a/doc/dbus-specification.sgml +++ b/doc/dbus-specification.xml @@ -1,7 +1,11 @@ - + +
- + D-BUS Specification Version 0.8 06 September 2003 @@ -10,7 +14,7 @@ Havoc Pennington - Red Hat, Inc + Red Hat, Inc.
hp@pobox.com
@@ -30,14 +34,14 @@ Alexander Larsson - Red Hat, Inc + Red Hat, Inc.
alexl@redhat.com
- + Introduction @@ -75,10 +79,10 @@ The base D-BUS protocol is a peer-to-peer protocol, specified in . 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 message bus, - specified in . The message bus is a special + specified in . The message bus is a special application that accepts connections from multiple other applications, and forwards messages among them. @@ -111,7 +115,7 @@ Header Encoding Following the mandatory fields, there are zero or more named fields (see - ), and then nul bytes + ), and then nul bytes padding the header such that its total length in bytes is a multiple of 8. @@ -119,7 +123,7 @@ The header MUST begin with the following mandatory fields in the following order: - + Size @@ -185,7 +189,7 @@ Types that can appear in the second byte of the header: - + Conventional name @@ -228,7 +232,7 @@ Flags that can appear in the third byte of the header: - + Conventional name @@ -255,7 +259,7 @@ Header Fields In addition to the required header information mentioned - in , + in , 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 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. @@ -277,7 +281,7 @@ Here are the currently-defined named header fields: - + Conventional Name @@ -326,7 +330,7 @@ UINT32 The serial number of the message this message is a reply to. (The serial number is one of the mandatory header fields, - see .) + see .) SERVICE @@ -334,7 +338,7 @@ STRING The name of the service this message should be routed to. Only used in combination with the message bus, see - . + . SENDER_SERVICE @@ -373,7 +377,7 @@ - + Type name @@ -442,7 +446,7 @@ The types are encoded as follows: - + Type name @@ -771,10 +775,10 @@ AUTH [mechanism] [initial-response] - CANCELBEGIN - DATA <data in base 64 encoding> - ERROR [human-readable error explanation] + CANCEL + BEGIN + DATA <data in base 64 encoding> + ERROR [human-readable error explanation] From server to client are as follows: @@ -1203,7 +1207,7 @@ Standard Peer-to-Peer Messages - See for details on + See for details on the notation used in this section. @@ -1232,7 +1236,7 @@ Message arguments: - + Argument @@ -1283,7 +1287,7 @@ Messages may have a SERVICE field (see ). When the message bus + linkend="message-protocol-header-fields"/>). When the message bus receives a message, if the SERVICE 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 service description files. 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 . + in different places, see . [FIXME the file format should be much better specified than @@ -1439,7 +1443,7 @@ The executable being launched may want to know whether the message bus activating it is one of the well-known message buses (see ). To facilitate this, the bus MUST also set + linkend="message-bus-types"/>). To facilitate this, the bus MUST also set the DBUS_ACTIVATION_BUS_TYPE environment variable if it is one of the well-known buses. The currently-defined values for this variable are system for the systemwide message bus, @@ -1530,7 +1534,7 @@ Reply arguments: - + Argument @@ -1573,7 +1577,7 @@ Reply arguments: - + Argument @@ -1604,7 +1608,7 @@ Message arguments: - + Argument @@ -1623,7 +1627,7 @@ Reply arguments: - + Argument @@ -1655,7 +1659,7 @@ Message arguments: - + Argument @@ -1679,7 +1683,7 @@ Reply arguments: - + Argument @@ -1702,7 +1706,7 @@ specified can be the following values logically ORed together: - + Identifier @@ -1738,7 +1742,7 @@ The return value can be one of the following values: - + Identifier @@ -1781,7 +1785,7 @@ Message arguments: - + Argument @@ -1818,7 +1822,7 @@ Message arguments: - + Argument @@ -1860,7 +1864,7 @@ Message arguments: - + Argument @@ -1898,7 +1902,7 @@ Message arguments: - + Argument @@ -1936,7 +1940,7 @@ Message arguments: - + Argument @@ -1960,7 +1964,7 @@ Reply arguments: - + Argument @@ -1977,7 +1981,7 @@ - Tries to launch the executable associated with a service. For more information, see . + Tries to launch the executable associated with a service. For more information, see . [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 @@ The return value can be one of the following values: - + Identifier @@ -2170,7 +2174,7 @@ An application is said to own a service if the message bus has associated the application with the service name. Services may also have secondary owners (see - ). + ). @@ -2187,7 +2191,7 @@ ".service files" tell the bus how to activate a particular service. - See + See diff --git a/doc/dbus-test-plan.sgml b/doc/dbus-test-plan.xml similarity index 97% rename from doc/dbus-test-plan.sgml rename to 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 @@ - + +
- + D-BUS Test Plan 14 February 2003 @@ -14,7 +18,7 @@ - + Introduction 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 @@ + + + +
+ + D-BUS Tutorial + Version 0.1 + 29 September 2003 + + + Havoc + Pennington + + Red Hat, Inc. +
+ hp@pobox.com +
+ + + + + + + Introduction + + D-BUS blah blah blah + + + + foo + + + + + bar + + + + + + blah blah blah + + + blah blah blah + + +