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.
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.
<listitem>s themselves can contain <para> 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: GtkAboutDialog.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: set_logo() . 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: Gtk::ICON_LOOKUP_FORCE_SVG.- 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 title:
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: documentation mailing list. 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: php-gtk-doc@lists.php.net, and will give you: documentation mailing list.
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; base directory; it will be replaced with the correct images directory at compile time.Normal images are included in a paragraph via
and inline images withCode 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:
<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>
|
Examples for code snippets have to be inline as in:
<informalexample>
<programlisting role="php"><![CDATA[
//some php code here
]]></programlisting>
</informalexample>
|