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 |