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

1 files changed, 0 insertions, 228 deletions

diff --git a/doc/dbus-test-plan.sgml b/doc/dbus-test-plan.sgml
deleted file mode 100644
index 755ed22a..00000000
--- a/doc/dbus-test-plan.sgml
+++ /dev/null
@@ -1,228 +0,0 @@
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
-]>
-<article id="index">
-  <artheader>
-    <title>D-BUS Test Plan</title>
-    <date>14 February 2003</date>
-    <authorgroup>
-      <author>
-	<firstname>Anders</firstname>
-	<surname>Carlsson</surname>
-	<affiliation>
-	  <orgname>CodeFactory AB</orgname>
-	  <address><email>andersca@codefactory.se</email></address>
-	</affiliation>
-      </author>
-    </authorgroup>
-  </artheader>
-  <sect1 id="introduction">
-    <title>Introduction</title>
-    <para>
-      This document tries to explain the details of the test plan for D-BUS
-    </para>
-    <sect2 id="importance-of-testing">
-      <title>The importance of testing</title>
-      <para>
-        As with any big library or program, testing is important. It
-        can help find bugs and regressions and make the code better
-        overall. 
-      </para>
-      <para>
-        D-BUS is a large and complex piece of software (about 25,000
-        lines of code for the client library, and 2,500 lines of code
-        for the bus daemon) and it's therefore important to try to make sure
-        that all parts of the software is functioning correctly.
-      </para>
-      <para>
-        D-BUS can be built with support for testing by passing
-        <literal>--enable-tests</literal>. to the configure script. It
-        is recommended that production systems build without testing
-        since that reduces the D-BUS client library size.
-      </para>
-    </sect2>
-  </sect1>
-  <sect1 id="client-library">
-    <title>Testing the D-BUS client library</title>
-    <para>
-      The tests for the client library consist of the dbus-test
-      program which is a unit test for all aspects of the client
-      library. Whenever a bug in the client library is found and
-      fixed, a test is added to make sure that the bug won't occur again.
-    </para>
-    <sect2 id="data-structures">
-      <title>Data Structures</title>
-      <para>
-      The D-BUS client library consists of some data structures that
-      are used internally; a linked list class, a hashtable class and
-      a string class. All aspects of those are tested by dbus-test.
-      </para>
-    </sect2>
-    <sect2 id="message-loader">
-      <title>Message loader</title>
-      <para>
-        The message loader is the part of D-BUS that takes messages in
-        raw character form and parses them, turning them into DBusMessages.
-      </para>
-      <para>
-        This is one of the parts of D-BUS that
-        <emphasis>must</emphasis> be absolutely bug-free and
-        robust. The message loader should be able to handle invalid
-        and incomplete messages without crashing. Not doing so is a
-        serious issue and can easily result in D-BUS being exploitable
-        to DoS attacks.
-      </para>
-      <para>
-        To solve these problems, there is a testing feature called the
-        Message Builder. The message builder can take a serialized
-        message in string-form and convert it into a raw character
-        string which can then be loaded by the message loader. 
-      </para>
-      <figure>
-	<title>Example of a message in string form</title>
-	<programlisting>
-          # Standard org.freedesktop.DBus.Hello message
-
-          VALID_HEADER
-          FIELD_NAME name
-          TYPE STRING
-          STRING 'org.freedesktop.DBus.Hello'
-          FIELD_NAME srvc
-          TYPE STRING
-          STRING 'org.freedesktop.DBus'
-          ALIGN 8
-          END_LENGTH Header
-          START_LENGTH Body
-          END_LENGTH Body
-        </programlisting>
-      </figure>
-      <para>
-        The file format of messages in string form is documented in
-        the D-BUS Reference Manual.
-      </para>
-      <para>
-        The message test part of dbus-test is using the message
-        builder to build different kinds of messages, both valid,
-        invalid, and invalid ones, to make sure that the loader won't
-        crash or leak memory of any of those, and that the loader
-        knows if a message is valid or not.
-      </para>
-      <para>
-        There is also a test program called
-        <literal>break-loader</literal> that loads a message in
-        string-form into raw character form using the message
-        builder. It then randomly changes the message, it can for
-        example replace single bytes of data or modify the length of
-        the message. This is to simulate network errors. The
-        break-loader program saves all the messages leading to errors
-        so it can easily be run for a long period of time.
-      </para>
-    </sect2>
-    <sect2 id="authentication">
-      <title>Authentication</title>
-      <para>
-        For testing authentication, there is a testing feature that
-        can read authentication sequences from a file and play them
-        back to a dummy server and client to make sure that
-        authentication is working according to the specification.
-      </para>
-      <figure>
-	<title>Example of an authentication script</title>
-	<programlisting>
-          ## this tests a successful auth of type EXTERNAL
-          
-          SERVER
-          SEND 'AUTH EXTERNAL USERNAME_BASE64'
-          EXPECT_COMMAND OK
-          EXPECT_STATE WAITING_FOR_INPUT
-          SEND 'BEGIN'
-          EXPECT_STATE AUTHENTICATED
-        </programlisting>
-      </figure>
-    </sect2>
-  </sect1>
-  <sect1 id="daemon">
-    <title>Testing the D-BUS bus daemon</title>
-    <para>
-      Since the D-BUS bus daemon is using the D-BUS client library it
-      will benefit from all tests done on the client library, but
-      there is still the issue of testing client-server communication.
-      This is more complicated since it it may require another process
-      running.
-    </para>
-    <sect2 id="debug-transport">
-      <title>The debug transport</title>
-      <para>
-        In D-BUS, a <emphasis>transport</emphasis> is a class that
-        handles sending and receiving raw data over a certain
-        medium. The transport that is used most in D-BUS is the UNIX
-        transport with sends and recevies data over a UNIX socket. A
-        transport that tunnels data through X11 client messages is
-        also under development.
-      </para>
-      <para>
-        The D-BUS debug transport is a specialized transport that
-        works in-process. This means that a client and server that
-        exists in the same process can talk to eachother without using
-        a socket.
-      </para>
-    </sect2>
-    <sect2 id="bus-test">
-      <title>The bus-test program</title>
-      <para>
-        The bus-test program is a program that is used to test various
-        parts of the D-BUS bus daemon; robustness and that it conforms
-        to the specifications.
-      </para>
-      <para>
-        The test program has the necessary code from the bus daemon
-        linked in, and it uses the debug transport for
-        communication. This means that the bus daemon code can be
-        tested without the real bus actually running, which makes
-        testing easier.
-      </para>
-      <para>
-        The bus-test program should test all major features of the
-        bus, such as service registration, notification when things
-        occurs and message matching.
-      </para>
-    </sect2>
-  </sect1>
-  <sect1 id="other-tests">
-    <title>Other tests</title>
-
-    <sect2 id="oom-robustness">
-      <title>Out-Of-Memory robustness</title>
-      <para>
-        Since D-BUS should be able to be used in embedded devices, and
-        also as a system service, it should be able to cope with
-        low-memory situations without exiting or crashing.
-      </para>
-      <para>
-        In practice, this means that both the client and server code
-        must be able to handle dbus_malloc returning NULL. 
-      </para>
-      <para>
-        To test this, two environment variables
-        exist. <literal>DBUS_MALLOC_FAIL_NTH</literal> will make every
-        nth call to dbus_malloc return NULL, and
-        <literal>DBUS_MALLOC_FAIL_GREATER_THAN</literal> will make any
-        dbus_malloc call with a request for more than the specified
-        number of bytes fail.
-      </para>
-    </sect2>
-
-    <sect2 id="leaks-and-other-stuff">
-      <title>Memory leaks and code robustness</title> 
-      <para>
-        Naturally there are some things that tests can't be written
-        for, for example things like memory leaks and out-of-bounds
-        memory reading or writing.
-      </para>
-      <para>
-        Luckily there exists good tools for catching such errors. One
-        free good tool is <ulink url="http://devel-home.kde.org/~sewardj/">Valgrind</ulink>, which runs the program in a
-        virtual CPU which makes catching errors easy. All test programs can be run under Valgrind, 
-      </para>
-    </sect2>
-  </sect1>
-</article>