doc/authors.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 General
   9 =======
  10
  11 The files to edit manually are generated in the tmpl/ directory.
  12 Remember to use &lt; or &gt; instead of '<' and '>', in these files.
  13
  14 The first part of each function/macro/struct etc. description should be
  15 a very short summary of what it is. This may be used at some point to
  16 produce a short reference guide which can be printed out.
  17
  18 For macros which return a value just like a function, you must manually
  19 add a '@Returns: ' field.
  20
  21 You may want to rearrange the functions/macros etc. to split them into
  22 related sections. To do this rearrange the MODULE-sections.txt
  23 files. You can also add <SUBSECTION> between functions. Currently this just
  24 results in a blank line between them in the synopsis.
  25
  26 If a function or macro has a very long description, you may want the table
  27 of parameters to go somewhere in the middle rather than after the description
  28 as would normally happen. To place the table of parameters in the middle of
  29 the description simple write "<!--PARAMETERS-->" on its own line at the
  30 desired location.
  31
  32
  33 Abbreviations
  34 =============
  35
  36 These are expanded into appropriate DocBook tags, saving a lot of typing.
  37 I've used the Gnome ones (see gnome.txt) but also added '#'.
  38
  39   Use function() to refer to functions or macros which take arguments.
  40
  41   Use @param to refer to parameters. (I've also used this when referring to
  42   parameters of other functions, related to the one being described.)
  43
  44   Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS.
  45
  46   Use #symbol to refer to other types of symbol, e.g. structs and enums
  47     and macros which don't take arguments.
  48
  49
  50
  51 Useful DocBook Tags
  52 ===================
  53
  54 These are the DocBook tags which I have used or I think could be useful.
  55 Let me know if I'm doing something wrong!
  56
  57
  58 To link to another section in the GTK docs:
  59
  60     <link linkend="glib-Hash-Tables">Hash Tables</link>
  61
  62   The linkend is the SGML id on the top item of the page you want to link to.
  63   For most pages this is currently the part ("gtk", "gdk", glib") and then
  64   the page title ("Hash Tables"). For widgets it is just the class name.
  65   Spaces and underscores are converted to '-' to conform to SGML.
  66
  67
  68 To refer to an external function, e.g. a standard C function:
  69
  70     <function>...</function>
  71
  72
  73 To include example code:
  74
  75     <example>
  76     <title>Using a GHashTable.</title>
  77     <programlisting>
  78       ...
  79     </programlisting>
  80     </example>
  81
  82   or possibly this, for very short code fragments which don't need a title:
  83
  84     <informalexample>
  85     <programlisting>
  86       ...
  87     </programlisting>
  88     </informalexample>
  89
  90
  91 To include bulleted lists:
  92
  93     <itemizedlist>
  94
  95     <listitem>
  96     <para>
  97       ...
  98     </para>
  99     </listitem>
 100
 101     <listitem>
 102     <para>
 103       ...
 104     </para>
 105     </listitem>
 106
 107     </itemizedlist>
 108
 109
 110 To include a note which stands out from the text:
 111
 112     <note>
 113     <para>
 114       Make sure you free the data after use.
 115     </para>
 116     </note>
 117
 118 To refer to a type:
 119
 120     <type>unsigned char</type>
 121
 122
 123 To refer to an external structure (not one described in the GTK docs):
 124
 125     <structname>XFontStruct</structname>
 126
 127
 128 To refer to a field of a structure:
 129
 130     <structfield>len</structfield>
 131
 132
 133 To refer to a class name, we could possibly use:
 134
 135     <classname>GtkWidget</classname>
 136
 137   but you'll probably be using #GtkWidget instead (to automatically create
 138   a link to the GtkWidget page - see the abbreviations above).
 139
 140
 141 To emphasize text:
 142
 143     <emphasis>This is important</emphasis>
 144
 145   but I haven't been using it so far.
 146
 147
 148 For filenames use:
 149
 150     <filename>c:\windows</filename>
 151