Note
====

There is now a user manual which can be read using yelp and can be found under
'development'. Please refer to this documentation for up-to-date information.


General
=======

The files to edit manually are generated in the tmpl/ directory.
Remember to use &lt; or &gt; instead of '<' and '>', in these files.

The first part of each function/macro/struct etc. description should be
a very short summary of what it is. This may be used at some point to
produce a short reference guide which can be printed out.

For macros which return a value just like a function, you must manually
add a '@Returns: ' field.

You may want to rearrange the functions/macros etc. to split them into
related sections. To do this rearrange the MODULE-sections.txt
files. You can also add <SUBSECTION> between functions. Currently this just
results in a blank line between them in the synopsis.

If a function or macro has a very long description, you may want the table
of parameters to go somewhere in the middle rather than after the description
as would normally happen. To place the table of parameters in the middle of
the description simple write "<!--PARAMETERS-->" on its own line at the
desired location.


Abbreviations
=============

These are expanded into appropriate DocBook tags, saving a lot of typing.
I've used the Gnome ones (see gnome.txt) but also added '#'.

  Use function() to refer to functions or macros which take arguments.

  Use @param to refer to parameters. (I've also used this when referring to
  parameters of other functions, related to the one being described.)

  Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS.

  Use #symbol to refer to other types of symbol, e.g. structs and enums
    and macros which don't take arguments.



Useful DocBook Tags
===================

These are the DocBook tags which I have used or I think could be useful.
Let me know if I'm doing something wrong!


To link to another section in the GTK docs:

    <link linkend="glib-Hash-Tables">Hash Tables</link>

  The linkend is the SGML id on the top item of the page you want to link to.
  For most pages this is currently the part ("gtk", "gdk", glib") and then
  the page title ("Hash Tables"). For widgets it is just the class name.
  Spaces and underscores are converted to '-' to conform to SGML.


To refer to an external function, e.g. a standard C function:

    <function>...</function> 


To include example code:

    <example>
    <title>Using a GHashTable.</title>
    <programlisting>
      ...
    </programlisting>
    </example>

  or possibly this, for very short code fragments which don't need a title:

    <informalexample>
    <programlisting>
      ...
    </programlisting>
    </informalexample>


To include bulleted lists:

    <itemizedlist>

    <listitem>
    <para>
      ...
    </para>
    </listitem>

    <listitem>
    <para>
      ...
    </para>
    </listitem>

    </itemizedlist>


To include a note which stands out from the text:

    <note>
    <para>
      Make sure you free the data after use.
    </para>
    </note>

To refer to a type:

    <type>unsigned char</type>


To refer to an external structure (not one described in the GTK docs):

    <structname>XFontStruct</structname>


To refer to a field of a structure:

    <structfield>len</structfield>


To refer to a class name, we could possibly use:

    <classname>GtkWidget</classname>

  but you'll probably be using #GtkWidget instead (to automatically create
  a link to the GtkWidget page - see the abbreviations above).


To emphasize text:

    <emphasis>This is important</emphasis>

  but I haven't been using it so far.


For filenames use:

    <filename>c:\windows</filename>