mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-03-03 22:52:09 +01:00
docs: switch to xi:inbclude for the content to save some more seconds
This commit is contained in:
Stefan Kost
parent
00db5238d9
commit
7211f7f8eb
@ -1,29 +1,6 @@
|
|||||||
<?xml version="1.0"?>
|
<?xml version="1.0"?>
|
||||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||||
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
|
||||||
<!ENTITY gobject-GType SYSTEM "xml/gtype.xml">
|
|
||||||
<!ENTITY gobject-GTypePlugin SYSTEM "xml/gtypeplugin.xml">
|
|
||||||
<!ENTITY gobject-GTypeModule SYSTEM "xml/gtypemodule.xml">
|
|
||||||
<!ENTITY gobject-The-Base-Object-Type SYSTEM "xml/objects.xml">
|
|
||||||
<!ENTITY gobject-Enumeration-and-Flag-Types SYSTEM "xml/enumerations_flags.xml">
|
|
||||||
<!ENTITY gobject-Boxed-Types SYSTEM "xml/gboxed.xml">
|
|
||||||
<!ENTITY gobject-Generic-values SYSTEM "xml/generic_values.xml">
|
|
||||||
<!ENTITY gobject-param-value-types SYSTEM "xml/param_value_types.xml">
|
|
||||||
<!ENTITY gobject-GParamSpec SYSTEM "xml/gparamspec.xml">
|
|
||||||
<!ENTITY gobject-Varargs-Value-Collection SYSTEM "xml/value_collection.xml">
|
|
||||||
<!ENTITY gobject-Signals SYSTEM "xml/signals.xml">
|
|
||||||
<!ENTITY gobject-Closures SYSTEM "xml/gclosure.xml">
|
|
||||||
<!ENTITY gobject-Value-Arrays SYSTEM "xml/value_arrays.xml">
|
|
||||||
<!ENTITY glib-mkenums SYSTEM "glib-mkenums.xml">
|
|
||||||
<!ENTITY glib-genmarshal SYSTEM "glib-genmarshal.xml">
|
|
||||||
<!ENTITY gobject-query SYSTEM "gobject-query.xml">
|
|
||||||
|
|
||||||
<!ENTITY tutorial-Intro SYSTEM "tut_intro.xml">
|
|
||||||
<!ENTITY tutorial-GType SYSTEM "tut_gtype.xml">
|
|
||||||
<!ENTITY tutorial-GObject SYSTEM "tut_gobject.xml">
|
|
||||||
<!ENTITY tutorial-GSignal SYSTEM "tut_gsignal.xml">
|
|
||||||
<!ENTITY tutorial-HowTo SYSTEM "tut_howto.xml">
|
|
||||||
<!ENTITY tutorial-Tools SYSTEM "tut_tools.xml">
|
|
||||||
|
|
||||||
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
|
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
|
||||||
<!ENTITY version SYSTEM "version.xml">
|
<!ENTITY version SYSTEM "version.xml">
|
||||||
@ -85,46 +62,38 @@
|
|||||||
<part label="I">
|
<part label="I">
|
||||||
<title>Concepts</title>
|
<title>Concepts</title>
|
||||||
|
|
||||||
&tutorial-Intro;
|
<xi:include href="tut_intro.xml" />
|
||||||
&tutorial-GType;
|
<xi:include href="tut_gtype.xml" />
|
||||||
&tutorial-GObject;
|
<xi:include href="tut_gobject.xml" />
|
||||||
&tutorial-GSignal;
|
<xi:include href="tut_gsignal.xml" />
|
||||||
</part>
|
</part>
|
||||||
<reference label="II">
|
<reference label="II">
|
||||||
<title>API Reference</title>
|
<title>API Reference</title>
|
||||||
|
|
||||||
&gobject-GType;
|
<xi:include href="xml/gtype.xml" />
|
||||||
&gobject-GTypePlugin;
|
<xi:include href="xml/gtypeplugin.xml" />
|
||||||
&gobject-GTypeModule;
|
<xi:include href="xml/gtypemodule.xml" />
|
||||||
&gobject-The-Base-Object-Type;
|
<xi:include href="xml/objects.xml" />
|
||||||
&gobject-Enumeration-and-Flag-Types;
|
<xi:include href="xml/enumerations_flags.xml" />
|
||||||
&gobject-Boxed-Types;
|
<xi:include href="xml/gboxed.xml" />
|
||||||
&gobject-Generic-values;
|
<xi:include href="xml/generic_values.xml" />
|
||||||
&gobject-param-value-types;
|
<xi:include href="xml/param_value_types.xml" />
|
||||||
&gobject-Varargs-Value-Collection;
|
<xi:include href="xml/gparamspec.xml" />
|
||||||
&gobject-GParamSpec;
|
<xi:include href="xml/value_collection.xml" />
|
||||||
&gobject-Signals;
|
<xi:include href="xml/signals.xml" />
|
||||||
&gobject-Closures;
|
<xi:include href="xml/gclosure.xml" />
|
||||||
&gobject-Value-Arrays;
|
<xi:include href="xml/value_arrays.xml" />
|
||||||
|
|
||||||
</reference>
|
</reference>
|
||||||
<reference label="III">
|
<reference label="III">
|
||||||
<title>Tools Reference</title>
|
<title>Tools Reference</title>
|
||||||
|
|
||||||
&glib-mkenums;
|
<xi:include href="glib-mkenums.xml" />
|
||||||
&glib-genmarshal;
|
<xi:include href="glib-genmarshal.xml" />
|
||||||
&gobject-query;
|
<xi:include href="gobject-query.xml" />
|
||||||
</reference>
|
</reference>
|
||||||
<part label="IV">
|
|
||||||
<title>Tutorial</title>
|
|
||||||
|
|
||||||
&tutorial-HowTo;
|
<xi:include href="tut_howto.xml" />
|
||||||
</part>
|
<xi:include href="tut_tools.xml" />
|
||||||
<part label="V">
|
|
||||||
<title>Related Tools</title>
|
|
||||||
|
|
||||||
&tutorial-Tools;
|
|
||||||
</part>
|
|
||||||
|
|
||||||
<index id="api-index-full">
|
<index id="api-index-full">
|
||||||
<title>Index</title>
|
<title>Index</title>
|
||||||
|
|||||||
@ -1,4 +1,7 @@
|
|||||||
<?xml version='1.0' encoding="ISO-8859-1"?>
|
<?xml version='1.0' encoding="ISO-8859-1"?>
|
||||||
|
<!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="chapter-gobject">
|
<chapter id="chapter-gobject">
|
||||||
<title>The GObject base class</title>
|
<title>The GObject base class</title>
|
||||||
|
|
||||||
|
|||||||
@ -1,4 +1,7 @@
|
|||||||
<?xml version='1.0' encoding="ISO-8859-1"?>
|
<?xml version='1.0' encoding="ISO-8859-1"?>
|
||||||
|
<!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="chapter-signal">
|
<chapter id="chapter-signal">
|
||||||
<title>The GObject messaging system</title>
|
<title>The GObject messaging system</title>
|
||||||
|
|
||||||
|
|||||||
@ -1,4 +1,7 @@
|
|||||||
<?xml version='1.0' encoding="ISO-8859-1"?>
|
<?xml version='1.0' encoding="ISO-8859-1"?>
|
||||||
|
<!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="chapter-gtype">
|
<chapter id="chapter-gtype">
|
||||||
<title>The GLib Dynamic Type System</title>
|
<title>The GLib Dynamic Type System</title>
|
||||||
|
|
||||||
@ -900,7 +903,7 @@ maman_ibaz_base_init (gpointer g_iface)
|
|||||||
|
|
||||||
<para>
|
<para>
|
||||||
The above process can be summarized as follows:
|
The above process can be summarized as follows:
|
||||||
<table id="ginterface-init-table">
|
<table id="ginterface-fini-table">
|
||||||
<title>Interface Finalization</title>
|
<title>Interface Finalization</title>
|
||||||
<tgroup cols="3">
|
<tgroup cols="3">
|
||||||
<colspec colwidth="*" colnum="1" align="left"/>
|
<colspec colwidth="*" colnum="1" align="left"/>
|
||||||
|
|||||||
@ -1,11 +1,16 @@
|
|||||||
<?xml version='1.0' encoding="ISO-8859-1"?>
|
<?xml version='1.0' encoding="ISO-8859-1"?>
|
||||||
<partintro>
|
<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||||
<para>
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
|
||||||
This chapter tries to answer the real-life questions of users and presents
|
]>
|
||||||
the most common scenario use cases I could come up with.
|
<part label="IV">
|
||||||
The use cases are presented from most likely to less likely.
|
<title>Tutorial</title>
|
||||||
</para>
|
<partintro>
|
||||||
</partintro>
|
<para>
|
||||||
|
This chapter tries to answer the real-life questions of users and presents
|
||||||
|
the most common scenario use cases I could come up with.
|
||||||
|
The use cases are presented from most likely to less likely.
|
||||||
|
</para>
|
||||||
|
</partintro>
|
||||||
|
|
||||||
<chapter id="howto-gobject">
|
<chapter id="howto-gobject">
|
||||||
<title>How to define and implement a new GObject</title>
|
<title>How to define and implement a new GObject</title>
|
||||||
@ -1712,4 +1717,4 @@ g_object_do_class_init (GObjectClass *class)
|
|||||||
|
|
||||||
</sect2>
|
</sect2>
|
||||||
-->
|
-->
|
||||||
|
</part>
|
||||||
|
|||||||
@ -1,4 +1,7 @@
|
|||||||
<?xml version='1.0' encoding="ISO-8859-1"?>
|
<?xml version='1.0' encoding="ISO-8859-1"?>
|
||||||
|
<!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="chapter-intro">
|
<chapter id="chapter-intro">
|
||||||
<title>Background</title>
|
<title>Background</title>
|
||||||
|
|
||||||
|
|||||||
@ -1,106 +1,112 @@
|
|||||||
<?xml version='1.0' encoding="ISO-8859-1"?>
|
<?xml version='1.0' encoding="ISO-8859-1"?>
|
||||||
<partintro>
|
<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||||
<para>
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
|
||||||
Several useful developer tools have been build around GObject
|
]>
|
||||||
technology. The next sections briefly introduce them and link to
|
<part label="V">
|
||||||
the respective project pages.
|
<title>Related Tools</title>
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
<partintro>
|
||||||
For example, writing GObjects is often seen as a tedious task. It
|
<para>
|
||||||
requires a lot of typing and just doing a copy/paste requires a
|
Several useful developer tools have been build around GObject
|
||||||
great deal of care. A lot of projects and scripts have been
|
technology. The next sections briefly introduce them and link to
|
||||||
written to generate GObject skeleton form boilerplate code, or
|
the respective project pages.
|
||||||
even translating higher-level language into plain C.
|
</para>
|
||||||
</para>
|
|
||||||
</partintro>
|
|
||||||
|
|
||||||
<chapter id="tools-vala">
|
|
||||||
<title>Vala</title>
|
|
||||||
<para>
|
|
||||||
From the <ulink url="http://live.gnome.org/Vala">Vala
|
|
||||||
homepage</ulink> itself: <quote>Vala is a new programming language
|
|
||||||
that aims to bring modern programming language features to GNOME
|
|
||||||
developers without imposing any additional runtime requirements
|
|
||||||
and without using a different ABI compared to applications and
|
|
||||||
libraries written in C.</quote>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The syntax of Vala is similar to C#. The available compiler
|
|
||||||
translates Vala into GObject C code. It can also compile
|
|
||||||
non-GObject C, using plain C API.
|
|
||||||
</para>
|
|
||||||
</chapter>
|
|
||||||
|
|
||||||
<chapter id="tools-gob">
|
|
||||||
<title>GObject builder</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
In order to help a GObject class developper, one obvious idea is
|
|
||||||
to use some sort of templates for the skeletons. and then run
|
|
||||||
them through a special tool to generate the real C files. <ulink
|
|
||||||
url="http://www.5z.com/jirka/gob.html">GOB</ulink> (or GOB2) is
|
|
||||||
such a tool. It is a preprocessor which can be used to build
|
|
||||||
GObjects with inline C code so that there is no need to edit the
|
|
||||||
generated C code. The syntax is inspired by Java and Yacc or
|
|
||||||
Lex. The implementation is intentionally kept simple: the inline C
|
|
||||||
code provided by the user is not parsed.
|
|
||||||
</para>
|
|
||||||
</chapter>
|
|
||||||
|
|
||||||
<chapter id="tools-ginspector">
|
|
||||||
<title>Graphical inspection of GObjects</title>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Yet another tool that you may find helpful when working with
|
For example, writing GObjects is often seen as a tedious task. It
|
||||||
GObjects is <ulink
|
requires a lot of typing and just doing a copy/paste requires a
|
||||||
url="http://sourceforge.net/projects/g-inspector">G-Inspector</ulink>. It
|
great deal of care. A lot of projects and scripts have been
|
||||||
is able to display GLib/GTK+ objects and their properties.
|
written to generate GObject skeleton form boilerplate code, or
|
||||||
|
even translating higher-level language into plain C.
|
||||||
</para>
|
</para>
|
||||||
</chapter>
|
</partintro>
|
||||||
|
|
||||||
<chapter id="tools-refdb">
|
<chapter id="tools-vala">
|
||||||
<title>Debugging reference count problems</title>
|
<title>Vala</title>
|
||||||
|
<para>
|
||||||
|
From the <ulink url="http://live.gnome.org/Vala">Vala
|
||||||
|
homepage</ulink> itself: <quote>Vala is a new programming language
|
||||||
|
that aims to bring modern programming language features to GNOME
|
||||||
|
developers without imposing any additional runtime requirements
|
||||||
|
and without using a different ABI compared to applications and
|
||||||
|
libraries written in C.</quote>
|
||||||
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The reference counting scheme used by GObject does solve quite
|
The syntax of Vala is similar to C#. The available compiler
|
||||||
a few memory management problems but also introduces new sources of bugs.
|
translates Vala into GObject C code. It can also compile
|
||||||
In large applications, finding the exact spot where the reference count
|
non-GObject C, using plain C API.
|
||||||
of an Object is not properly handled can be very difficult. Hopefully,
|
</para>
|
||||||
there exist a tool named <ulink url="http://refdbg.sf.net/">refdbg</ulink>
|
</chapter>
|
||||||
which can be used to automate the task of tracking down the location
|
|
||||||
of invalid code with regard to reference counting. This application
|
<chapter id="tools-gob">
|
||||||
intercepts the reference counting calls and tries to detect invalid behavior.
|
<title>GObject builder</title>
|
||||||
It supports a filter-rule mechanism to let you trace only the objects you are
|
|
||||||
interested in and it can be used together with GDB.
|
<para>
|
||||||
</para>
|
In order to help a GObject class developper, one obvious idea is
|
||||||
<para>
|
to use some sort of templates for the skeletons. and then run
|
||||||
<indexterm><primary>g_trap_object_ref</primary></indexterm>
|
them through a special tool to generate the real C files. <ulink
|
||||||
Note that if GObject has been compiled with <option>--enable-debug=yes</option>,
|
url="http://www.5z.com/jirka/gob.html">GOB</ulink> (or GOB2) is
|
||||||
it exports a trap variable
|
such a tool. It is a preprocessor which can be used to build
|
||||||
<programlisting>
|
GObjects with inline C code so that there is no need to edit the
|
||||||
|
generated C code. The syntax is inspired by Java and Yacc or
|
||||||
|
Lex. The implementation is intentionally kept simple: the inline C
|
||||||
|
code provided by the user is not parsed.
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="tools-ginspector">
|
||||||
|
<title>Graphical inspection of GObjects</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Yet another tool that you may find helpful when working with
|
||||||
|
GObjects is <ulink
|
||||||
|
url="http://sourceforge.net/projects/g-inspector">G-Inspector</ulink>. It
|
||||||
|
is able to display GLib/GTK+ objects and their properties.
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="tools-refdb">
|
||||||
|
<title>Debugging reference count problems</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The reference counting scheme used by GObject does solve quite
|
||||||
|
a few memory management problems but also introduces new sources of bugs.
|
||||||
|
In large applications, finding the exact spot where the reference count
|
||||||
|
of an Object is not properly handled can be very difficult. Hopefully,
|
||||||
|
there exist a tool named <ulink url="http://refdbg.sf.net/">refdbg</ulink>
|
||||||
|
which can be used to automate the task of tracking down the location
|
||||||
|
of invalid code with regard to reference counting. This application
|
||||||
|
intercepts the reference counting calls and tries to detect invalid behavior.
|
||||||
|
It supports a filter-rule mechanism to let you trace only the objects you are
|
||||||
|
interested in and it can be used together with GDB.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<indexterm><primary>g_trap_object_ref</primary></indexterm>
|
||||||
|
Note that if GObject has been compiled with <option>--enable-debug=yes</option>,
|
||||||
|
it exports a trap variable
|
||||||
|
<programlisting>
|
||||||
static volatile GObject *g_trap_object_ref;
|
static volatile GObject *g_trap_object_ref;
|
||||||
</programlisting>
|
</programlisting>
|
||||||
If set to a non-NULL value, <link linkend="g-object-ref">g_object_ref</link>()
|
If set to a non-NULL value, <link linkend="g-object-ref">g_object_ref</link>()
|
||||||
and <link linkend="g-object-unref">g_object_unref</link>() will be intercepted
|
and <link linkend="g-object-unref">g_object_unref</link>() will be intercepted
|
||||||
when called with that value.
|
when called with that value.
|
||||||
</para>
|
</para>
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
||||||
<chapter id="tools-gtkdoc">
|
<chapter id="tools-gtkdoc">
|
||||||
<title>Writing API docs</title>
|
<title>Writing API docs</title>
|
||||||
|
|
||||||
<para>The API documentation for most of the GLib, GObject, GTK+ and GNOME
|
<para>The API documentation for most of the GLib, GObject, GTK+ and GNOME
|
||||||
libraries is built with a combination of complex tools. Typically, the part of
|
libraries is built with a combination of complex tools. Typically, the part of
|
||||||
the documentation which describes the behavior of each function is extracted
|
the documentation which describes the behavior of each function is extracted
|
||||||
from the specially-formatted source code comments by a tool named gtk-doc which
|
from the specially-formatted source code comments by a tool named gtk-doc which
|
||||||
generates DocBook XML and merges this DocBook XML with a set of master XML
|
generates DocBook XML and merges this DocBook XML with a set of master XML
|
||||||
DocBook files. These XML DocBook files are finally processed with xsltproc
|
DocBook files. These XML DocBook files are finally processed with xsltproc
|
||||||
(a small program part of the libxslt library) to generate the final HTML
|
(a small program part of the libxslt library) to generate the final HTML
|
||||||
output. Other tools can be used to generate PDF output from the source XML.
|
output. Other tools can be used to generate PDF output from the source XML.
|
||||||
The following code excerpt shows what these comments look like.
|
The following code excerpt shows what these comments look like.
|
||||||
<programlisting>
|
<programlisting>
|
||||||
/**
|
/**
|
||||||
* gtk_widget_freeze_child_notify:
|
* gtk_widget_freeze_child_notify:
|
||||||
* @widget: a #GtkWidget
|
* @widget: a #GtkWidget
|
||||||
@ -114,12 +120,13 @@ void
|
|||||||
gtk_widget_freeze_child_notify (GtkWidget *widget)
|
gtk_widget_freeze_child_notify (GtkWidget *widget)
|
||||||
{
|
{
|
||||||
...
|
...
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
Thorough
|
Thorough
|
||||||
<ulink url="http://developer.gnome.org/arch/doc/authors.html">documentation</ulink>
|
<ulink url="http://developer.gnome.org/arch/doc/authors.html">documentation</ulink>
|
||||||
on how to set up and use gtk-doc in your
|
on how to set up and use gtk-doc in your
|
||||||
project is provided on the GNOME developer website.
|
project is provided on the GNOME developer website.
|
||||||
</para>
|
</para>
|
||||||
</chapter>
|
</chapter>
|
||||||
|
</part>
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user