GNOME.org
Appendix 1. Contributing to this document
Prev   

Appendix 1. Contributing to this document

This document is written in Docbook XML. The source files for this document are located in the subdirectory doc/cookbook inside the Clutter source directory.

To maintain some degree of consistency, try to stick to the following broad guidelines about how to write Docbook for this cookbook:

  • If adding a new recipe, use the recipe-template.xml XML file as a basis. You can find it in the <clutter source>/doc/cookbook/ directory.

  • Try to indent your XML sensibly using 2 spaces per level (we're not too strict, but some indentation helps reading the source).

  • Stick to a column width of around 80 characters.

  • Use the <filename> element for file and directory names.

  • Use the <property> element for property names (e.g. GObject properties).

  • Use the <type> element for GObject class names.

  • Use the <constant> element for C defines.

  • Use the <keycap> element for keys, where you are referring to what's actually printed on the key, e.g. Shift. If you're referring to the key some other way (e.g. "the Control key"), don't use <keycap>.

  • Use the <function> element for functions; the style adopted is to give the function name followed by empty brackets, e.g. clutter_actor_set_size().

  • Use the <note> element for asides which might otherwise interrupt the flow of the recipe.

  • To include a video in a recipe, do the following:

    • Make the video as short as is practical, and only include the relevant Clutter window(s).

    • Use Ogg Theora for the encoding.

    • Put the file into the <clutter source>/doc/cookbook/videos directory. The name should be in the format <section>-<recipe>-<identifier>.ogv. For example: animations-fading-fade-out.ogv.

    • Add the name of the file to the in the cookbook's Makefile.am, e.g.

      VIDEO_FILES = \
	videos/animations-fading-fade-out.ogv \
	$(NULL)

      This ensures it gets included in the distribution and installation.

    • Use an <inlinemediaobject> to include it in the Docbook recipe file. It should look something like this:

      <inlinemediaobject>
  <videoobject>
    <videodata fileref="videos/animations-fading-in-then-out.ogv"/>
  </videoobject>
  <alt>
    <para>Video showing an actor fading in then out using
    <type>ClutterState</type></para>
  </alt>
</inlinemediaobject>

      The <alt> tag provides the text which is presented as a link to the file for users whose browser doesn't support HTML 5 embedded video.

  • To include a full code sample in a recipe (which can be compiled into a runnable binary), do the following:

    • Create a C code file in the <clutter source>/doc/cookbook/examples directory. It should be a standalone C application (with a main() etc.). The filename should be in the format <section>-<recipe>.c; you can add an optional identifier to the end if you have more than one example for a recipe.

      If you want to load image files into the application (e.g. to demonstrate something with a texture), you can use the TESTS_DATA_DIR variable in your C code to reuse images in the Clutter tests directory; this will be replaced with <clutter source>/tests/data during the build. For example:

      clutter_texture_set_from_file (CLUTTER_TEXTURE (texture),
                               TESTS_DATA_DIR "/redhand.png",
                               &error);

    • Edit Makefile.am in the cookbook/examples directory so that the build recognises the new code; e.g. if your C source file were called fooing-barring.c you would do:

      noinst_PROGRAMS = \
	textures-reflection	\
	text-shadow		\
	animations-rotating \
	fooing-barring \
	$(NULL)

fooing_barring_SOURCE = fooing-barring.c

      Note

      Note the second line is a new one to tell the build where the source file is for your example.

    • Add a section at the end of your recipe which XIncludes the sample code, e.g.:

      <section>
  <title>Full example</title>

  <example id="fooing-barring-example">
    <title>Fooing with a bar</title>
    <programlisting>
      <xi:include href="examples/fooing-barring.c" parse="text">
        <xi:fallback>a code sample should be here... but isn't</xi:fallback>
      </xi:include>
    </programlisting>
  </example>
</section>
Prev   
3. Creating and animating a custom ClutterDeformEffect Home