diff options
| -rw-r--r-- | ChangeLog | 15 | ||||
| -rw-r--r-- | configure.ac | 1 | ||||
| -rw-r--r-- | docs/Makefile.am | 12 | ||||
| -rw-r--r-- | docs/reference/pygobject-introduction.xml | 239 | ||||
| -rw-r--r-- | docs/reference/pygobject-ref.xml | 141 | ||||
| -rw-r--r-- | docs/reference/version.xml.in | 1 | ||||
| -rw-r--r-- | docs/xsl/common.xsl | 3 | ||||
| -rw-r--r-- | docs/xsl/html.xsl | 18 | ||||
| -rw-r--r-- | docs/xsl/ref-html-style.xsl | 24 |
9 files changed, 308 insertions, 146 deletions
@@ -1,3 +1,18 @@ +2006-07-19 John Finlay <finlay@moeraki.com> + + * docs/xsl/html.xsl: Output xref links for unknown links. + + * docs/xsl/ref-html-style.xsl: Include refsect1 and refsect2 in + indexed items but only ig they have ids. + + * configure.ac (AC_CONFIG_FILES) : Add docs/reference/version.xml + + * docs/reference/pygobject-ref.xml: Add pygobject-introduction.xml + and version and builddate entities. Remove commented out items. + + * docs/Makefile.am: Add reference/pygobject-introduction.xml and + reference/version.xml.in + 2006-07-18 Johan Dahlin <johan@gnome.org> * docs/Makefile.am (HTMLdir): Install book in $datadir/gtk-doc/html diff --git a/configure.ac b/configure.ac index d317d75..f693cc6 100644 --- a/configure.ac +++ b/configure.ac @@ -128,6 +128,7 @@ AC_CONFIG_FILES( Makefile pygobject-2.0.pc docs/Makefile + docs/reference/version.xml gobject/Makefile examples/Makefile tests/Makefile diff --git a/docs/Makefile.am b/docs/Makefile.am index 2295387..f01825a 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -1,6 +1,7 @@ REF_VERSION = $(PYGOBJECT_MAJOR_VERSION).$(PYGOBJECT_MINOR_VERSION) XMLFILES = \ + reference/pygobject-introduction.xml \ reference/pygobject-classes.xml \ reference/pygobject-constants.xml \ reference/pygobject-ref.xml \ @@ -24,6 +25,8 @@ XSL_DATA = $(XSLFILES) HTMLdir = $(datadir)/gtk-doc/html/pygobject HTML_DATA = \ + html/pygobject-introduction.html \ + html/pygobject-reference-copyright.html \ html/class-gobjectgboxed.html \ html/class-gobjectginterface.html \ html/class-gobjectgpointer.html \ @@ -37,11 +40,14 @@ HTML_DATA = \ html/index.sgml \ html/pygobject.devhelp -BUILT_SOURCES = build_stamp $(HTML_DATA) -CLEANFILES = build_stamp $(HTML_DATA) -EXTRA_DIST = $(XMLFILES) $(XSLFILES) +BUILT_SOURCES = build_stamp $(HTML_DATA) reference/version.xml \ + reference/builddate.xml +CLEANFILES = build_stamp $(HTML_DATA) reference/version.xml \ + reference/builddate.xml +EXTRA_DIST = $(XMLFILES) $(XSLFILES) reference/version.xml.in build_stamp: reference ${XMLFILES} ${XSLFILES} + date '+%B %d, %Y' > reference/builddate.xml xsltproc --nonet --xinclude -o html/ \ --stringparam gtkdoc.bookname "pygobject" \ --stringparam gtkdoc.version ${REF_VERSION} \ diff --git a/docs/reference/pygobject-introduction.xml b/docs/reference/pygobject-introduction.xml new file mode 100644 index 0000000..a139646 --- /dev/null +++ b/docs/reference/pygobject-introduction.xml @@ -0,0 +1,239 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + + <chapter id="pygobject-introduction"> + <title>Introduction</title> + + <para>This document describes many of the <literal>PyGObject</literal> + version 2.12 classes and their methods and associated + functions. Deprecated classes, functions and methods have been + specifically left out of this reference though classes that have become + deprecated since PyGObject 2.0 have been left in but annotated with a + deprecation warning. I have attempted to document as much of the + <literal>PyGObject</literal> <literal>API</literal> as I can but there are + undoubtedly errors and omissions. If you discover any of these please send + me email at <email><ulink + url="mailto:finlay@moeraki.com">finlay@moeraki.com</ulink></email> or file + a bug report at <ulink + url="http://bugzilla.gnome.org">bugzilla.gnome.org</ulink> for the + <literal>pygobject</literal> project. Specific areas that have not been + documented include:</para> + + <itemizedlist> + <listitem> + <simpara>The GParamSpec class</simpara> + </listitem> + </itemizedlist> + + <para>This reference describes the API for <literal>PyGObject</literal> as + of version 2.11.0+ and assumes that the additional API changes for version + 2.12 will not be significant. There will undoubtedly be changes that are + not reflected in this reference. The differences in the API between + version 2.0 and previous versions are denoted in this reference with a + Note that describes the availability of the object, constructor, method or + function. Any of these that do not have a notation can be assumed to be + available in all versions of PyGObject from 2.0 and up. The source code + must be consulted if this reference and your version of + <literal>PyGObject</literal> seem to differ. You are encouraged to use the + latest version of <literal>PyGObject</literal> that is available. See the + <ulink url="http://www.pygtk.org"><literal>PyGTK</literal> + homepage</ulink> for more information and more resources on how to use + PyGObject as well as help in its development.</para> + + <para> The Reference contains a chapter for each + <literal>PyGObject</literal> module containing the class descriptions. The + class descriptions are arranged alphabetically within the + chapters. Currently there is one module chapter:</para> + + <variablelist> + <varlistentry> + <term>The <literal>gobject</literal> module</term> + <listitem><simpara>The classes that are included in the +<literal>gobject</literal> module of <literal>PyGObject</literal> and are +accessed similar to: gobject.GObject. These classes are the base object +classes that the <literal>gtk</literal> and <literal>gtk.gdk</literal> +module classes are built on.</simpara> + </listitem> + </varlistentry> + </variablelist> + +<!-- + <sect1> + <title>Major Changes since Version 2.11</title> + + <para>The major changes in this document since version 2.11 + include:</para> + + <itemizedlist> + <listitem> + <para></para> + </listitem> + </itemizedlist> + + </sect1> +--> + + <sect1 id="pygobject-reference-format"> + <title>Reference Page Format</title> + + <para>Each <literal>PyGObject</literal> class is described in a reference +page that has a number of sections in a fixed format. Each reference page +will have a subset of the following sections:</para> + + <variablelist> + <varlistentry> + <term>Name</term> + <listitem> + <simpara>The name and a one-line description of the +class.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>Synopsis</term> + <listitem> + <simpara>A synopsis of the class and its methods and +optionally a list of associated functions.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>Ancestry</term> + <listitem> + <simpara>The list of the parent classes of the class. This +section may not be present in all class descriptions.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>Properties</term> + <listitem> + <simpara>A list of the properties (internal state) +supported by the class. This section may not be present in all classes. The +property descriptions include the name, the access operations (e.g. Read, +Write), and a brief description. Properties are accessed using the <link +linkend="method-gobject--set-property"><methodname>gobject.set_property</methodname>()</link> +and <link +linkend="method-gobject--get-property"><methodname>gobject.get_property</methodname>()</link> +methods that are available to every <literal>PyGObject</literal> object. This +section may not be present in all class descriptions.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>Attributes</term> + <listitem> + <simpara>A set of internal object state data accessible as Python + attributes (e.g. object.attr). The attribute descriptions include + a name by which the attribute data is accessed, the access mode + (e.g. Read, Write), and a brief description of the attribute. Most + <literal>PyGObject</literal> classes do not support attributes so + this section is not present in most class descriptions.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>Signal Prototypes</term> + <listitem> + <simpara>A list of the signals supported by the class including + the signal name and a synopsis of the signal handler function + prototype. This section may not be present in all class + descriptions.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem><simpara>A description of the class and possibly some of + the methods supported by the class.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>Constructor</term> + <listitem> + <simpara>The description of the class object constructor including + the synopsis with brief parameter descriptions and a description + of th use of the constructor. There may be more than one + constructor description if the constructor supports different + parameter lists. This section may not be present in all class + descriptions.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>Methods</term> + <listitem> + <simpara>A list of methods supported by the class. Each method + description includes: a synopsis of the method and its parameters + as well as a brief description of each parameter and return value + (if any); and, a description of the use of the method.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>Functions</term> + <listitem> + <simpara>A list of related functions. Each function description + includes a synopsis of the function and its parameters and return + value (if any), and a description of the use of the + function.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>Signals</term> + <listitem> + <simpara>A list of signals including a synopsis of the signal + handler prototype function with its parameters and return value + (if any). The signal emission conditions are briefly + described. This section is not present in all class descriptions; + specifically, the <literal>gtk.gdk</literal> classes do not + usually support signals.</simpara> + </listitem> + </varlistentry> + </variablelist> + + <para>The function and method synopsis parameters are displayed in + <emphasis role="bold">bold</emphasis> to denote Python keyword + parameters. Also if the parameter is optional its default value will be + displayed. For example the <link + linkend="function-gobject--signal-lookup"><function>gobject.signal_lookup</function>()</link> + function synopsis is:</para> + + <programlisting> +<methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--signal-lookup">gobject.signal_lookup</link></methodname> + <methodparam><parameter + role="keyword">name</parameter></methodparam> + <methodparam><parameter + role="keyword">type</parameter></methodparam> + </methodsynopsis> +</programlisting> + + <para>The parameters <parameter>name</parameter> and + <parameter>type</parameter> are keyword parameters that can be specified + in a call either by position or keyword (in which case position is not + important). The following calls have the same result:</para> + + <programlisting> + id = gobject.signal_lookup("clicked", gtk.Button) + id = gobject.signal_lookup("clicked", type=gtk.Button) + id = gobject.signal_lookup(name="clicked", type=gtk.Button) + id = gobject.signal_lookup(type=gtk.Button, name="clicked") +</programlisting> + + <para>Parameters that are not keyword parameters are displayed in +<emphasis>italic</emphasis> and must be specified positionally but may also +be optional.</para> + + </sect1> + + <sect1 id="pygobject-reference-copyright"> + <title>Copyright and License Notice</title> + + <para>The PyGObject 2.0 Reference is Copyright (C) 2004-2006 John + Finlay.</para> + + <para>This work is licensed under the Creative Commons + Attribution-ShareAlike License. To view a copy of this license, visit + <ulink + url="http://creativecommons.org/licenses/by-sa/1.0/">http://creativecommons.org/licenses/by-sa/1.0/</ulink> + or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, + California 94305, USA.</para> + + </sect1> + + </chapter> diff --git a/docs/reference/pygobject-ref.xml b/docs/reference/pygobject-ref.xml index 9252ea0..c455145 100644 --- a/docs/reference/pygobject-ref.xml +++ b/docs/reference/pygobject-ref.xml @@ -1,13 +1,15 @@ <?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"> +<!ENTITY builddate SYSTEM "builddate.xml"> ]> -<book id="pygtk-reference" xmlns:xi="http://www.w3.org/2001/XInclude"> +<book id="pygobject-reference" xmlns:xi="http://www.w3.org/2001/XInclude"> <bookinfo> - <pubdate>July 6, 2006</pubdate> + <pubdate>&builddate;</pubdate> <title>PyGObject Reference Manual</title> - <edition>for version 2.12.x</edition> - <releaseinfo>Version 2.11.0</releaseinfo> + <edition>for version &version;</edition> + <releaseinfo>for PyGObject version &version;</releaseinfo> <authorgroup> <author> <firstname>John</firstname> @@ -18,137 +20,18 @@ <para>This reference describes the classes of the python gobject module.</para> </abstract> -<!-- <revhistory> - <revision> - <revnumber>2.9.0</revnumber> - <date>July 7, 2006</date> - <revremark>Release covering PyGTK 2.9.x (GTK+ 2.9)</revremark> - </revision> - <revision> - <revnumber>2.8.2</revnumber> - <date>October 7, 2005</date> - <revremark>Release covering PyGTK 2.8.x (GTK+ 2.8)</revremark> - </revision> - <revision> - <revnumber>2.8.1</revnumber> - <date>September 17, 2005</date> - <revremark>Release covering PyGTK 2.8.x (GTK+ 2.8)</revremark> - </revision> - <revision> - <revnumber>2.8.0</revnumber> - <date>September 7, 2005</date> - <revremark>Release covering PyGTK 2.8.x (GTK+ 2.8)</revremark> - </revision> - <revision> - <revnumber>2.6.0</revnumber> - <date>April 10, 2005</date> - <revremark>First release covering PyGTK 2.6.x (GTK+ 2.6)</revremark> - </revision> - <revision> - <revnumber>2.5.2</revnumber> - <date>March 5, 2005</date> - </revision> - <revision> - <revnumber>2.5.1</revnumber> - <date>December 23, 2004</date> - <revremark>First release covering PyGTK 2.5.1 (GTK+ 2.6)</revremark> - </revision> - <revision> - <revnumber>2.5.0</revnumber> - <date>November 15, 2004</date> - <revremark>First release covering PyGTK 2.5.x</revremark> - </revision> - <revision> - <revnumber>2.4.11</revnumber> - <date>October 3, 2004</date> - </revision> - <revision> - <revnumber>2.4.10</revnumber> - <date>August 11, 2004</date> - </revision> - <revision> - <revnumber>2.4.9</revnumber> - <date>August 3, 2004</date> - </revision> - <revision> - <revnumber>2.4.8</revnumber> - <date>July 1, 2004</date> - </revision> - <revision> - <revnumber>2.4.7</revnumber> - <date>May 19, 2004</date> - </revision> - <revision> - <revnumber>2.4.6</revnumber> - <date>May 17, 2004</date> - </revision> - <revision> - <revnumber>2.4.4</revnumber> - <date>May 5, 2004</date> - </revision> - <revision> - <revnumber>2.4.2</revnumber> - <date>April 29, 2004</date> - </revision> - <revision> - <revnumber>2.4.0</revnumber> - <date>April 27, 2004</date> - <revremark>First release covering PyGTK 2.2 and 2.4</revremark> - </revision> - <revision> - <revnumber>1.9</revnumber> - <date>January 28, 2004</date> - </revision> - <revision> - <revnumber>1.8</revnumber> - <date>October 7, 2003</date> - </revision> - <revision> - <revnumber>1.7</revnumber> - <date>August 23, 2003</date> - </revision> - <revision> - <revnumber>1.6</revnumber> - <date>July 20, 2003</date> - </revision> - <revision> - <revnumber>1.5</revnumber> - <date>July 17, 2003</date> - </revision> - <revision> - <revnumber>1.4</revnumber> - <date>July 16, 2003</date> - </revision> - <revision> - <revnumber>1.3</revnumber> - <date>July 15, 2003</date> - </revision> - <revision> - <revnumber>1.2</revnumber> - <date>July 12, 2003</date> - </revision> - <revision> - <revnumber>1.1</revnumber> - <date>July 11, 2003</date> - </revision> - <revision> - <revnumber>1.0</revnumber> - <date>July 2, 2003</date> - <revremark>First release for PyGTK 2.0</revremark> - </revision> - </revhistory>--> </bookinfo> <toc> </toc> - <!-- <xi:include href="pygtk-introduction.xml"/> --> + <xi:include href="pygobject-introduction.xml"/> <xi:include href="pygobject-classes.xml"/> + <!-- -<appendix id="pygtk-ref-changelog"> -<title>ChangeLog</title> - <xi:include href="ChangeLog.xml"/> -</appendix> - --> + <index> + <title>Index</title> + </index> +--> </book> diff --git a/docs/reference/version.xml.in b/docs/reference/version.xml.in new file mode 100644 index 0000000..a24f987 --- /dev/null +++ b/docs/reference/version.xml.in @@ -0,0 +1 @@ +@PACKAGE_VERSION@ diff --git a/docs/xsl/common.xsl b/docs/xsl/common.xsl index cb4a7d2..606313f 100644 --- a/docs/xsl/common.xsl +++ b/docs/xsl/common.xsl @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- mode: xml -*--> +<?xml version='1.0'?> <!DOCTYPE xsl:stylesheet [ ]> @@ -16,5 +16,4 @@ </xsl:choose> </xsl:template> - </xsl:stylesheet> diff --git a/docs/xsl/html.xsl b/docs/xsl/html.xsl index 350f183..3bb5638 100644 --- a/docs/xsl/html.xsl +++ b/docs/xsl/html.xsl @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- mode: xml -*--> +<?xml version='1.0'?> <!DOCTYPE xsl:stylesheet [ <!ENTITY RE " "> <!ENTITY nbsp " "> @@ -262,6 +262,22 @@ <xsl:apply-templates select="."/> </xsl:template> + <!-- ========================================================= --> + <!-- template to output gtkdoclink elements for the unknown targets --> + + <xsl:template match="link"> + <xsl:choose> + <xsl:when test="id(@linkend)"> + <xsl:apply-imports/> + </xsl:when> + <xsl:otherwise> + <PYGTKDOCLINK HREF="{@linkend}"> + <xsl:apply-templates/> + </PYGTKDOCLINK> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + <xsl:template match="parameter" mode="python"> <span class="{name(.)}"> <xsl:choose> diff --git a/docs/xsl/ref-html-style.xsl b/docs/xsl/ref-html-style.xsl index 124a117..4fc86e7 100644 --- a/docs/xsl/ref-html-style.xsl +++ b/docs/xsl/ref-html-style.xsl @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- mode: xml -*--> +<?xml version='1.0'?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'> <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"/> @@ -14,7 +14,7 @@ <xsl:with-param name="filename" select="'index.sgml'"/> <xsl:with-param name="content"> <!-- check all anchor and refentry elements --> - <xsl:apply-templates select="//anchor|//refentry" + <xsl:apply-templates select="//anchor|//refentry|//refsect1|//refsect2" mode="generate.index.mode"/> </xsl:with-param> <xsl:with-param name="encoding" select="'utf-8'"/> @@ -23,16 +23,18 @@ <xsl:template match="*" mode="generate.index.mode"> <xsl:if test="not(@href)"> - <xsl:text><ANCHOR id="</xsl:text> - <xsl:value-of select="@id"/> - <xsl:text>" href="</xsl:text> - <xsl:if test="$gtkdoc.bookname"> - <xsl:value-of select="$gtkdoc.bookname"/> - <xsl:text>/</xsl:text> - </xsl:if> - <xsl:call-template name="href.target"/> - <xsl:text>"> + <xsl:if test="@id"> + <xsl:text><ANCHOR id="</xsl:text> + <xsl:value-of select="@id"/> + <xsl:text>" href="</xsl:text> + <xsl:if test="$gtkdoc.bookname"> + <xsl:value-of select="$gtkdoc.bookname"/> + <xsl:text>/</xsl:text> + </xsl:if> + <xsl:call-template name="href.target"/> + <xsl:text>"> </xsl:text> + </xsl:if> </xsl:if> </xsl:template> |