mutter/doc/cookbook/introduction.xml

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY appurl "http://www.clutter-project.org">
<!ENTITY docurl "http://docs.clutter-project.org/docs/clutter-cookbook">
]>

<chapter id="introduction">
  <title>Preface</title>

  <epigraph>
    <attribution>The Perl Cookbook</attribution>
    <para>Let me show you that easy way, so others may easily follow.</para>
  </epigraph>

  <para>There is a wonderful simile in the preface of the <emphasis>Perl
  Cookbook</emphasis>: approaching a programming problem is oftentimes
  similar to balancing Columbus's egg. The initial difficulties of dealing
  with, and more importantly solving, problems in the software engineering
  field sometimes can only be overcome if somebody shows you how to use a
  new tool. This is true for programming languages but also for programming
  libraries.</para>

  <para>This book has been written to try and give you a reference on
  how to solve common issues that you might have to face when using
  the Clutter toolkit.</para>

  <para>This book is not meant to be a replacement for the Clutter API
  reference, even though there will be descriptions of how Clutter works
  and how its API looks like. We will require knowledge of the Clutter API,
  but we will also point out where to find more information on the API that
  examples have used.</para>

  <para>Indeed, this book should be used as a companion to the API reference,
  expanding its examples and showing how to achieve a specific result.</para>

  <para>This is not a book for learning Clutter. This is also not a book
  for learning C, or GObject or even GUI development.</para>

  <para>Above all, this is a book for learning <emphasis>more</emphasis>
  about Clutter, and about how to use it in the most efficient and easiest
  way. It is meant to help you move past the basic usage of Clutter.</para>

  <para>This book is divided into chapters. Each chapter is dedicated to
  a specific class, like ClutterTexture, or a specific area, like animations.
  Each chapter starts with a short introduction, followed by different
  <emphasis>recipes</emphasis>. Each recipe starts with a problem, or a short
  statement describing what we want to achieve; a solution, containing the
  source code; and a discussion section, where the code is explained, where
  alternative approaches might be useful, and where caveats and references to
  the Clutter API for further studying can be found.</para>

  <para>This book, in the cookbook spirit, can be accessed mostly at
  random.</para>

  <section>
    <title>About Clutter</title>

    <para>Clutter is an free and open source software library for creating
    portable, dynamic, compelling and fast graphical user interfaces.</para>

    <para>Clutter uses OpenGL (and, optionally, OpenGL ES on mobile and
    embedded platforms) for rendering the user interface elements, but
    at the same time it exposes an application program interface that hides
    the underlying complexity of the OpenGL state machine from the
    developer.</para>

    <para>The program interface of Clutter is intended to be easy to use,
    efficient, flexible and as self-documenting as possible.</para>
  </section>

  <section>
    <title>About this document</title>

    <para>This document is available in various formats like HTML, and
    PDF.</para>

    <para>The latest version is always available at
    <ulink url="&docurl;">&docurl;</ulink>.</para>

    <para>To contribute to this document, see the
    <link linkend="contributing">Contributing</link> appendix.</para>

    <section>
      <title>Compiling the examples</title>

      <para>This document comes with full examples, usually stored
      on disk in <filename><emphasis>datadir</emphasis>/clutter-1.0/cookbook/examples</filename>
      directory.</para>

      <para>Each example can be compiled using:</para>

      <informalexample>
        <programlisting>
cc \
  `pkg-config --cflags clutter-1.0` \
  -o <emphasis>example</emphasis> <emphasis>example</emphasis>.c \
  `pkg-config --libs clutter-1.0`
        </programlisting>
      </informalexample>

      <para>substituting the <emphasis>example</emphasis> with in the
      line above with the name of the example.</para>

    </section>

  </section>

  <section>
    <title>Acknowledgments</title>

    <para>This book has been written taking the inspiration from the Perl
    Cookbook, authored by Tom Christiansen and Nathan Torkington.</para>

    <para>This book would not have been possible without the existence of
    the Clutter library itself, and without the help and contributions of
    all the people that have been working on it every day.</para>

    <section>
      <title>Acknowledgments from Emmanuele</title>

      <para>To Matthew, for starting the flame. To Robert and Neil, for
      keeping it ablaze.</para>

      <para>To Marta, for her love and patience.</para>
    </section>

    <section>
      <title>Acknowledgements from Elliot</title>
    </section>

  </section>

  <section>
    <title>Where to get Clutter</title>

    <para>You can obtain the Clutter source code ready for compilation
    from <ulink url="&appurl;">&appurl;</ulink>.</para>

    <para>Clutter is also available on all major GNU/Linux distributions,
    in various package formats.</para>

    <para>On OSX, Clutter is available with both Fink and MacPorts.</para>

    <para>Binaries for Microsoft Windows are also available.</para>
  </section>

</chapter>