diff options
author | Emmanuele Bassi <ebassi@openedhand.com> | 2008-06-26 09:02:58 +0000 |
---|---|---|
committer | Emmanuele Bassi <ebassi@openedhand.com> | 2008-06-26 09:02:58 +0000 |
commit | e7a7307b493ae07d0563ffbbc33ac836f410bcda (patch) | |
tree | 79b5a7c1096271b5bf292e3a4420d822acbaca95 /doc/reference | |
parent | 93fda926514c91139790d083dafff49a64f11b4e (diff) | |
download | clutter-e7a7307b493ae07d0563ffbbc33ac836f410bcda.tar.gz |
2008-06-26 Emmanuele Bassi <ebassi@openedhand.com>
* clutter/clutter-overview.xml: Split the overview into its own
file, so we gtk-doc can linkify all class names.
* clutter/building-clutter.xml: Split the building instructions
into its own file, for better maintainability.
* clutter/clutter-animation.xml:
* clutter/creating-behaviours.xml:
* clutter/subclassing-ClutterActor.xml: Rename from SGML to XML;
these were not SGML files anyway, but templates.
* clutter/clutter-docs.sgml: Use XInclude instead of the ugly
entities hack.
* clutter/Makefile.am: Update the build.
Diffstat (limited to 'doc/reference')
-rw-r--r-- | doc/reference/ChangeLog | 18 | ||||
-rw-r--r-- | doc/reference/clutter/Makefile.am | 18 | ||||
-rw-r--r-- | doc/reference/clutter/building-clutter.xml | 236 | ||||
-rw-r--r-- | doc/reference/clutter/clutter-animation.xml (renamed from doc/reference/clutter/clutter-animation.sgml) | 0 | ||||
-rw-r--r-- | doc/reference/clutter/clutter-docs.sgml | 301 | ||||
-rw-r--r-- | doc/reference/clutter/clutter-overview.xml | 53 | ||||
-rw-r--r-- | doc/reference/clutter/creating-behaviours.xml (renamed from doc/reference/clutter/creating-your-own-behaviours.sgml) | 0 | ||||
-rw-r--r-- | doc/reference/clutter/subclassing-ClutterActor.xml (renamed from doc/reference/clutter/subclassing-ClutterActor.sgml) | 0 |
8 files changed, 323 insertions, 303 deletions
diff --git a/doc/reference/ChangeLog b/doc/reference/ChangeLog index 723bceb5e..176a3649d 100644 --- a/doc/reference/ChangeLog +++ b/doc/reference/ChangeLog @@ -1,3 +1,21 @@ +2008-06-26 Emmanuele Bassi <ebassi@openedhand.com> + + * clutter/clutter-overview.xml: Split the overview into its own + file, so we gtk-doc can linkify all class names. + + * clutter/building-clutter.xml: Split the building instructions + into its own file, for better maintainability. + + * clutter/clutter-animation.xml: + * clutter/creating-behaviours.xml: + * clutter/subclassing-ClutterActor.xml: Rename from SGML to XML; + these were not SGML files anyway, but templates. + + * clutter/clutter-docs.sgml: Use XInclude instead of the ugly + entities hack. + + * clutter/Makefile.am: Update the build. + 2008-06-25 Emmanuele Bassi <ebassi@openedhand.com> * clutter/clutter-sections.txt: Add missing symbols. diff --git a/doc/reference/clutter/Makefile.am b/doc/reference/clutter/Makefile.am index e4681203a..176160b48 100644 --- a/doc/reference/clutter/Makefile.am +++ b/doc/reference/clutter/Makefile.am @@ -97,18 +97,22 @@ HTML_IMAGES=\ # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE). # e.g. content_files=running.sgml building.sgml changes-2.0.sgml content_files= \ - subclassing-ClutterActor.sgml \ - clutter-animation.sgml \ - creating-your-own-behaviours.sgml \ - version.xml + version.xml \ + subclassing-ClutterActor.xml \ + clutter-animation.xml \ + creating-behaviours.xml \ + clutter-overview.xml \ + building-clutter.xml # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded # These files must be listed here *and* in content_files # e.g. expand_content_files=running.sgml expand_content_files= \ - subclassing-ClutterActor.sgml \ - clutter-animation.sgml \ - creating-your-own-behaviours.sgml + subclassing-ClutterActor.xml \ + clutter-animation.xml \ + creating-behaviours.xml \ + clutter-overview.xml \ + building-clutter.xml # CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library. # Only needed if you are using gtkdoc-scangobj to dynamically query widget diff --git a/doc/reference/clutter/building-clutter.xml b/doc/reference/clutter/building-clutter.xml new file mode 100644 index 000000000..38c814ac4 --- /dev/null +++ b/doc/reference/clutter/building-clutter.xml @@ -0,0 +1,236 @@ +<part id="building-clutter"> + <partinfo> + <author> + <firstname>Emmanuele</firstname> + <surname>Bassi</surname> + <affiliation> + <address> + <email>ebassi@openedhand.com</email> + </address> + </affiliation> + </author> + </partinfo> + + <title>Building Clutter</title> + + <partintro> + + <section id='dependencies'> + <title>Clutter Dependencies</title> + + <variablelist> + <varlistentry> + <term>GLib</term> + <listitem> + <para>A general-purpose utility library, not specific to + graphical user interfaces. GLib provides many useful data + types, macros, type conversions, string utilities, file + utilities, a main loop abstraction, and so on.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>GObject</term> + <listitem> + <para>The GLib Object System provides the required + implementations of a flexible, extensible and intentionally + easy to map (into other languages) object-oriented framework + for C.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Pango</term> + <listitem> + <para>Pango is a library for laying out and rendering + text, with an emphasis on internationalization.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Backend Windowing System Library</term> + <listitem> + <para>GLX, EGL (1.1), SDL, Cocoa (OS X) and WGL (Windows)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Graphics Rendering </term> + <listitem> + <para>Open GL (1.4+) ir Open GL ES (1.1) </para> + </listitem> + </varlistentry> + </variablelist> + + </section> + + <section id='building-instructions'> + <title>Platform-specific instructions</title> + + <section id='building-linux'> + <title>Linux</title> + + <para>If you are using Debian or Ubuntu, you can install pre-compiled + binary packages the normal Debian way following the instructions at + <ulink type="http" url="http://debian.o-hand.com/"> + http://debian.o-hand.com/</ulink>. + </para> + + <para>To build Clutter clutter from sources, get the latest source + archives from <ulink type="http" + url="http://www.clutter-project.org/sources/"> + http://www.clutter-project.org/sources/</ulink>. Once you have extracted + the sources from the archive execute the following commands in the + top-level directory: + </para> + + <literallayout> + $ ./configure + $ make + # make install + </literallayout> + + <para>You can configure the build with number of additional arguments + passed to the configure script, the full list of which can be obtained + by running ./configure --help. The following arguments are specific to + Clutter: + + <variablelist> + <varlistentry> + <term>--enable-debug=[no/minimum/yes]</term> + <listitem> + <para>Turns on debugging. Possible values are: yes - all + glib asserts, checks and runtime clutter verbose messages; + minimum - just glib cast checks and runtime clutter verbose + messagaes; no - no glib asserts or checks and no runtime + clutter verbose messages; default=yes. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>--enable-maintainer-flags=[no/yes]</term> + <listitem> + <para>Use strict compiler flags; default=no. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>--enable-gtk-doc</term> + <listitem> + <para>Use gtk-doc to build documentation; default=no. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>--enable-manual=[no/yes]</term> + <listitem> + <para>Build application developers manual; requires jw and + xmlto binaries; default=no. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>--with-flavour=[glx/eglx/eglnative/sdl]</term> + <listitem> + <para>Select the Clutter backend; default=glx. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </para> + + </section> + + <section id='building-windows'> + <title>Windows</title> + <para> + The recommended way of building Clutter for Windows is using the + <ulink type="http" url="http://www.mingw.org/">mingw</ulink> tool + chain. One option is to cross-compile Clutter under Linux -- you + can use the script found in the <filename>build/mingw/</filename> + directory to simplify the process (the script takes care of setting + up the necessary dependencies). + </para> + + <para> + If you wish to build Clutter using mingw direcly under Windows, you + can do so the normal *nix way (described above) using the mingw + POSIX shell. Should you prefer to use Microsoft Visual Studio, a + project file for MSVC 2005 is located in the + <filename>build/msvc_2k5/</filename> directory. In either case, you + will need to first install the required dependencies. + </para> + <para> + There are currently two backends that are supported on + Windows. One uses the Win32 and WGL APIs directly and the + other is built on top of SDL. You must choose one of the + backends when running the configure script using the + following argument: + <variablelist> + <varlistentry> + <term>--with-flavour=[win32/sdl]</term> + <listitem> + <para>Select the Clutter backend; default=glx. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </section> + + <section id='building-osx'> + <title>OSX</title> + <para>For developing an application with Clutter, the recommended + way of installing it using the <ulink href="http://www.macports.org/">MacPorts</ulink> + project, by simply invoking:</para> + + <informalexample><programlisting> + $ sudo port install clutter + </programlisting></informalexample> + + <para>on a terminal, after installing and updating MacPorts.</para> + + <para>For developing Clutter itself, the recommended way of building + it OSX is to use <ulink href="http://live.gnome.org/Jhbuild">Jhbuild</ulink>, + following the documentation for building the GTK+ stack as shown + <ulink href="http://developer.imendio.com/projects/gtk-macosx/build-instructions">here</ulink>.</para> + + <para> + Jhbuild depends on SVN, which can be installed on OSX by using + the <ulink href="http://www.macports.org/">MacPorts</ulink> + project. + </para> + + <para> + XCode should also be installed, either from the OSX installation + disk or downloading it from the Apple website. It is recommended + to also install the X11 development files, even though Clutter + does not strictly depend on them. + </para> + + <para> + The Clutter Quartz backend is built by passing the + <literal>--with-flavour=osx</literal> command line argument + to the configure script. If not passed, the GLX backend will + be built. By default, the Quartz backend depends on CoreGraphics + in order to load images into textures, but it can also depend + on GDK-Pixbuf or an internal, highly experimental PNG and JPEG + loader. + </para> + + <para> + GTK-Doc is not working on OSX, so API reference generation + should also be disabled when building Clutter, by using + the <literal>--disable-docs</literal> and + <literal>--disable-gtk-doc</literal> command line argument + to the configure script. + </para> + + </section> + + </section> + + </partintro> +</part> diff --git a/doc/reference/clutter/clutter-animation.sgml b/doc/reference/clutter/clutter-animation.xml index 1e8515d64..1e8515d64 100644 --- a/doc/reference/clutter/clutter-animation.sgml +++ b/doc/reference/clutter/clutter-animation.xml diff --git a/doc/reference/clutter/clutter-docs.sgml b/doc/reference/clutter/clutter-docs.sgml index c6ab98f96..bd7531838 100644 --- a/doc/reference/clutter/clutter-docs.sgml +++ b/doc/reference/clutter/clutter-docs.sgml @@ -2,9 +2,6 @@ <!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 clutter-SubclassingActor SYSTEM "xml/subclassing-ClutterActor.sgml"> -<!ENTITY clutter-animation SYSTEM "xml/clutter-animation.sgml"> -<!ENTITY creating-your-own-behaviours SYSTEM "xml/creating-your-own-behaviours.sgml"> ]> <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> @@ -40,297 +37,9 @@ </legalnotice> </bookinfo> - <part id="clutter"> - <title>Clutter Overview</title> - - <partintro> - - <para> - - Clutter is a GObject based library for creating fast, visually - rich, graphical user interfaces. - - </para> - - <para> - - Clutter works by manipulating a scene-graph of 2D surfaces, or 'actors', - inside a 3D space. - - </para> - <para> - - #ClutterActor is the base class for such surfaces. All - #ClutterActor<!-- -->s can be positioned, scaled and rotated in 3D space. - In addition, other properties can be set, such as 2D clipping, children and - opacity. Tranforms applied to a parent actor also apply to any children. - Actors are also able to receive events. - - </para> - <para> - - Subclasses of #ClutterActor include #ClutterStage, #ClutterTexture, - #ClutterLabel, #ClutterRectangle, #ClutterEntry and - #ClutterGroup. #ClutterActor<!-- -->s are added to a parent, transformed - and then made visible. - - </para> - <para> - - #ClutterStage is the top level #ClutterActor - it's the representation - of a window, or framebuffer. It is created automatically when Clutter is - initialised. #ClutterStage is a #ClutterGroup, a class - implementing the #ClutterCointainer interface. Clutter currently - only supports a single stage. - - </para> - <para> - - #ClutterTimeline<!-- -->s provide the basis for Clutter's animation - utilities. Multiple timelines can be synchronised using #ClutterScore, - and #ClutterBehaviour and #ClutterEffect allow for the creation of - animation effects such as transitions. - - </para> - <para> - - Clutter further contains a number of utilities, including; - #ClutterScript - for loading 'UI definition' files formatted in - JSON, #ClutterShader - a class for applying GPU shaders to actors, - #ClutterModel - a utility class for MVC list type implementations - and #ClutterFixed - fixed point math utilities. - - </para> - - </partintro> - </part> - - <part id="clutterbuilding"> - <title>Building Clutter</title> - - <partintro> - - <section id='dependencies'> - <title>Clutter Dependencies</title> - - <variablelist> - <varlistentry> - <term>GLib</term> - <listitem> - <para>A general-purpose utility library, not specific to - graphical user interfaces. GLib provides many useful data - types, macros, type conversions, string utilities, file - utilities, a main loop abstraction, and so on.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>GObject</term> - <listitem> - <para>The GLib Object System provides the required - implementations of a flexible, extensible and intentionally - easy to map (into other languages) object-oriented framework - for C.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>Pango</term> - <listitem> - <para>Pango is a library for laying out and rendering - text, with an emphasis on internationalization.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>GDK-Pixbuf</term> - <listitem> - <para>GDK-Pixbuf is a library for loading and manipulating - various image file formats.</para> - </listitem> - <term>Backend Windowing System Library</term> - <listitem> - <para>GLX, EGL (1.1), SDL, Cocoa (OS X) and WGL (Windows)</para> - </listitem> - <term>Graphics Rendering </term> - <listitem> - <para>Open GL (1.2+) ir Open GL ES (1.1) </para> - </listitem> - </varlistentry> - </variablelist> - - </section> - - <section id='building-instructions'> - <title>Platform-specific instructions</title> - - <section id='building-linux'> - <title>Linux</title> - - <para>If you are using Debian or Ubuntu, you can install pre-compiled - binary packages the normal Debian way following the instructions at - <ulink type="http" url="http://debian.o-hand.com/"> - http://debian.o-hand.com/</ulink>. - </para> - - <para>To build Clutter clutter from sources, get the latest source - archives from <ulink type="http" - url="http://www.clutter-project.org/sources/"> - http://www.clutter-project.org/sources/</ulink>. Once you have extracted - the sources from the archive execute the following commands in the - top-level directory: - </para> - - <literallayout> - ./configure - make - make install - </literallayout> - - <para>You can configure the build with number of additional arguments - passed to the configure script, the full list of which can be obtained - by running ./configure --help. The following arguments are specific to - Clutter: - - <variablelist> - <varlistentry> - <term>--enable-debug=[no/minimum/yes]</term> - <listitem> - <para>Turns on debugging. Possible values are: yes - all - glib asserts, checks and runtime clutter verbose messages; - minimum - just glib cast checks and runtime clutter verbose - messagaes; no - no glib asserts or checks and no runtime - clutter verbose messages; default=yes. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>--enable-maintainer-flags=[no/yes]</term> - <listitem> - <para>Use strict compiler flags; default=no. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>--enable-gtk-doc</term> - <listitem> - <para>Use gtk-doc to build documentation; default=no. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>--enable-manual=[no/yes]</term> - <listitem> - <para>Build application developers manual; requires jw and - xmlto binaries; default=no. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>--with-flavour=[glx/eglx/eglnative/sdl]</term> - <listitem> - <para>Select the Clutter backend; default=glx. - </para> - </listitem> - </varlistentry> - </variablelist> - - </para> - - </section> - - <section id='building-windows'> - <title>Windows</title> - <para> - The recommended way of building Clutter for Windows is using the - <ulink type="http" url="http://www.mingw.org/">mingw</ulink> tool - chain. One option is to cross-compile Clutter under Linux -- you - can use the script found in the <filename>build/mingw/</filename> - directory to simplify the process (the script takes care of setting - up the necessary dependencies). - </para> - - <para> - If you wish to build Clutter using mingw direcly under Windows, you - can do so the normal *nix way (described above) using the mingw - POSIX shell. Should you prefer to use Microsoft Visual Studio, a - project file for MSVC 2005 is located in the - <filename>build/msvc_2k5/</filename> directory. In either case, you - will need to first install the required dependencies. - </para> - <para> - There are currently two backends that are supported on - Windows. One uses the Win32 and WGL APIs directly and the - other is built on top of SDL. You must choose one of the - backends when running the configure script using the - following argument: - <variablelist> - <varlistentry> - <term>--with-flavour=[win32/sdl]</term> - <listitem> - <para>Select the Clutter backend; default=glx. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </section> - - <section id='building-osx'> - <title>OSX</title> - <para>For developing an application with Clutter, the recommended - way of installing it using the <ulink href="http://www.macports.org/">MacPorts</ulink> - project, by simply invoking:</para> - - <informalexample><programlisting> - $ sudo port install clutter - </programlisting></informalexample> - - <para>on a terminal, after installing and updating MacPorts.</para> - - <para>For developing Clutter itself, the recommended way of building - it OSX is to use <ulink href="http://live.gnome.org/Jhbuild">Jhbuild</ulink>, - following the documentation for building the GTK+ stack as shown - <ulink href="http://developer.imendio.com/projects/gtk-macosx/build-instructions">here</ulink>.</para> - - <para> - Jhbuild depends on SVN, which can be installed on OSX by using - the <ulink href="http://www.macports.org/">MacPorts</ulink> - project. - </para> - - <para> - XCode should also be installed, either from the OSX installation - disk or downloading it from the Apple website. It is recommended - to also install the X11 development files, even though Clutter - does not strictly depend on them. - </para> - - <para> - The Clutter Quartz backend is built by passing the - <literal>--with-flavour=osx</literal> command line argument - to the configure script. If not passed, the GLX backend will - be built. By default, the Quartz backend depends on CoreGraphics - in order to load images into textures, but it can also depend - on GDK-Pixbuf or an internal, highly experimental PNG and JPEG - loader. - </para> - - <para> - GTK-Doc is not working on OSX, so API reference generation - should also be disabled when building Clutter, by using - the <literal>--disable-docs</literal> and - <literal>--disable-gtk-doc</literal> command line argument - to the configure script. - </para> - - </section> - </section> - - </partintro> - </part> + <xi:include href="xml/clutter-overview.xml"/> + <xi:include href="xml/building-clutter.xml"/> <part id="clutterbase"> <title>Clutter Core Reference</title> @@ -453,11 +162,11 @@ developing with Clutter.</para> </partintro> - &clutter-SubclassingActor; + <xi:include href="subclassing-ClutterActor.xml"/> - &clutter-animation; + <xi:include href="clutter-animation.xml"/> - &creating-your-own-behaviours; + <xi:include href="creating-behaviours.xml"/> </part> diff --git a/doc/reference/clutter/clutter-overview.xml b/doc/reference/clutter/clutter-overview.xml new file mode 100644 index 000000000..a015fd22a --- /dev/null +++ b/doc/reference/clutter/clutter-overview.xml @@ -0,0 +1,53 @@ +<part id="clutter-overview"> + <partinfo> + <author> + <firstname>Emmanuele</firstname> + <surname>Bassi</surname> + <affiliation> + <address> + <email>ebassi@openedhand.com</email> + </address> + </affiliation> + </author> + </partinfo> + + <title>Overview</title> + + <partintro> + + <para>Clutter is a GObject based library for creating fast, visually + rich, graphical user interfaces.</para> + + <para>Clutter works by manipulating a scene-graph of 2D surfaces, or + 'actors', inside a 3D space.</para> + + <para>#ClutterActor is the base class for such surfaces. All + #ClutterActor<!-- -->s can be positioned, scaled and rotated in 3D space. + In addition, other properties can be set, such as 2D clipping, children and + opacity. Tranforms applied to a parent actor also apply to any children. + Actors are also able to receive events.</para> + + <para>Subclasses of #ClutterActor include #ClutterStage, #ClutterTexture, + #ClutterLabel, #ClutterRectangle, #ClutterEntry and + #ClutterGroup. #ClutterActor<!-- -->s are added to a parent, transformed + and then made visible.</para> + + <para>#ClutterStage is the top level #ClutterActor - it's the + representation of a window, or framebuffer. It is created automatically + when Clutter is initialised. #ClutterStage is a #ClutterGroup, a class + implementing the #ClutterCointainer interface.</para> + + <para>#ClutterTimeline<!-- -->s provide the basis for Clutter's animation + utilities. Multiple timelines can be synchronised using #ClutterScore, + and #ClutterBehaviour and #ClutterEffect allow for the creation of + animation effects such as transitions.</para> + + <para>Clutter further contains a number of utilities, including; + #ClutterScript - for loading 'UI definition' files formatted in + <ulink type="http" url="http://json.org">JSON</ulink>, #ClutterShader - a + class for applying GPU shaders to actors, #ClutterModel - a utility class + for MVC list type implementations, and fixed point math utilities.</para> + + </partintro> + +</part> diff --git a/doc/reference/clutter/creating-your-own-behaviours.sgml b/doc/reference/clutter/creating-behaviours.xml index 53ee8e2a0..53ee8e2a0 100644 --- a/doc/reference/clutter/creating-your-own-behaviours.sgml +++ b/doc/reference/clutter/creating-behaviours.xml diff --git a/doc/reference/clutter/subclassing-ClutterActor.sgml b/doc/reference/clutter/subclassing-ClutterActor.xml index 50634fbaa..50634fbaa 100644 --- a/doc/reference/clutter/subclassing-ClutterActor.sgml +++ b/doc/reference/clutter/subclassing-ClutterActor.xml |