doc/sections-file.txt

   1 Note
   2 ====
   3
   4 There is now a user manual which can be read using yelp and can be found under
   5 'development'. Please refer to this documentation for up-to-date information.
   6
   7
   8 *-section.txt
   9 =============
  10
  11 This describes the MODULE-sections.txt file which is used to organise the
  12 documentation output by gtk-doc.
  13
  14 The file is divided into sections. Each section will be output to a separate
  15 file in the templates, which also corresponds to a SGML file, and a file in
  16 the final HTML files. Each section contains a list of function/macro etc.
  17 names, which can be rearranged into the desired order.
  18
  19 The <FILE> ... </FILE> tag is used to specify the file name, without any
  20 suffix. For example, using '<FILE>gnome-config</FILE>' will result in the
  21 section declarations being output in the template file tmpl/gnome-config.sgml,
  22 which will be converted into the DocBook SGML file sgml/gnome-config.sgml.
  23 (The name of the html file is based on the module name and the section title,
  24 or for widgets it is based on the widget name converted to lower case).
  25
  26 The <TITLE> ... </TITLE> tag is used to specify the title of the section.
  27 It is only useful before the templates are initially created, since the title
  28 set in the template file overrides this.
  29
  30 You can group items in the section by using the <SUBSECTION> tag. Currently
  31 it outputs a blank line between subsections in the synopsis section.
  32 You can also use <SUBSECTION Standard> for standard GtkObject declarations
  33 (e.g. the functions like gtk_object_get_type and macros like GTK_OBJECT(),
  34 GTK_IS_OBJECT() etc.) Currently these are left out of the documentation.
  35 You can also use <SUBSECTION Private> for private declarations which will not
  36 be output (Its a handy way to avoid warning messages about unused
  37 declarations.). If your library contains private types which you don't want
  38 to appear in the object hierarchy and the list of implemented or required
  39 interfaces, add them to a Private subsection.
  40
  41 You can also use <INCLUDE> ... <INCLUDE> to specify the #include files which
  42 are shown in the synopsis sections. It contains a comma-separate list of
  43 #include files, without the angle brackets. If you set it outside of any
  44 sections, it acts for all sections until the end of the file. If you set it
  45 within a section, it only applies to that section.
  46
  47 If a line starts with a '#' it is treated as a comment and ignored.
  48
  49 Example MODULE-sections.txt file:
  50
  51 # This is a comment.
  52 <INCLUDE>gnome.h</INCLUDE>
  53
  54 <SECTION>
  55 <FILE>gnome-dateedit</FILE>
  56 <TITLE>GnomeDateEdit</TITLE>
  57 gnome_date_edit_new
  58 gnome_date_edit_set_time
  59 gnome_date_edit_set_popup_range
  60 gnome_date_edit_get_date
  61 <SUBSECTION Standard>
  62 GNOME_DATE_EDIT
  63 GNOME_IS_DATE_EDIT
  64 gnome_date_edit_get_type
  65 GNOME_DATE_EDIT_CLASS
  66 </SECTION>