add a stub for docbook documentation

11 files changed, 378 insertions, 30 deletions

diff --git a/Makefile.am b/Makefile.am
index 55f71b8..95be344 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -8,6 +8,7 @@ SUBDIRS =			\
 	src			\
 	tools			\
 	data			\
+	doc			\
 	libck-connector         \
 	pam-ck-connector        \
 	$(NULL)
diff --git a/configure.ac b/configure.ac
index 796186f..fce1ff9 100644
--- a/configure.ac
+++ b/configure.ac
@@ -164,6 +164,73 @@ AM_CONDITIONAL(CK_COMPILE_SOLARIS, test x$CK_BACKEND = xsolaris, [Compiling for
 AC_SUBST(CK_BACKEND)
 
 dnl ---------------------------------------------------------------------------
+dnl Check for PAM
+dnl ---------------------------------------------------------------------------
+
+have_pam=no
+AC_CHECK_LIB(pam, pam_getenv, have_pam=yes)
+AM_CONDITIONAL(HAVE_PAM, test x$have_pam = xyes)
+if test "x$have_pam" = "xyes"; then
+    PAM_LIBS="${PAM_LIBS} -lpam"
+fi
+AC_SUBST(HAVE_PAM)
+AC_SUBST(PAM_LIBS)
+
+
+# Check if we should build the PAM module
+msg_pam_module=no
+AC_ARG_ENABLE(pam-module, [AC_HELP_STRING([--enable-pam-module], [build PAM module])],, enable_pam_module=no)
+if test "x$enable_pam_module" = "xyes"; then
+  if test "x$have_pam" = "xno"; then
+    AC_MSG_ERROR([--enable-pam-module requires PAM but PAM was not found])
+  fi
+  AC_DEFINE(ENABLE_PAM_MODULE, [], [Set if we build PAM module])
+  msg_pam_module=yes
+fi
+AM_CONDITIONAL(ENABLE_PAM_MODULE, test "x$enable_pam_module" = "xyes")
+
+dnl ---------------------------------------------------------------------------
+dnl - Where should we put documentation ?
+dnl ---------------------------------------------------------------------------
+
+AC_ARG_WITH(doc-dir,
+              [AC_HELP_STRING([--with-doc-dir=<dir>],
+              [directory to install documentation])])
+if ! test -z "$with_doc_dir"; then
+   DOCDIR="$with_doc_dir/ConsoleKit-$VERSION"
+else
+   DOCDIR="$datadir/doc/ConsoleKit-$VERSION"
+fi
+AC_SUBST(DOCDIR)
+
+dnl ---------------------------------------------------------------------------
+dnl - DocBook Documentation
+dnl ---------------------------------------------------------------------------
+
+AC_ARG_ENABLE(docbook-docs, [  --enable-docbook-docs   build documentation (requires xmlto)],enable_docbook_docs=$enableval,enable_docbook_docs=no)
+AC_PATH_PROG(XMLTO, xmlto, no)
+AC_MSG_CHECKING([whether to build DocBook documentation])
+if test x$XMLTO = xno ; then
+    have_docbook=no
+else
+    have_docbook=yes
+fi
+if test x$enable_docbook_docs = xauto ; then
+    if test x$have_docbook = xno ; then
+        enable_docbook_docs=no
+    else
+        enable_docbook_docs=yes
+    fi
+fi
+if test x$enable_docbook_docs = xyes; then
+    if test x$have_docbook = xno; then
+	AC_MSG_ERROR([Building DocBook docs explicitly required, but DocBook not found])
+    fi
+fi
+AM_CONDITIONAL(DOCBOOK_DOCS_ENABLED, test x$enable_docbook_docs = xyes)
+AC_MSG_RESULT(yes)
+
+dnl ---------------------------------------------------------------------------
 dnl Finish
 dnl ---------------------------------------------------------------------------
 
@@ -208,32 +275,6 @@ else
 fi
 
 #
-# Check for pam
-#
-have_pam=no
-AC_CHECK_LIB(pam, pam_getenv, have_pam=yes)
-AM_CONDITIONAL(HAVE_PAM, test x$have_pam = xyes)
-if test "x$have_pam" = "xyes"; then
-    PAM_LIBS="${PAM_LIBS} -lpam"
-fi
-AC_SUBST(HAVE_PAM)
-AC_SUBST(PAM_LIBS)
-
-#
-# Check if we should build the PAM module
-#
-msg_pam_module=no
-AC_ARG_ENABLE(pam-module, [AC_HELP_STRING([--enable-pam-module], [build PAM module])],, enable_pam_module=no)
-if test "x$enable_pam_module" = "xyes"; then
-  if test "x$have_pam" = "xno"; then
-    AC_MSG_ERROR([--enable-pam-module requires PAM but PAM was not found])
-  fi
-  AC_DEFINE(ENABLE_PAM_MODULE, [], [Set if we build PAM module])
-  msg_pam_module=yes
-fi
-AM_CONDITIONAL(ENABLE_PAM_MODULE, test "x$enable_pam_module" = "xyes")
-
-#
 # Enable Debug
 #
 AC_ARG_ENABLE(debug, [AC_HELP_STRING([--enable-debug=[no/yes]], [turn on debugging])],, enable_debug=yes)
@@ -266,6 +307,8 @@ tools/Makefile
 tools/linux/Makefile
 data/Makefile
 data/ConsoleKit
+doc/Makefile
+doc/ConsoleKit.xml
 libck-connector/Makefile
 libck-connector/ck-connector.pc
 pam-ck-connector/Makefile
@@ -289,9 +332,8 @@ echo "
         Base libs:                ${CONSOLE_KIT_LIBS}
         Maintainer mode:          ${USE_MAINTAINER_MODE}
 
-        Backend:                  ${CK_BACKEND}
-
         dbus-1 system.d dir:      ${DBUS_SYS_DIR}
-        build PAM module:         ${msg_pam_module}
-
+        Build backend:            ${CK_BACKEND}
+        Build PAM module:         ${msg_pam_module}
+        Build docs:               ${enable_docbook_docs}
 "
diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 0000000..4337b46
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1,6 @@
+Makefile
+Makefile.in
+ConsoleKit.xml
+ConsoleKit.html
+*.o
+*~
diff --git a/doc/ConsoleKit.xml.in b/doc/ConsoleKit.xml.in
new file mode 100644
index 0000000..7eb0cb1
--- /dev/null
+++ b/doc/ConsoleKit.xml.in
@@ -0,0 +1,69 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY dbus-Manager SYSTEM "./ck-dbus-manager.xml">
+<!ENTITY dbus-Seat SYSTEM "./ck-dbus-seat.xml">
+<!ENTITY dbus-Session SYSTEM "./ck-dbus-session.xml">
+]>
+
+<book id="index">
+  <bookinfo>
+    <title>ConsoleKit @VERSION@ Documentation</title>
+    <releaseinfo>Version @VERSION@</releaseinfo>
+    <date>8 March, 2007</date>
+    <authorgroup>
+      <author>
+        <firstname>William Jon</firstname>
+        <surname>McCann</surname>
+        <affiliation>
+          <address>
+            <email>mccann@jhu.edu</email>
+          </address>
+        </affiliation>
+      </author>
+    </authorgroup>
+  </bookinfo>
+
+  <preface>
+    <title>Introduction</title>
+    <para>
+    </para>
+  </preface>
+
+  <part>
+    <title>Concepts</title>
+
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ck-introduction.xml" />
+  </part>
+
+  <part>
+    <title>Reference</title>
+
+    <reference id="dbus-reference">
+      <title>D-Bus API Reference</title>
+
+      <partintro>
+        <para>
+        ConsoleKit provides a D-Bus API for programs to obtain information about the
+        users, sessions, and seats that are present on a system.
+        </para>
+        <para>
+        Please see the other sections of this manual for an introduction to
+        these concepts.
+        </para>
+        <para>
+        This API is not yet stable and is likely to change in the future.
+        </para>
+      </partintro>
+
+      &dbus-Manager;
+      &dbus-Seat;
+      &dbus-Session;
+
+    </reference>
+  </part>
+
+  <index>
+    <title>Index</title>
+  </index>
+
+</book>
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..6f96464
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,37 @@
+NULL =
+
+SPEC_XML_FILES =			\
+	ConsoleKit.xml			\
+	ck-introduction.xml		\
+	ck-dbus-manager.xml		\
+	ck-dbus-seat.xml		\
+	ck-dbus-session.xml		\
+	$(NULL)
+
+if DOCBOOK_DOCS_ENABLED
+
+htmldocdir = $(DOCDIR)/spec
+htmldoc_DATA = ConsoleKit.html
+
+ConsoleKit.html : $(SPEC_XML_FILES)
+	$(XMLTO) html-nochunks -m config.xsl ConsoleKit.xml
+
+endif # DOCBOOK_DOCS_ENABLED
+
+EXTRA_DIST =				\
+	ConsoleKit.html			\
+	ConsoleKit.xml.in		\
+	config.xsl			\
+	docbook.css			\
+	$(SPEC_XML_FILES)
+	$(NULL)
+
+
+MAINTAINERCLEANFILES =		\
+	*~			\
+	Makefile.in		\
+	$(NULL)
+
+clean-local:
+	rm -f *~
+	rm -f ConsoleKit.html
diff --git a/doc/ck-dbus-manager.xml b/doc/ck-dbus-manager.xml
new file mode 100644
index 0000000..77577a5
--- /dev/null
+++ b/doc/ck-dbus-manager.xml
@@ -0,0 +1,52 @@
+<refentry id="ck-manager">
+  <refmeta>
+    <refentrytitle role="top_of_page">org.freedesktop.ConsoleKit.Manager</refentrytitle>
+    <manvolnum>1</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>org.freedesktop.ConsoleKit.Manager</refname>
+    <refpurpose>Primary management interface</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv role="synopsis">
+    <title role="synopsis.title">Synopsis</title>
+    <synopsis>
+
+  Interface:
+          org.freedesktop.ConsoleKit.Manager
+
+  Methods:
+          GetSeats                  (out OBJECT_PATH ARRAY           seats)
+          GetSessionsForUser        (in  UINT32                      uid,
+                                     out OBJECT_PATH ARRAY           sessions)
+          GetCurrentSession         (out OBJECT_PATH                 session)
+          GetSessionForUnixProcess  (in  UINT32                      pid,
+                                     out OBJECT_PATH                 session)
+          GetSessionForCookie       (in  STRING                      cookie,
+                                     out OBJECT_PATH                 session)
+          GetSystemIdleHint         (out BOOLEAN                     hint)
+          GetSystemIdleSinceHint    (out STRING                      iso8601_datetime)
+
+          OpenSession               (out STRING                      cookie)
+          OpenSessionWithParameters (int STRING,VARIANT STRUCT ARRAY parameters,
+                                     out STRING                      cookie)
+          CloseSession              (int STRING                      cookie,
+                                     out BOOLEAN                     result)
+
+  Signals:
+          SeatAdded                 (STRING  sid)
+          SeatRemoved               (STRING  sid)
+          SystemIdleHintChanged     (BOOLEAN hint)
+
+    </synopsis>
+
+  </refsynopsisdiv>
+
+  <refsect1 role="desc">
+    <title role="desc.title">Description</title>
+    <para>
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/doc/ck-dbus-seat.xml b/doc/ck-dbus-seat.xml
new file mode 100644
index 0000000..738f6e2
--- /dev/null
+++ b/doc/ck-dbus-seat.xml
@@ -0,0 +1,39 @@
+<refentry id="ck-seat">
+  <refmeta>
+    <refentrytitle role="top_of_page">org.freedesktop.ConsoleKit.Seat</refentrytitle>
+    <manvolnum>2</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>org.freedesktop.ConsoleKit.Seat</refname>
+    <refpurpose>Seat interface</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv role="synopsis">
+    <title role="synopsis.title">Synopsis</title>
+    <synopsis>
+
+  Interface:
+          org.freedesktop.ConsoleKit.Seat
+
+  Methods:
+          GetId                (out OBJECT_PATH       sid)
+          ActivateSession      (in  OBJECT_PATH       ssid)
+          GetActiveSession     (out OBJECT_PATH       ssid)
+          GetSessions          (out OBJECT_PATH ARRAY sessions)
+
+  Signals:
+          SessionAdded         (STRING ssid)
+          SessionRemoved       (STRING ssid)
+          ActiveSessionChanged (STRING ssid)
+
+    </synopsis>
+  </refsynopsisdiv>
+
+  <refsect1 role="desc">
+    <title role="desc.title">Description</title>
+    <para>
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/doc/ck-dbus-session.xml b/doc/ck-dbus-session.xml
new file mode 100644
index 0000000..77181ec
--- /dev/null
+++ b/doc/ck-dbus-session.xml
@@ -0,0 +1,55 @@
+<refentry id="ck-session">
+  <refmeta>
+    <refentrytitle role="top_of_page">org.freedesktop.ConsoleKit.Session</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>org.freedesktop.ConsoleKit.Session</refname>
+    <refpurpose>Session interface</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv role="synopsis">
+    <title role="synopsis.title">Synopsis</title>
+    <synopsis>
+
+  Interface:
+          org.freedesktop.ConsoleKit.Session
+
+  Methods:
+          GetId               (out STRING  ssid)
+          GetSeatId           (out STRING  sid)
+          GetUser             (out INT32   uid)
+          GetIdleHint         (out BOOLEAN hint)
+          SetIdleHint         (in  BOOLEAN hint)
+          GetIdleSinceHint    (out STRING  iso8601_datetime)
+          GetCreationTime     (out STRING  iso8601_datetime)
+          GetRemoteHostName   (out STRING  hostname)
+          GetDisplayDevice    (out STRING  device)
+          GetX11DisplayDevice (out STRING  device)
+          GetX11Display       (out STRING  display)
+          GetSessionType      (out STRING  type)
+          IsLocal             (out BOOLEAN local)
+          IsActive            (out BOOLEAN active)
+          Unlock              ()
+          Lock                ()
+          Activate            ()
+
+  Signals:
+          ActiveChanged       (BOOLEAN active)
+          IdleHintChanged     (BOOLEAN hint)
+          Unlock              ()
+          Lock                ()
+
+  Properties:
+
+    </synopsis>
+  </refsynopsisdiv>
+
+  <refsect1 role="desc">
+    <title role="desc.title">Description</title>
+    <para>
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/doc/ck-introduction.xml b/doc/ck-introduction.xml
new file mode 100644
index 0000000..3a23d76
--- /dev/null
+++ b/doc/ck-introduction.xml
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+
+<chapter id="introduction">
+  <title>Introduction</title>
+
+  <sect1>
+    <title>About</title>
+    <para>
+      ConsoleKit is a framework for keeping track of the various
+      users, sessions, and seats present on a system.  It
+      provides a mechanism for software to react to changes of any of
+      these items or of any of the metadata associated with them.
+    </para>
+  </sect1>
+
+  <sect1>
+    <title>Defining the Problem</title>
+    <para>
+    </para>
+  </sect1>
+
+</chapter>
diff --git a/doc/config.xsl b/doc/config.xsl
new file mode 100644
index 0000000..7aa9def
--- /dev/null
+++ b/doc/config.xsl
@@ -0,0 +1,6 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                xmlns:fo="http://www.w3.org/1999/XSL/Format"
+                version="1.0">
+  <xsl:param name="html.stylesheet" select="'docbook.css'"/>
+</xsl:stylesheet>
diff --git a/doc/docbook.css b/doc/docbook.css
new file mode 100644
index 0000000..9a0e72a
--- /dev/null
+++ b/doc/docbook.css
@@ -0,0 +1,18 @@
+body {
+	font-family: luxi sans,sans-serif;
+}
+
+table {
+	border: solid 1pt; 
+	border-collapse: collapse;
+}
+
+th {
+	background: #eeeeee; 
+	padding: 5px;
+}
+
+td {
+	border: solid 1pt;
+	padding: 5px;
+}