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.


*-section.txt
=============

This describes the MODULE-sections.txt file which is used to organise the
documentation output by gtk-doc.

The file is divided into sections. Each section will be output to a separate
file in the templates, which also corresponds to a SGML file, and a file in
the final HTML files. Each section contains a list of function/macro etc.
names, which can be rearranged into the desired order.

The <FILE> ... </FILE> tag is used to specify the file name, without any
suffix. For example, using '<FILE>gnome-config</FILE>' will result in the
section declarations being output in the template file tmpl/gnome-config.sgml,
which will be converted into the DocBook SGML file sgml/gnome-config.sgml.
(The name of the html file is based on the module name and the section title,
or for widgets it is based on the widget name converted to lower case).

The <TITLE> ... </TITLE> tag is used to specify the title of the section.
It is only useful before the templates are initially created, since the title
set in the template file overrides this.

You can group items in the section by using the <SUBSECTION> tag. Currently
it outputs a blank line between subsections in the synopsis section.
You can also use <SUBSECTION Standard> for standard GtkObject declarations
(e.g. the functions like gtk_object_get_type and macros like GTK_OBJECT(),
GTK_IS_OBJECT() etc.) Currently these are left out of the documentation.
You can also use <SUBSECTION Private> for private declarations which will not
be output (Its a handy way to avoid warning messages about unused
declarations.). If your library contains private types which you don't want
to appear in the object hierarchy and the list of implemented or required 
interfaces, add them to a Private subsection.

You can also use <INCLUDE> ... <INCLUDE> to specify the #include files which
are shown in the synopsis sections. It contains a comma-separate list of
#include files, without the angle brackets. If you set it outside of any
sections, it acts for all sections until the end of the file. If you set it
within a section, it only applies to that section.

If a line starts with a '#' it is treated as a comment and ignored.

Example MODULE-sections.txt file:

# This is a comment.
<INCLUDE>gnome.h</INCLUDE>

<SECTION>
<FILE>gnome-dateedit</FILE>
<TITLE>GnomeDateEdit</TITLE>
gnome_date_edit_new
gnome_date_edit_set_time
gnome_date_edit_set_popup_range
gnome_date_edit_get_date
<SUBSECTION Standard>
GNOME_DATE_EDIT
GNOME_IS_DATE_EDIT
gnome_date_edit_get_type
GNOME_DATE_EDIT_CLASS
</SECTION>