diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | Makefile.am | 1 | ||||
| -rwxr-xr-x | autogen.sh | 1 | ||||
| -rw-r--r-- | configure.ac | 8 | ||||
| -rw-r--r-- | doc/Makefile.am | 2 | ||||
| -rw-r--r-- | doc/api/.gitignore | 27 | ||||
| -rw-r--r-- | doc/api/Makefile.am | 71 | ||||
| -rwxr-xr-x | doc/api/clean.sh | 8 | ||||
| -rw-r--r-- | doc/api/colord-docs.xml | 106 | ||||
| -rw-r--r-- | doc/api/dbus/.gitignore | 3 | ||||
| -rw-r--r-- | doc/api/dbus/Makefile.am | 19 | ||||
| -rw-r--r-- | doc/api/dbus/dbus-introspect-docs.dtd | 32 | ||||
| -rw-r--r-- | doc/api/dbus/spec-to-docbook.xsl | 543 | ||||
| -rw-r--r-- | doc/api/version.xml.in | 1 | ||||
| -rw-r--r-- | doc/website/using.html | 8 | ||||
| -rw-r--r-- | src/org.freedesktop.ColorManager.Device.xml | 6 | ||||
| -rw-r--r-- | src/org.freedesktop.ColorManager.Profile.xml | 6 | ||||
| -rw-r--r-- | src/org.freedesktop.ColorManager.xml | 6 |
18 files changed, 838 insertions, 11 deletions
@@ -28,3 +28,4 @@ missing stamp-h1 *.patch NEWS.new +gtk-doc.make diff --git a/Makefile.am b/Makefile.am index 25202a5..65643fa 100644 --- a/Makefile.am +++ b/Makefile.am @@ -13,6 +13,7 @@ SUBDIRS = \ libcolord \ client \ rules \ + doc \ src snapshot: @@ -25,6 +25,7 @@ if ([ -z "$*" ] && [ "x$NOCONFIGURE" = "x" ]) ; then echo fi +(cd $srcdir && gtkdocize) || exit 1 (cd $srcdir && autoreconf --force --install) || exit 1 (cd $srcdir && intltoolize) || exit 1 diff --git a/configure.ac b/configure.ac index 22613c7..736c240 100644 --- a/configure.ac +++ b/configure.ac @@ -13,6 +13,9 @@ AM_INIT_AUTOMAKE([1.9 tar-ustar dist-bzip2]) AC_CONFIG_HEADERS([config.h]) AC_CONFIG_MACRO_DIR([m4]) +# set up gtk-doc +GTK_DOC_CHECK(1.9) + # use this in cd-version.h CD_MAJOR_VERSION=cd_major_version CD_MINOR_VERSION=cd_minor_version @@ -45,6 +48,7 @@ AC_PROG_INSTALL LT_INIT AM_PROG_CC_C_O IT_PROG_INTLTOOL([0.35.0]) +AC_PATH_PROG(XSLTPROC, xsltproc) dnl --------------------------------------------------------------------------- dnl - Use strict options (default enabled for devs, disabled in releases) @@ -190,6 +194,10 @@ AC_CONFIG_FILES([ Makefile etc/Makefile man/Makefile +doc/Makefile +doc/api/Makefile +doc/api/dbus/Makefile +doc/api/version.xml data/Makefile data/tests/Makefile policy/Makefile diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..265f2ec --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,2 @@ +SUBDIRS = \ + api diff --git a/doc/api/.gitignore b/doc/api/.gitignore new file mode 100644 index 0000000..614262e --- /dev/null +++ b/doc/api/.gitignore @@ -0,0 +1,27 @@ +Makefile.in +Makefile.libs +.libs +*.bak +*.gcno +*.out +*.txt +tmpl +xml +html +html-build.stamp +html.stamp +colord-docs.xml +colord.args +colord.hierarchy +colord.interfaces +colord.prerequisites +colord.signals +colord.types +colord-scan.c +colord-scan.o +scan-build.stamp +sgml-build.stamp +sgml.stamp +tmpl-build.stamp +tmpl.stamp +version.xml diff --git a/doc/api/Makefile.am b/doc/api/Makefile.am new file mode 100644 index 0000000..c991693 --- /dev/null +++ b/doc/api/Makefile.am @@ -0,0 +1,71 @@ + +SUBDIRS = dbus + +AUTOMAKE_OPTIONS = 1.7 + +# The name of the module. +DOC_MODULE=colord + +# The top-level SGML file. +DOC_MAIN_SGML_FILE=colord-docs.xml + +# Extra options to supply to gtkdoc-scan +SCAN_OPTIONS=--ignore-headers=config.h + +# The directory containing the source code. Relative to $(srcdir) +DOC_SOURCE_DIR=../../libcolord + +# Used for dependencies +HFILE_GLOB= +CFILE_GLOB= + +# Headers to ignore +IGNORE_HFILES= \ + config.h + +# CFLAGS and LDFLAGS for compiling scan program. Only needed +# if $(DOC_MODULE).types is non-empty. +INCLUDES = \ + $(GLIB_CFLAGS) \ + -I$(top_srcdir)/libcolord \ + -I$(top_builddir)/libcolord + +COLORD_LIBS = $(top_builddir)/libcolord/.libs/libcolord.so + +GTKDOC_LIBS = \ + $(GLIB_LIBS) \ + $(COLORD_LIBS) + +# Extra options to supply to gtkdoc-mkdb +MKDB_OPTIONS=--sgml-mode --output-format=xml + +# Extra options to supply to gtkdoc-mktmpl +MKTMPL_OPTIONS= + +# Non-autogenerated SGML files to be included in $(DOC_MAIN_SGML_FILE) +content_files = \ + version.xml \ + dbus/org.freedesktop.ColorManager.ref.xml + +# Images to copy into HTML directory +HTML_IMAGES = \ + $(NULL) + +# Extra options to supply to gtkdoc-fixref +FIXXREF_OPTIONS= + +MAINTAINERCLEANFILES = \ + *~ \ + Makefile.in \ + colord.types \ + colord-*.txt + +if ENABLE_GTK_DOC +include $(top_srcdir)/gtk-doc.make +else +EXTRA_DIST = +endif + +# Version information for marking the documentation +EXTRA_DIST += version.xml.in + diff --git a/doc/api/clean.sh b/doc/api/clean.sh new file mode 100755 index 0000000..4eaba11 --- /dev/null +++ b/doc/api/clean.sh @@ -0,0 +1,8 @@ +rm -f *.txt +rm -f colord-scan.* +rm -f colord.types +rm -f html/*.html +rm -f html/*.png +rm -f tmpl/* +rm -f *.stamp + diff --git a/doc/api/colord-docs.xml b/doc/api/colord-docs.xml new file mode 100644 index 0000000..a0a7285 --- /dev/null +++ b/doc/api/colord-docs.xml @@ -0,0 +1,106 @@ +<?xml version="1.0"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ +<!ENTITY version SYSTEM "version.xml"> +]> +<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> + <bookinfo> + <title>colord Reference Manual</title> + <releaseinfo>Version &version;</releaseinfo> + <authorgroup> + <author> + <firstname>Richard</firstname> + <surname>Hughes</surname> + <affiliation> + <address> + <email>richard@hughsie.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2011</year> + <holder>The colord authors</holder> + </copyright> + + <legalnotice> + <para> + Permission is granted to copy, distribute and/or modify this + document under the terms of the <citetitle>GNU Free + Documentation License</citetitle>, Version 1.1 or any later + version published by the Free Software Foundation with no + Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. You may obtain a copy of the <citetitle>GNU Free + Documentation License</citetitle> from the Free Software + Foundation by visiting <ulink type="http" + url="http://www.fsf.org">their Web site</ulink> or by writing + to: + + <address> + The Free Software Foundation, Inc., + <street>59 Temple Place</street> - Suite 330, + <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>, + <country>USA</country> + </address> + </para> + + <para> + Many of the names used by companies to distinguish their + products and services are claimed as trademarks. Where those + names appear in any freedesktop.org documentation, and those + trademarks are made aware to the members of the + freedesktop.org Project, the names have been printed in caps + or initial caps. + </para> + </legalnotice> + </bookinfo> + + <reference id="ref-dbus"> + <title>D-Bus API Reference</title> + <partintro> + <para> + This part documents the D-Bus interface used to access the + colord daemon. + </para> + </partintro> + <xi:include href="dbus/org.freedesktop.ColorManager.ref.xml"/> + <xi:include href="dbus/org.freedesktop.ColorManager.Device.ref.xml"/> + <xi:include href="dbus/org.freedesktop.ColorManager.Profile.ref.xml"/> + </reference> + + <reference id="libcolord"> + <title>libcolord GObjects</title> + <partintro> + <para> + This part documents GObjects used in libcolord. + </para> + </partintro> + <xi:include href="xml/cd-client.xml"/> + <xi:include href="xml/cd-device.xml"/> + <xi:include href="xml/cd-profile.xml"/> + </reference> + + <reference id="libcolord-glib-helpers"> + <title>libcolord-glib helpers</title> + <partintro> + <para> + This part documents helper funtions in libcolord-glib. + </para> + </partintro> + <xi:include href="xml/cd-version.xml"/> + </reference> + + <index> + <title>Index</title> + </index> + + <!-- License --> + + <appendix id="license"> + <title>License</title> + <para> +<programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../COPYING" parse="text"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting> + </para> + </appendix> +</book> diff --git a/doc/api/dbus/.gitignore b/doc/api/dbus/.gitignore new file mode 100644 index 0000000..7879383 --- /dev/null +++ b/doc/api/dbus/.gitignore @@ -0,0 +1,3 @@ +*.ref.xml +*.ref.xml + diff --git a/doc/api/dbus/Makefile.am b/doc/api/dbus/Makefile.am new file mode 100644 index 0000000..e78afce --- /dev/null +++ b/doc/api/dbus/Makefile.am @@ -0,0 +1,19 @@ + +all : org.freedesktop.ColorManager.ref.xml org.freedesktop.ColorManager.Device.ref.xml org.freedesktop.ColorManager.Profile.ref.xml + +org.freedesktop.ColorManager.ref.xml : $(top_srcdir)/src/org.freedesktop.ColorManager.xml $(top_srcdir)/doc/api/dbus/spec-to-docbook.xsl + echo "<?xml version=\"1.0\"?>""<!DOCTYPE refentry PUBLIC \"-//OASIS//DTD DocBook XML V4.1.2//EN\" \"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd\">" > $@ + $(XSLTPROC) $(top_srcdir)/doc/api/dbus/spec-to-docbook.xsl $< | tail -n +2 >> $@ + +org.freedesktop.ColorManager.Device.ref.xml : $(top_srcdir)/src/org.freedesktop.ColorManager.Device.xml $(top_srcdir)/doc/api/dbus/spec-to-docbook.xsl + echo "<?xml version=\"1.0\"?>""<!DOCTYPE refentry PUBLIC \"-//OASIS//DTD DocBook XML V4.1.2//EN\" \"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd\">" > $@ + $(XSLTPROC) $(top_srcdir)/doc/api/dbus/spec-to-docbook.xsl $< | tail -n +2 >> $@ + +org.freedesktop.ColorManager.Profile.ref.xml : $(top_srcdir)/src/org.freedesktop.ColorManager.Profile.xml $(top_srcdir)/doc/api/dbus/spec-to-docbook.xsl + echo "<?xml version=\"1.0\"?>""<!DOCTYPE refentry PUBLIC \"-//OASIS//DTD DocBook XML V4.1.2//EN\" \"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd\">" > $@ + $(XSLTPROC) $(top_srcdir)/doc/api/dbus/spec-to-docbook.xsl $< | tail -n +2 >> $@ + +EXTRA_DIST = spec-to-docbook.xsl dbus-introspect-docs.dtd + +clean-local : + rm -f *~ *.ref.xml diff --git a/doc/api/dbus/dbus-introspect-docs.dtd b/doc/api/dbus/dbus-introspect-docs.dtd new file mode 100644 index 0000000..ca918fb --- /dev/null +++ b/doc/api/dbus/dbus-introspect-docs.dtd @@ -0,0 +1,32 @@ +<!-- 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> diff --git a/doc/api/dbus/spec-to-docbook.xsl b/doc/api/dbus/spec-to-docbook.xsl new file mode 100644 index 0000000..1864414 --- /dev/null +++ b/doc/api/dbus/spec-to-docbook.xsl @@ -0,0 +1,543 @@ +<?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> + <para> + <xsl:apply-templates select="//interface/doc:doc"/> + </para> + </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"/> + + <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: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> + </refsect2> + + <xsl:call-template name="property-doc"/> + + </xsl:for-each> +</xsl:template> + +<xsl:template name="signal-doc"> + <xsl:apply-templates select="doc:doc/doc:description"/> + + <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: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> + </refsect2> + + <xsl:call-template name="signal-doc"/> + + </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> + <xsl:call-template name="listitems-do-term"><xsl:with-param name="str" select="doc:term"/></xsl:call-template> + <xsl:apply-templates select="doc:definition"/> + </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"/> + + <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: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"> + <refsect3> + <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> + </refsect3> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="count(doc:doc/doc:permission) > 0"> + <refsect3> + <title>Permissions</title> + <xsl:apply-templates select="doc:doc/doc:permission"/> + </refsect3> + </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> + </refsect2> + + <xsl:call-template name="method-doc"/> + + </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> + </xsl:variable> + <xsl:for-each select="///property"> +<link><xsl:attribute name="linkend"><xsl:value-of select="$basename"/>:<xsl:value-of select="@name"/></xsl:attribute>'<xsl:value-of select="@name"/>'</link><xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$longest - string-length(@name) + 1"/></xsl:call-template> <xsl:call-template name="property-args"><xsl:with-param name="indent" select="$longest + 2"/></xsl:call-template> +</xsl:for-each> +</xsl:template> + + +<xsl:template name="signals-synopsis"> + <xsl:param name="basename"/> + <xsl:variable name="longest"> + <xsl:call-template name="find-longest"> + <xsl:with-param name="set" select="///signal/@name"/> + </xsl:call-template> + </xsl:variable> + <xsl:for-each select="///signal"> +<link><xsl:attribute name="linkend"><xsl:value-of select="$basename"/>::<xsl:value-of select="@name"/></xsl:attribute><xsl:value-of select="@name"/></link><xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$longest - string-length(@name) + 1"/></xsl:call-template>(<xsl:call-template name="signal-args"><xsl:with-param name="indent" select="$longest + 2"/><xsl:with-param name="prefix" select="///signal"/></xsl:call-template>) +</xsl:for-each> +</xsl:template> + + +<xsl:template name="methods-synopsis"> + <xsl:param name="basename"/> + <xsl:variable name="longest"> + <xsl:call-template name="find-longest"> + <xsl:with-param name="set" select="///method/@name"/> + </xsl:call-template> + </xsl:variable> + <xsl:for-each select="///method"> +<link><xsl:attribute name="linkend"><xsl:value-of select="$basename"/>.<xsl:value-of select="@name"/></xsl:attribute><xsl:value-of select="@name"/></link><xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$longest - string-length(@name) + 1"/></xsl:call-template>(<xsl:call-template name="method-args"><xsl:with-param name="indent" select="$longest + 2"/><xsl:with-param name="prefix" select="///method"/></xsl:call-template>) +</xsl:for-each> +</xsl:template> + + +<xsl:template name="method-args"><xsl:param name="indent"/><xsl:param name="prefix"/><xsl:variable name="longest"><xsl:call-template name="find-longest"><xsl:with-param name="set" select="$prefix/arg/@type"/></xsl:call-template></xsl:variable><xsl:for-each select="arg"><xsl:value-of select="@direction"/> +<xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="4 - string-length(@direction)"/></xsl:call-template>'<xsl:value-of select="@type"/>'<xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$longest - string-length(@type) + 1"/></xsl:call-template> +<xsl:value-of select="@name"/><xsl:if test="not(position() = last())">, +<xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$indent"/></xsl:call-template></xsl:if> +</xsl:for-each> +</xsl:template> + + +<xsl:template name="signal-args"><xsl:param name="indent"/><xsl:param name="prefix"/><xsl:variable name="longest"><xsl:call-template name="find-longest"><xsl:with-param name="set" select="$prefix/arg/@type"/></xsl:call-template></xsl:variable><xsl:for-each select="arg">'<xsl:value-of select="@type"/>'<xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$longest - string-length(@type) + 1"/></xsl:call-template> +<xsl:value-of select="@name"/><xsl:if test="not(position() = last())">, +<xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$indent"/></xsl:call-template></xsl:if> +</xsl:for-each> +</xsl:template> + + +<xsl:template name="property-args"><xsl:param name="indent"/> +<xsl:value-of select="@access"/><xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="9 - string-length(@access) + 1"/></xsl:call-template>'<xsl:value-of select="@type"/>' +</xsl:template> + + +<xsl:template name="pad-spaces"> + <xsl:param name="width"/> + <xsl:variable name="spaces" xml:space="preserve"> </xsl:variable> + <xsl:value-of select="substring($spaces,1,$width)"/> +</xsl:template> + + +<xsl:template name="find-longest"> + <xsl:param name="set"/> + <xsl:param name="index" select="1"/> + <xsl:param name="longest" select="0"/> + + <xsl:choose> + <xsl:when test="$index > count($set)"> + <!--finished looking--> + <xsl:value-of select="$longest"/> + </xsl:when> + <xsl:when test="string-length($set[$index])>$longest"> + <!--found new longest--> + <xsl:call-template name="find-longest"> + <xsl:with-param name="set" select="$set"/> + <xsl:with-param name="index" select="$index + 1"/> + <xsl:with-param name="longest" select="string-length($set[$index])"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <!--this isn't any longer--> + <xsl:call-template name="find-longest"> + <xsl:with-param name="set" select="$set"/> + <xsl:with-param name="index" select="$index + 1"/> + <xsl:with-param name="longest" select="$longest"/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + + +<xsl:template name="interface-basename"> + <xsl:param name="str"/> + <xsl:choose> + <xsl:when test="contains($str,'.')"> + <xsl:call-template name="interface-basename"> + <xsl:with-param name="str" select="substring-after($str,'.')"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$str"/> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + +</xsl:stylesheet> diff --git a/doc/api/version.xml.in b/doc/api/version.xml.in new file mode 100644 index 0000000..d78bda9 --- /dev/null +++ b/doc/api/version.xml.in @@ -0,0 +1 @@ +@VERSION@ diff --git a/doc/website/using.html b/doc/website/using.html index 83e8eb8..e93e848 100644 --- a/doc/website/using.html +++ b/doc/website/using.html @@ -78,7 +78,7 @@ See the <a href="screenshots.html">screenshots page</a> for more details. <h2>Using libcolord:</h2> <p> -The <a href="gtk-doc/CdClient.html">libcolord gobject library</a> +The <a href="api/libcolord.html">libcolord gobject library</a> wraps the DBUS interface in a nice glib-style API. This makes designing programs that use libcolord can concentrate on core functionality rather that the DBUS and colord internals. @@ -93,6 +93,9 @@ devices = cd_client_get_devices_sync (client, cancellable, &error); g_object_unref (client); g_ptr_array_unref (devices); </pre> +<p> +The latest documentation for libcolord is available <a href="api/">here</a>. +</p> <h2>Using the raw DBUS API:</h2> <p> @@ -101,7 +104,8 @@ gobject dependency is needed. This is not difficult, although does require more code than just using libcolord. See this file for an example <a href="http://gitorious.org/colord/master/blobs/master/doc/raw-dbus.c">raw-dbus.c</a>. -The latest interface is available in the source tree or <a href="http://gitweb.freedesktop.org/?p=colord.git;a=blob;f=src/org.freedesktop.colord.xml">on-line</a>. +The latest interface description is available <a href="http://gitweb.freedesktop.org/?p=colord.git;a=blob;f=src/org.freedesktop.colord.xml">on-line</a> +or viewable in the <a href="api/">generated help</a> pages. </p> <p>Back to the <a href="index.html">main page</a></p> diff --git a/src/org.freedesktop.ColorManager.Device.xml b/src/org.freedesktop.ColorManager.Device.xml index 7024bdc..da9c748 100644 --- a/src/org.freedesktop.ColorManager.Device.xml +++ b/src/org.freedesktop.ColorManager.Device.xml @@ -1,7 +1,7 @@ <!DOCTYPE node PUBLIC -'-//freedesktop//DTD D-BUS Object Introspection 1.0//EN' -'http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd'> -<node> +"-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" +"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"> +<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd"> <interface name='org.freedesktop.ColorManager.Device'> <doc:doc> <doc:description> diff --git a/src/org.freedesktop.ColorManager.Profile.xml b/src/org.freedesktop.ColorManager.Profile.xml index 3c57f00..0020a45 100644 --- a/src/org.freedesktop.ColorManager.Profile.xml +++ b/src/org.freedesktop.ColorManager.Profile.xml @@ -1,7 +1,7 @@ <!DOCTYPE node PUBLIC -'-//freedesktop//DTD D-BUS Object Introspection 1.0//EN' -'http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd'> -<node> +"-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" +"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"> +<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd"> <interface name='org.freedesktop.ColorManager.Profile'> <doc:doc> <doc:description> diff --git a/src/org.freedesktop.ColorManager.xml b/src/org.freedesktop.ColorManager.xml index 2df0422..1a0273c 100644 --- a/src/org.freedesktop.ColorManager.xml +++ b/src/org.freedesktop.ColorManager.xml @@ -1,7 +1,7 @@ <!DOCTYPE node PUBLIC -'-//freedesktop//DTD D-BUS Object Introspection 1.0//EN' -'http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd'> -<node> +"-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" +"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"> +<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd"> <interface name='org.freedesktop.ColorManager'> <doc:doc> <doc:description> |