diff --git a/Makefile b/Makefile
index 1150041..218c52c 100644
--- a/Makefile
+++ b/Makefile
@@ -84,7 +84,6 @@ dist:
 		$(PACKAGE)-$(VERSION)/tools/appbroker.c \
 		$(PACKAGE)-$(VERSION)/tools/appclient.c \
 		$(PACKAGE)-$(VERSION)/tools/Makefile \
-		$(PACKAGE)-$(VERSION)/tools/README \
 		$(PACKAGE)-$(VERSION)/tools/project.conf \
 		$(PACKAGE)-$(VERSION)/Makefile \
 		$(PACKAGE)-$(VERSION)/COPYING \
diff --git a/doc/AppBroker.xml b/doc/AppBroker.xml
index b7e3386..e274a36 100644
--- a/doc/AppBroker.xml
+++ b/doc/AppBroker.xml
@@ -57,7 +57,8 @@
 	<refsect1 id="description">
 		<title>Description</title>
 		<para><command>&name;</command> is a broker for the App message-passing
-			protocol.</para>
+			protocol. It translates an interface definition file into a C header file,
+		suitable as a reference while implementing an AppServer.</para>
 	</refsect1>
 	<refsect1 id="options">
 		<title>Options</title>
@@ -72,6 +73,63 @@
 			</varlistentry>
 		</variablelist>
 	</refsect1>
+	<refsect1 id="example">
+		<title>Example</title>
+		<para>The following interface definition file:</para>
+		<programlisting>service=VFS
+
+[call::chmod]
+ret=INT32
+arg1=STRING,pathname
+arg2=UINT32,mode</programlisting>
+		<para>will likely be translated as follows:</para>
+		<programlisting>/* $Id$ */
+
+
+
+#ifndef VFS_VFS_H
+# define VFS_VFS_H
+
+# include &lt;stdint.h&gt;
+# include &lt;System/App.h&gt;
+
+
+/* types */
+typedef Buffer * BUFFER;
+typedef double * DOUBLE;
+typedef float * FLOAT;
+typedef int16_t INT16;
+typedef int32_t INT32;
+typedef uint16_t UINT16;
+typedef uint32_t UINT32;
+typedef String const * STRING;
+typedef void VOID;
+
+typedef BUFFER BUFFER_IN;
+
+typedef DOUBLE DOUBLE_IN;
+
+typedef FLOAT FLOAT_IN;
+typedef INT32 INT32_IN;
+typedef UINT32 UINT32_IN;
+typedef STRING STRING_IN;
+
+typedef Buffer * BUFFER_OUT;
+typedef int32_t * INT32_OUT;
+typedef uint32_t * UINT32_OUT;
+typedef String ** STRING_OUT;
+
+typedef Buffer * BUFFER_INOUT;
+typedef int32_t * INT32_INOUT;
+typedef uint32_t * UINT32_INOUT;
+typedef String ** STRING_INOUT;
+
+
+/* calls */
+INT32 VFS_chmod(App * app, AppServerClient * client, STRING pathname, UINT32 mode);
+
+#endif /* !VFS_VFS_H */</programlisting>
+	</refsect1>
 	<refsect1 id="bugs">
 		<title>Bugs</title>
 		<para>Issues can be listed and reported at <ulink
diff --git a/tools/README b/tools/README
deleted file mode 100644
index 3744375..0000000
--- a/tools/README
+++ /dev/null
@@ -1,44 +0,0 @@
-broker reads a configuration file for a given AppInterface, eg:
-
-=== BEGIN FILE ===
-service=VFS
-
-[chmod]
-ret=INT32
-arg1=STRING,pathname
-arg2=UINT32,mode
-=== END FILE ===
-
-which is then translated into a C header file, eg:
-=== BEGIN FILE ===
-/* $Id$ */
-
-
-
-#ifndef VFS_H
-# define VFS_H
-
-# include <stdint.h>
-# include <System.h>
-
-
-/* types */
-typedef Buffer * BUFFER;
-typedef int32_t INT32;
-typedef uint32_t UINT32;
-typedef String * STRING;
-
-
-/* functions */
-INT32 VFS_chmod(STRING pathname, UINT32 mode);
-
-#endif /* !VFS_H */
-=== END FILE ===
-
-This service definition file and corresponding header may then be committed
-along the relevant source code.
-
-It would also be helpful to:
-- place this code directly inside AppInterface's class
-- implement dynamic port assignment: it currently has to be explicitly specified
-  in the interface file
diff --git a/tools/project.conf b/tools/project.conf
index 7d53691..53b36eb 100644
--- a/tools/project.conf
+++ b/tools/project.conf
@@ -5,7 +5,7 @@ cflags_force=-W `pkg-config --cflags libSystem`
 cflags=-Wall -g -O2 -pedantic
 ldflags_force=-L../src `pkg-config --libs libSystem` -lApp
 ldflags=-L$(PREFIX)/lib -Wl,-rpath,$(PREFIX)/lib
-dist=Makefile,README
+dist=Makefile
 
 [AppBroker]
 type=binary