The manual sources consist of over 300 single files, and so chances are high that there are white spots in the docs. If you already have noticed what's missing when browsing the manual, go ahead and fill the white spot which interests you at most. If you don't know any empty places, search the manual files for FIXME and TODO comments and start there.

As you might have noticed already, the manual sources are in the manual/ directory, which contains folders for each language. Have a look at manual/en/reference/ - you will find folders for gtk, gdk. Every class has it's own xml file in one of the folders - that allows multiple people to work on different parts of manual at the same time, and it allows slower machines to open a manual file.

You probably won't need to add any files, because the skeleton for the class docs should exist at least. If you have to add a new file, be sure it's registered in manual/reference.xml - it won't be included in the manual otherwise.

Class images have its own directory, images/. The directory structure is about the same as the one for the xml files; for example the image for GtkAboutDialog is at images/reference/gtk/gtkaboutdialog.png. If you create new images, make sure they are small. A file with 30kb is too expensive, if you add all the image sizes up. Also make sure you use .png files, and reduce the color palette to a fixed size to keep file size low.

Executable examples have their own directory examples/ with a structure similar to the images and the xml doc files, with the exception that every single class has its own directory. The file are named after the function/method they give an example for: set_logo() function of GtkAboutDialog has to go into examples/reference/gtk/gtkaboutdialog/set_logo.phpw. Notice the file extension. The filename of the default constructor is constructor.phpw.

One word first: Write the documentation with any program you want to. I prefer the KDE text editor Kate, but a vi, emacs or even Notepad will do the job. Note: If you use non-ASCII characters, you need to save the file as UTF-8.

The docs consist of structured text: You tell that a text is in a paragraph, that the word shall get special emphasis or that another word is to be taken literal. If you have written HTML pages, you will know the concept.

You might wonder why the docs don't use HTML tags: It's because DocBook just describes the text structure, it doesn't format it. HTML tries to separate layout (CSS) and content (XHTML) as well, but DocBook can be used to produce not only HTML, but PDFs and real books, too. There are many special elements in a book: Chapters, sections, examples, and in a programming manual like this you have methods, parameters, properties, signals and so on. Each element has its own tag. This seems quite confusing when you start with docbook, but it has its benefits: Complete control over the output.

The most basic element is <para>, used to separate text into paragraphs. Paragraphs contain other tags like links, filenames, tables and so on. There is a special paragraph type <simpara> for paragraphs without any other tag inside.

The next important tags are the links. Have a look at their section.

You can emphasise words or groups of words via <emphasis>, or define literals with <literal>. Filenames can be expressed with <filename>, variables with <varname>. There are many more small tags, but listing them here would make a whole manual.

If you want to list items, use the <itemizedlist> (unordered) or <orderedlist> (ordered) tags. The list items in it have to be surrounded with a <listitem> tag.

<itemizedlist>
 <listitem>First item</listitem>
 <listitem>Second item</listitem>
</itemizedlist>

The manual lives through the links which interconnect the pages, allowing one to jump to other relevant sections with one click. Whenever you make a reference to some other class or a similar function, link it. It saves people a lot of time searching.

The manual knows four types of links between pages:

The PHP-GTK 2 documentation, unlike the previous version created for PHP-GTK 1, supports images and external code examples.

There are three types of images: class images, normal images which create their own paragraph, and inline images which flow with the text.

Class images are shown at the class overview page, on the right side of the description. Just add a

<classimage fileref="&directory.images;/reference/gtk/gtkiconview.constructor.png"/>

<graphic fileref="&directory.images;/path/to/the/file.png"/>

<inlinegraphic fileref="&directory.images;/path/to/the/file.png"/>

<example>
     <title>Simple GtkAboutDialog</title>
     <programlisting role="php">
      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
          href="&directory.examples;/reference/gtk/gtkaboutdialog/constructor.phpw"
             parse="text">
       <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
      </xi:include>
     </programlisting>
    </example>

<informalexample>
     <programlisting role="php"><![CDATA[
//some php code here
]]></programlisting>
    </informalexample>