From e7a7307b493ae07d0563ffbbc33ac836f410bcda Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Thu, 26 Jun 2008 09:02:58 +0000 Subject: [PATCH] 2008-06-26 Emmanuele Bassi * 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. --- doc/reference/ChangeLog | 18 ++ doc/reference/clutter/Makefile.am | 18 +- doc/reference/clutter/building-clutter.xml | 236 ++++++++++++++ ...r-animation.sgml => clutter-animation.xml} | 0 doc/reference/clutter/clutter-docs.sgml | 301 +----------------- doc/reference/clutter/clutter-overview.xml | 53 +++ ...ehaviours.sgml => creating-behaviours.xml} | 0 ...ctor.sgml => subclassing-ClutterActor.xml} | 0 8 files changed, 323 insertions(+), 303 deletions(-) create mode 100644 doc/reference/clutter/building-clutter.xml rename doc/reference/clutter/{clutter-animation.sgml => clutter-animation.xml} (100%) create mode 100644 doc/reference/clutter/clutter-overview.xml rename doc/reference/clutter/{creating-your-own-behaviours.sgml => creating-behaviours.xml} (100%) rename doc/reference/clutter/{subclassing-ClutterActor.sgml => subclassing-ClutterActor.xml} (100%) 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 + + * 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 * 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 @@ + + + + Emmanuele + Bassi + +
+ ebassi@openedhand.com +
+ + + + + Building Clutter + + + +
+ Clutter Dependencies + + + + GLib + + 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. + + + + GObject + + 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. + + + + Pango + + Pango is a library for laying out and rendering + text, with an emphasis on internationalization. + + + + Backend Windowing System Library + + GLX, EGL (1.1), SDL, Cocoa (OS X) and WGL (Windows) + + + + Graphics Rendering + + Open GL (1.4+) ir Open GL ES (1.1) + + + + +
+ +
+ Platform-specific instructions + +
+ Linux + + If you are using Debian or Ubuntu, you can install pre-compiled + binary packages the normal Debian way following the instructions at + + http://debian.o-hand.com/. + + + To build Clutter clutter from sources, get the latest source + archives from + http://www.clutter-project.org/sources/. Once you have extracted + the sources from the archive execute the following commands in the + top-level directory: + + + + $ ./configure + $ make + # make install + + + 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: + + + + --enable-debug=[no/minimum/yes] + + 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. + + + + + + --enable-maintainer-flags=[no/yes] + + Use strict compiler flags; default=no. + + + + + + --enable-gtk-doc + + Use gtk-doc to build documentation; default=no. + + + + + + --enable-manual=[no/yes] + + Build application developers manual; requires jw and + xmlto binaries; default=no. + + + + + + --with-flavour=[glx/eglx/eglnative/sdl] + + Select the Clutter backend; default=glx. + + + + + + + + +
+ +
+ Windows + + The recommended way of building Clutter for Windows is using the + mingw tool + chain. One option is to cross-compile Clutter under Linux -- you + can use the script found in the build/mingw/ + directory to simplify the process (the script takes care of setting + up the necessary dependencies). + + + + 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 + build/msvc_2k5/ directory. In either case, you + will need to first install the required dependencies. + + + 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: + + + --with-flavour=[win32/sdl] + + Select the Clutter backend; default=glx. + + + + + +
+ +
+ OSX + For developing an application with Clutter, the recommended + way of installing it using the MacPorts + project, by simply invoking: + + + $ sudo port install clutter + + + on a terminal, after installing and updating MacPorts. + + For developing Clutter itself, the recommended way of building + it OSX is to use Jhbuild, + following the documentation for building the GTK+ stack as shown + here. + + + Jhbuild depends on SVN, which can be installed on OSX by using + the MacPorts + project. + + + + 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. + + + + The Clutter Quartz backend is built by passing the + --with-flavour=osx 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. + + + + GTK-Doc is not working on OSX, so API reference generation + should also be disabled when building Clutter, by using + the --disable-docs and + --disable-gtk-doc command line argument + to the configure script. + + +
+ +
+ + + diff --git a/doc/reference/clutter/clutter-animation.sgml b/doc/reference/clutter/clutter-animation.xml similarity index 100% rename from doc/reference/clutter/clutter-animation.sgml rename to 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 @@ - - - ]> @@ -40,297 +37,9 @@ - - Clutter Overview - - - - - - Clutter is a GObject based library for creating fast, visually - rich, graphical user interfaces. - - - - - - Clutter works by manipulating a scene-graph of 2D surfaces, or 'actors', - inside a 3D space. - - - - - #ClutterActor is the base class for such surfaces. All - #ClutterActors 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. - - - - - Subclasses of #ClutterActor include #ClutterStage, #ClutterTexture, - #ClutterLabel, #ClutterRectangle, #ClutterEntry and - #ClutterGroup. #ClutterActors are added to a parent, transformed - and then made visible. - - - - - #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. - - - - - #ClutterTimelines 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. - - - - - 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. - - - - - - - - Building Clutter - - - -
- Clutter Dependencies - - - - GLib - - 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. - - - - GObject - - 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. - - - - Pango - - Pango is a library for laying out and rendering - text, with an emphasis on internationalization. - - - - GDK-Pixbuf - - GDK-Pixbuf is a library for loading and manipulating - various image file formats. - - Backend Windowing System Library - - GLX, EGL (1.1), SDL, Cocoa (OS X) and WGL (Windows) - - Graphics Rendering - - Open GL (1.2+) ir Open GL ES (1.1) - - - - -
- -
- Platform-specific instructions - -
- Linux - - If you are using Debian or Ubuntu, you can install pre-compiled - binary packages the normal Debian way following the instructions at - - http://debian.o-hand.com/. - - - To build Clutter clutter from sources, get the latest source - archives from - http://www.clutter-project.org/sources/. Once you have extracted - the sources from the archive execute the following commands in the - top-level directory: - - - - ./configure - make - make install - - - 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: - - - - --enable-debug=[no/minimum/yes] - - 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. - - - - - - --enable-maintainer-flags=[no/yes] - - Use strict compiler flags; default=no. - - - - - - --enable-gtk-doc - - Use gtk-doc to build documentation; default=no. - - - - - - --enable-manual=[no/yes] - - Build application developers manual; requires jw and - xmlto binaries; default=no. - - - - - - --with-flavour=[glx/eglx/eglnative/sdl] - - Select the Clutter backend; default=glx. - - - - - - - -
- -
- Windows - - The recommended way of building Clutter for Windows is using the - mingw tool - chain. One option is to cross-compile Clutter under Linux -- you - can use the script found in the build/mingw/ - directory to simplify the process (the script takes care of setting - up the necessary dependencies). - - - - 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 - build/msvc_2k5/ directory. In either case, you - will need to first install the required dependencies. - - - 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: - - - --with-flavour=[win32/sdl] - - Select the Clutter backend; default=glx. - - - - - -
- -
- OSX - For developing an application with Clutter, the recommended - way of installing it using the MacPorts - project, by simply invoking: - - - $ sudo port install clutter - - - on a terminal, after installing and updating MacPorts. - - For developing Clutter itself, the recommended way of building - it OSX is to use Jhbuild, - following the documentation for building the GTK+ stack as shown - here. - - - Jhbuild depends on SVN, which can be installed on OSX by using - the MacPorts - project. - - - - 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. - - - - The Clutter Quartz backend is built by passing the - --with-flavour=osx 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. - - - - GTK-Doc is not working on OSX, so API reference generation - should also be disabled when building Clutter, by using - the --disable-docs and - --disable-gtk-doc command line argument - to the configure script. - - -
-
- - - + + Clutter Core Reference @@ -453,11 +162,11 @@ developing with Clutter. - &clutter-SubclassingActor; + - &clutter-animation; + - &creating-your-own-behaviours; + 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 @@ + + + + Emmanuele + Bassi + +
+ ebassi@openedhand.com +
+ + + + + Overview + + + + Clutter is a GObject based library for creating fast, visually + rich, graphical user interfaces. + + Clutter works by manipulating a scene-graph of 2D surfaces, or + 'actors', inside a 3D space. + + #ClutterActor is the base class for such surfaces. All + #ClutterActors 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. + + Subclasses of #ClutterActor include #ClutterStage, #ClutterTexture, + #ClutterLabel, #ClutterRectangle, #ClutterEntry and + #ClutterGroup. #ClutterActors are added to a parent, transformed + and then made visible. + + #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. + + #ClutterTimelines 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. + + 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 fixed point math utilities. + + + + diff --git a/doc/reference/clutter/creating-your-own-behaviours.sgml b/doc/reference/clutter/creating-behaviours.xml similarity index 100% rename from doc/reference/clutter/creating-your-own-behaviours.sgml rename to doc/reference/clutter/creating-behaviours.xml diff --git a/doc/reference/clutter/subclassing-ClutterActor.sgml b/doc/reference/clutter/subclassing-ClutterActor.xml similarity index 100% rename from doc/reference/clutter/subclassing-ClutterActor.sgml rename to doc/reference/clutter/subclassing-ClutterActor.xml