Commit 16179246 authored by Matthias Clasen's avatar Matthias Clasen

Add doc build infrastructure

parent 4716c8bd
SUBDIRS = src data po
SUBDIRS = src data po doc
ACLOCAL_AMFLAGS = -I m4
......
......@@ -28,11 +28,62 @@ GNOME_COMPILE_WARNINGS([maximum])
GNOME_CXX_WARNINGS
GNOME_MAINTAINER_MODE_DEFINES
nl ---------------------------------------------------------------------------
dnl - DocBook Documentation
dnl ---------------------------------------------------------------------------
AC_ARG_ENABLE(docbook-docs,
[AC_HELP_STRING([--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)
AC_ARG_VAR([XMLTO],[Define/override the 'xmlto' location.])
AC_ARG_VAR([XMLTO_FLAGS],[Define/override 'xmlto' options, like '--skip-validation'.])
dnl ---------------------------------------------------------------------------
dnl Check for xsltproc
dnl ---------------------------------------------------------------------------
AC_PATH_PROG([XSLTPROC], [xsltproc])
AC_CONFIG_HEADERS([config.h])
AC_CONFIG_FILES([
Makefile
po/Makefile.in
data/Makefile
src/Makefile
doc/Makefile
doc/dbus/Makefile
doc/dbus/AccountsService.xml
])
AC_OUTPUT
echo
AC_MSG_NOTICE([accountsservice was configured with the following options:])
if test "x$enable_docbook_docs" = "xyes"; then
AC_MSG_NOTICE([** DocBook documentation build enabled])
else
AC_MSG_NOTICE([** DocBook documentation build disabled])
fi
echo
SUBDIRS = dbus
<?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-Accounts SYSTEM "@srcdir@/org.freedesktop.Accounts.ref.xml">
<!ENTITY dbus-User SYSTEM "@srcdir@/org.freedesktop.Accounts.User.ref.xml">
]>
<book id="index">
<bookinfo>
<title>AccountsService @VERSION@ Documentation</title>
<releaseinfo>Version @VERSION@</releaseinfo>
<authorgroup>
<author>
<firstname>Matthias</firstname>
<surname>Clasen</surname>
<affiliation>
<address>
<email>mclasen@redhat.com</email>
</address>
</affiliation>
</author>
</authorgroup>
</bookinfo>
<!--
<preface>
<title>Introduction</title>
<para>
</para>
</preface>
<part>
<title>Concepts</title>
<para>
</para>
</part>
-->
<part>
<title>Reference</title>
<reference id="dbus-reference">
<title>D-Bus API Reference</title>
<partintro>
<para>
The AccountsService provides a D-Bus API for programs to obtain
information about user accounts 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-Accounts;
&dbus-User;
</reference>
</part>
<index>
<title>Index</title>
</index>
</book>
NULL =
SPEC_XML_FILES = \
AccountsService.xml \
org.freedesktop.Accounts.ref.xml \
org.freedesktop.Accounts.User.ref.xml \
$(NULL)
if DOCBOOK_DOCS_ENABLED
htmldocdir = $(docdir)/spec
htmldoc_DATA = AccountsService.html
AccountsService.html : $(SPEC_XML_FILES)
$(XMLTO) $(XMLTO_FLAGS) xhtml-nochunks -m $(top_srcdir)/doc/dbus/config.xsl AccountsService.xml
endif # DOCBOOK_DOCS_ENABLED
org.freedesktop.Accounts.ref.xml : $(top_srcdir)/data/org.freedesktop.Accounts.xml spec-to-docbook.xsl
$(XSLTPROC) $(top_srcdir)/doc/dbus/spec-to-docbook.xsl $< | tail -n +2 > $@
org.freedesktop.Accounts.User.ref.xml : $(top_srcdir)/data/org.freedesktop.Accounts.User.xml spec-to-docbook.xsl
$(XSLTPROC) $(top_srcdir)/doc/dbus/spec-to-docbook.xsl $< | tail -n +2 > $@
EXTRA_DIST = \
spec-to-docbook.xsl \
AccountsService.xml.in \
config.xsl \
docbook.css \
dbus-introspect-docs.dtd \
$(SPEC_XML_FILES)
$(NULL)
MAINTAINERCLEANFILES = \
*~ \
Makefile.in \
$(NULL)
clean-local:
rm -f *~ *.ref.xml
rm -f AccountsService.html
check-local:
xmllint --noout --noent --valid AccountsService.xml
<?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>
<!-- DTD for D-Bus Introspection Documentation -->
<!ELEMENT doc (summary?,description?,errors?,permission?,since?,deprecated,seealso?)>
<!ELEMENT summary (#PCDATA|ref)*>
<!ELEMENT description (#PCDATA|para|example)*>
<!ELEMENT errors (error)*>
<!ELEMENT permission (#PCDATA|ref|para)*>
<!ELEMENT since EMPTY>
<!ATTLIST since version CDATA #REQUIRED>
<!ELEMENT deprecated (#PCDATA|ref)>
<!ATTLIST deprecated version CDATA #REQUIRED>
<!ATTLIST deprecated instead CDATA #REQUIRED>
<!ELEMENT seealso (ref+)>
<!ELEMENT error (#PCDATA|para)*>
<!ATTLIST error name CDATA #REQUIRED>
<!ELEMENT para (#PCDATA|example|code|list|ref)*>
<!ELEMENT example (#PCDATA|para|code|ref)*>
<!ATTLIST language (c|glib|python|shell) #REQUIRED>
<!ATTLIST title CDATA #IMPLIED>
<!ELEMENT list (item*)>
<!ATTLIST list type (bullet|number) #REQUIRED>
<!ELEMENT item (term|definition)*>
<!ELEMENT term (#PCDATA|ref)*>
<!ELEMENT definition (#PCDATA|para)*>
<!ELEMENT code (#PCDATA)>
<!ATTLIST code lang CDATA #IMPLIED>
<!ELEMENT ref CDATA>
<!ATTLIST ref type (parameter|arg|signal|method|interface) #REQUIRED>
<!ATTLIST ref to CDATA #REQUIRED>
body
{
font-family: sans-serif;
}
h1.title
{
}
.permission
{
color: #ee0000;
text-decoration: underline;
}
.synopsis, .classsynopsis
{
background: #eeeeee;
border: solid 1px #aaaaaa;
padding: 0.5em;
}
.programlisting
{
background: #eeeeff;
border: solid 1px #aaaaff;
padding: 0.5em;
}
.variablelist
{
padding: 4px;
margin-left: 3em;
}
.variablelist td:first-child
{
vertical-align: top;
}
td.shortcuts
{
color: #770000;
font-size: 80%;
}
div.refnamediv
{
margin-top: 2em;
}
div.toc
{
border: 2em;
}
a
{
text-decoration: none;
}
a:hover
{
text-decoration: underline;
color: #FF0000;
}
div.table table
{
border-collapse: collapse;
border-spacing: 0px;
border-style: solid;
border-color: #777777;
border-width: 1px;
}
div.table table td, div.table table th
{
border-style: solid;
border-color: #777777;
border-width: 1px;
padding: 3px;
vertical-align: top;
}
div.table table th
{
background-color: #eeeeee;
}
<?xml version='1.0'?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd"
exclude-result-prefixes="doc">
<!--
Convert D-Bus Glib xml into DocBook refentries
Copyright (C) 2007 William Jon McCann
License: GPL
-->
<xsl:output method="xml" indent="yes" encoding="UTF-8"/>
<xsl:template match="/">
<xsl:variable name="interface" select="//interface/@name"/>
<xsl:variable name="basename">
<xsl:call-template name="interface-basename">
<xsl:with-param name="str" select="$interface"/>
</xsl:call-template>
</xsl:variable>
<refentry><xsl:attribute name="id"><xsl:value-of select="$basename"/></xsl:attribute>
<refmeta>
<refentrytitle role="top_of_page"><xsl:value-of select="//interface/@name"/></refentrytitle>
</refmeta>
<refnamediv>
<refname><xsl:value-of select="//interface/@name"/></refname>
<refpurpose><xsl:value-of select="$basename"/> interface</refpurpose>
</refnamediv>
<refsynopsisdiv role="synopsis">
<title role="synopsis.title">Methods</title>
<synopsis>
<xsl:call-template name="methods-synopsis">
<xsl:with-param name="basename" select="$basename"/>
</xsl:call-template>
</synopsis>
</refsynopsisdiv>
<xsl:choose>
<xsl:when test="count(///signal) > 0">
<refsect1 role="signal_proto">
<title role="signal_proto.title">Signals</title>
<synopsis>
<xsl:call-template name="signals-synopsis">
<xsl:with-param name="basename" select="$basename"/>
</xsl:call-template>
</synopsis>
</refsect1>
</xsl:when>
</xsl:choose>
<refsect1 role="impl_interfaces">
<title role="impl_interfaces.title">Implemented Interfaces</title>
<para>
Objects implementing <xsl:value-of select="$interface"/> also implements
org.freedesktop.DBus.Introspectable,
org.freedesktop.DBus.Properties
</para>
</refsect1>
<xsl:choose>
<xsl:when test="count(///property) > 0">
<refsect1 role="properties">
<title role="properties.title">Properties</title>
<synopsis>
<xsl:call-template name="properties-synopsis">
<xsl:with-param name="basename" select="$basename"/>
</xsl:call-template>
</synopsis>
</refsect1>
</xsl:when>
</xsl:choose>
<refsect1 role="desc">
<title role="desc.title">Description</title>
<xsl:choose>
<xsl:when test="count(//interface/doc:doc) > 0">
<xsl:apply-templates select="//interface/doc:doc"/>
</xsl:when>
<xsl:otherwise>
<para>
</para>
</xsl:otherwise>
</xsl:choose>
</refsect1>
<refsect1 role="details">
<title role="details.title">Details</title>
<xsl:call-template name="method-details">
<xsl:with-param name="basename" select="$basename"/>
</xsl:call-template>
</refsect1>
<xsl:choose>
<xsl:when test="count(///signal) > 0">
<refsect1 role="signals">
<title role="signals.title">Signal Details</title>
<xsl:call-template name="signal-details">
<xsl:with-param name="basename" select="$basename"/>
</xsl:call-template>
</refsect1>
</xsl:when>
</xsl:choose>
<xsl:choose>
<xsl:when test="count(///property) > 0">
<refsect1 role="property_details">
<title role="property_details.title">Property Details</title>
<xsl:call-template name="property-details">
<xsl:with-param name="basename" select="$basename"/>
</xsl:call-template>
</refsect1>
</xsl:when>
</xsl:choose>
</refentry>
</xsl:template>
<xsl:template name="property-doc">
<xsl:apply-templates select="doc:doc/doc:description"/>
<xsl:choose>
<xsl:when test="count(arg) > 0">
<variablelist role="params">
<xsl:for-each select="arg">
<varlistentry><term><parameter><xsl:value-of select="@name"/></parameter>:</term>
<listitem><simpara><xsl:value-of select="doc:doc/doc:summary"/></simpara></listitem>
</varlistentry>
</xsl:for-each>
</variablelist>
</xsl:when>
</xsl:choose>
<xsl:apply-templates select="doc:doc/doc:since"/>
<xsl:apply-templates select="doc:doc/doc:deprecated"/>
<xsl:apply-templates select="doc:doc/doc:permission"/>
<xsl:apply-templates select="doc:doc/doc:seealso"/>
</xsl:template>
<xsl:template name="property-details">
<xsl:param name="basename"/>
<xsl:variable name="longest">
<xsl:call-template name="find-longest">
<xsl:with-param name="set" select="@name"/>
</xsl:call-template>
</xsl:variable>
<xsl:for-each select="///property">
<refsect2>
<title><anchor role="function"><xsl:attribute name="id"><xsl:value-of select="$basename"/>:<xsl:value-of select="@name"/></xsl:attribute></anchor>The "<xsl:value-of select="@name"/>" property</title>
<indexterm><primary><xsl:value-of select="@name"/></primary><secondary><xsl:value-of select="$basename"/></secondary></indexterm>
<programlisting>'<xsl:value-of select="@name"/>'<xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="2"/></xsl:call-template>
<xsl:call-template name="property-args"><xsl:with-param name="indent" select="string-length(@name) + 2"/></xsl:call-template></programlisting>
<xsl:call-template name="property-doc"/>
</refsect2>
</xsl:for-each>
</xsl:template>
<xsl:template name="signal-doc">
<xsl:apply-templates select="doc:doc/doc:description"/>
<xsl:choose>
<xsl:when test="count(arg) > 0">
<variablelist role="params">
<xsl:for-each select="arg">
<varlistentry><term><parameter><xsl:value-of select="@name"/></parameter>:</term>
<listitem><simpara><xsl:value-of select="doc:doc/doc:summary"/></simpara></listitem>
</varlistentry>
</xsl:for-each>
</variablelist>
</xsl:when>
</xsl:choose>
<xsl:apply-templates select="doc:doc/doc:since"/>
<xsl:apply-templates select="doc:doc/doc:deprecated"/>
<xsl:apply-templates select="doc:doc/doc:permission"/>
<xsl:apply-templates select="doc:doc/doc:seealso"/>
</xsl:template>
<xsl:template name="signal-details">
<xsl:param name="basename"/>
<xsl:variable name="longest">
<xsl:call-template name="find-longest">
<xsl:with-param name="set" select="@name"/>
</xsl:call-template>
</xsl:variable>
<xsl:for-each select="///signal">
<refsect2>
<title><anchor role="function"><xsl:attribute name="id"><xsl:value-of select="$basename"/>::<xsl:value-of select="@name"/></xsl:attribute></anchor>The <xsl:value-of select="@name"/> signal</title>
<indexterm><primary><xsl:value-of select="@name"/></primary><secondary><xsl:value-of select="$basename"/></secondary></indexterm>
<programlisting><xsl:value-of select="@name"/> (<xsl:call-template name="signal-args"><xsl:with-param name="indent" select="string-length(@name) + 2"/><xsl:with-param name="prefix" select="."/></xsl:call-template>)</programlisting>
<xsl:call-template name="signal-doc"/>
</refsect2>
</xsl:for-each>
</xsl:template>
<xsl:template match="doc:code">
<programlisting>
<xsl:apply-templates />
</programlisting>
</xsl:template>
<xsl:template match="doc:tt">
<literal>
<xsl:apply-templates />
</literal>
</xsl:template>
<xsl:template match="doc:i">
<emphasis>
<xsl:apply-templates />
</emphasis>
</xsl:template>
<xsl:template match="doc:b">
<emphasis role="bold">
<xsl:apply-templates />
</emphasis>
</xsl:template>
<xsl:template match="doc:ulink">
<ulink>
<xsl:attribute name="url"><xsl:value-of select="@url"/></xsl:attribute>
<xsl:value-of select="."/>
</ulink>
</xsl:template>
<xsl:template match="doc:summary">
<xsl:apply-templates />
</xsl:template>
<xsl:template match="doc:example">
<informalexample>
<xsl:apply-templates />
</informalexample>
</xsl:template>
<xsl:template name="listitems-do-term">
<xsl:param name="str"/>
<xsl:choose>
<xsl:when test="string-length($str) > 0">
<emphasis role="bold"><xsl:value-of select="$str"/>: </emphasis>
</xsl:when>
</xsl:choose>
</xsl:template>
<xsl:template name="do-listitems">
<xsl:for-each select="doc:item">
<listitem><para>
<xsl:call-template name="listitems-do-term"><xsl:with-param name="str" select="doc:term"/></xsl:call-template>
<xsl:apply-templates select="doc:definition"/>
</para></listitem>
</xsl:for-each>
</xsl:template>
<xsl:template match="doc:list">
<para>
<xsl:choose>
<xsl:when test="contains(@type,'number')">
<orderedlist>
<xsl:call-template name="do-listitems"/>
</orderedlist>
</xsl:when>
<xsl:otherwise>
<itemizedlist>
<xsl:call-template name="do-listitems"/>
</itemizedlist>
</xsl:otherwise>
</xsl:choose>
</para>
</xsl:template>
<xsl:template match="doc:para">
<para>
<xsl:apply-templates />
</para>
</xsl:template>
<xsl:template match="doc:description">
<xsl:apply-templates />
</xsl:template>
<xsl:template match="doc:since">
<para role="since">Since <xsl:value-of select="@version"/>
</para>
</xsl:template>
<xsl:template match="doc:deprecated">
<xsl:variable name="name" select="../../@name"/>
<xsl:variable name="parent">
<xsl:call-template name="interface-basename">
<xsl:with-param name="str" select="../../../@name"/>/>
</xsl:call-template>
</xsl:variable>
<xsl:variable name="type" select="name(../..)"/>
<para role="deprecated">
<warning><para><literal><xsl:value-of select="$name"/></literal> is deprecated since version <xsl:value-of select="@version"/> and should not be used in newly-written code. Use
<xsl:variable name="to">
<xsl:choose>
<xsl:when test="contains($type,'property')">
<xsl:value-of select="$parent"/>:<xsl:value-of select="@instead"/>
</xsl:when>
<xsl:when test="contains($type,'signal')">
<xsl:value-of select="$parent"/>::<xsl:value-of select="@instead"/>
</xsl:when>
<xsl:when test="contains($type,'method')">
<xsl:value-of select="$parent"/>.<xsl:value-of select="@instead"/>
</xsl:when>
<xsl:when test="contains($type,'interface')">
<xsl:value-of select="@instead"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="@instead"/>
</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<xsl:call-template name="create-link">
<xsl:with-param name="type" select="$type"/>
<xsl:with-param name="to" select="$to"/>
<xsl:with-param name="val" select="@instead"/>
</xsl:call-template>
instead.</para></warning>
</para>
</xsl:template>
<xsl:template match="doc:permission">
<para role="permission">
<xsl:apply-templates />
</para>
</xsl:template>
<xsl:template match="doc:errors">
<para role="errors">
<xsl:apply-templates />
</para>
</xsl:template>
<xsl:template match="doc:seealso">
<para>
See also:
<xsl:apply-templates />
</para>
</xsl:template>
<xsl:template name="create-link">
<xsl:param name="type"/>
<xsl:param name="to"/>
<xsl:param name="val"/>
<xsl:choose>
<xsl:when test="contains($type,'property')">
<link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><literal><xsl:value-of select="$val"/></literal></link>
</xsl:when>
<xsl:when test="contains($type,'signal')">
<link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><literal><xsl:value-of select="$val"/></literal></link>
</xsl:when>
<xsl:when test="contains($type,'method')">
<link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><function><xsl:value-of select="$val"/></function></link>
</xsl:when>
<xsl:when test="contains($type,'interface')">
<link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><xsl:value-of select="$val"/></link>
</xsl:when>
</xsl:choose>
</xsl:template>
<xsl:template match="doc:ref">
<xsl:call-template name="create-link">
<xsl:with-param name="type" select="@type"/>
<xsl:with-param name="to" select="@to"/>
<xsl:with-param name="val" select="."/>
</xsl:call-template>
</xsl:template>
<xsl:template name="method-doc">
<xsl:apply-templates select="doc:doc/doc:description"/>
<xsl:choose>
<xsl:when test="count(arg) > 0">
<variablelist role="params">
<xsl:for-each select="arg">
<varlistentry><term><parameter><xsl:value-of select="@name"/></parameter>:</term>
<listitem><simpara><xsl:apply-templates select="doc:doc/doc:summary"/></simpara></listitem>
</varlistentry>
</xsl:for-each>
</variablelist>
</xsl:when>
</xsl:choose>
<xsl:apply-templates select="doc:doc/doc:since"/>
<xsl:apply-templates select="doc:doc/doc:deprecated"/>
<xsl:choose>
<xsl:when test="count(doc:doc/doc:errors) > 0">
<note>
<title>Errors</title>
<variablelist role="errors">
<xsl:for-each select="doc:doc/doc:errors/doc:error">
<varlistentry>
<term><parameter><xsl:value-of select="@name"/></parameter>:</term>
<listitem><simpara><xsl:apply-templates select="."/></simpara></listitem>
</varlistentry>
</xsl:for-each>
</variablelist>
</note>
</xsl:when>
</xsl:choose>
<xsl:choose>
<xsl:when test="count(doc:doc/doc:permission) > 0">
<note>
<title>Permissions</title>
<xsl:apply-templates select="doc:doc/doc:permission"/>
</note>
</xsl:when>
</xsl:choose>
<xsl:apply-templates select="doc:doc/doc:seealso"/>
</xsl:template>
<xsl:template name="method-details">
<xsl:param name="basename"/>
<xsl:variable name="longest">
<xsl:call-template name="find-longest">
<xsl:with-param name="set" select="@name"/>
</xsl:call-template>
</xsl:variable>
<xsl:for-each select="///method">
<refsect2>
<title><anchor role="function"><xsl:attribute name="id"><xsl:value-of select="$basename"/>.<xsl:value-of select="@name"/></xsl:attribute></anchor><xsl:value-of select="@name"/> ()</title>
<indexterm><primary><xsl:value-of select="@name"/></primary><secondary><xsl:value-of select="$basename"/></secondary></indexterm>
<programlisting><xsl:value-of select="@name"/> (<xsl:call-template name="method-args"><xsl:with-param name="indent" select="string-length(@name) + 2"/><xsl:with-param name="prefix" select="."/></xsl:call-template>)</programlisting>
<xsl:call-template name="method-doc"/>
</refsect2>
</xsl:for-each>
</xsl:template>
<xsl:template name="properties-synopsis">
<xsl:param name="basename"/>
<xsl:variable name="longest">
<xsl:call-template name="find-longest">
<xsl:with-param name="set" select="///property/@name"/>
</xsl:call-template>