This chapter deals with actually contributing to PHP-GTK 2 documentation. If
you have further questions, feel free to ask them on the
php-gtk-doc mailing list.
If you have written some documentation, you probably want it to go
into the official manual. Please send your files by mail to the php-gtk-doc
mailing list mentioned above, or to one of the contributors listed
on the documentation credits page.
They will put your work in the official sources on the CVS server.
If you contribute to the docs regularly, you can get a CVS account. Ask
about it at the documentation mailing list.
If you have a CVS account: always compile the manual
before committing changes! If there is an error in the xml, the nightly manual
generation will break and people will complain.
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.
Directory and file structure
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
Notice the file extension. The filename of the default constructor
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
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
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
The next important tags are the links. Have a look at
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
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
s themselves can contain
and other tags.
Most times the skeleton of the class docs already exist, and you
will only have to fill the description with content and the tags
mentioned above. The tags which need to be filled are:
<shortdesc> for a short description of
a class/function/signal/property (only one single paragraph, preferably
no tags in it) and <desc>
with a full description of the class (use many paragraphs).
If you are uncertain how to do something or if the tag you have chosen
is correct, have a look at the other, already written files - they are
the best examples.
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:
Class links link to the overview page of a certain
class. For example, you would use:
to link to the GtkAboutDialog overview page. It will look like this:
Method/function links connect to a method or
function of a certain class. The function name will automatically
be completed with (). Use
to accomplish the task. The manual will show:
The class parameter is not necessary
if you link to the current class; but add it nevertheless
- it means less effort when copying something to a different
part of the manual.
Links to signals are created in this way:
This will compiled to: "close".
Enumerator links are also very simple:
This will result in: GtkButtonBoxStyle.
You can also link to an enumeration or flag using one of its option fields:
This will compile to:
Property links are a simple:
This will result in: action_area.
Free manual links are necessary if you want to link
a certain word in the text, or link to a tutorial section. You need to
provide the ID of the section to be linked, and are free to choose a
See the result:
The documentation tutorial
shows you how to compile the manual.
The <link linkend="tutorials.doccing">documentation tutorial</link>
shows you how to compile the manual.
URL links leave the scope of the manual; you can
write a plain link to any HTTP, FTP or email address you want:
which will look like:
If the link is one commonly used in the manual, you can use one of
the many XML entities listed in manual/global.ents
to achieve a similar effect:
will result in: email@example.com, and
<ulink url="mailto:firstname.lastname@example.org">documentation mailing list</ulink>
will give you:
documentation mailing list.
<ulink url="mailto:&email.phpgtkdoc;">documentation mailing list</ulink>
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
Note the &directory.images;
directory; it will be replaced with the correct images directory
at compile time.
Normal images are included in a paragraph via
and inline images with
Code examples can be separated from the manual file, too. This is
especially useful for readers who want to run the examples themselves: no
need to copy and paste the code, just execute it in the example code
directory. Furthermore, it's easier to test the examples when writing
and editing the manual.
Examples may get their own file only if they
are a complete, executable program - code snippets have to be inline.
Detached examples can be included in this way:
<xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
Examples for code snippets have to be inline as in:
//some php code here
section is useful because it allows you to
directly include code, without having to escape it. The
<?php and ?> tags aren't required in code snippets. Note that
opens a new document inside the current
document, alas requiring new indention. Don't be afraid of breaking your
indenting scheme inside CDATA sections.