5.8. Gamma/GTK manual

Preparing Cogent Documentation :
	Chapter 5. Special Organization

The reference pages for this document are generated automatically by a Gamma program (gtkwidgets2docs.g) that reads widget definitions from the gammagtk.so shared object file and writes them to individual files, adding SGML markup. The HTML version of the output contains links to the standard GTK documentation, which is included in our HTML distribution. Because the GTK widget set is under constant development, we have created the reference in such a way that it can be newly generated at any time. Certain parts of some pages, such as widget purposes, descriptions, and examples are written by hand and included in the document using entities. The entity definitions and files are generated automatically by gtkwidgets2docs.g as well.

Here are the pre-processing steps for setting up the GTK documentation and auto-generating the SGML for the Gamma/GTK reference pages:

Download the GTK, GDK and Glib tarballs (glib-docs.tar.gz, gdk-docs.tar.gz, and gtk-docs.tar.gz) from the GTK API website page (www.gtk.org/api).
Unzip and untar them in the doc/i/gtkgamma/htmldocs/ directory, giving you:
- doc/i/gtkgamma/htmldocs/gtk/*.html
- doc/i/gtkgamma/htmldocs/gdk/*.html
- doc/i/gtkgamma/htmldocs/glib/*.html
cd to the doc/o/gtkgamma-book/ directory and type make gtkhtml.

If you are making up the documentation as a result of a new Gamma/GTK build, you will have to process the new functions. This is done by running the function_processor.g program and hand editing the output. Here is the procedure:

Install the new Gamma/GTK build, which should include at least a new gammagtk.so shared object library.
cd to the doc/i/gtkgamma/autodocs/ directory and type function_processor.g (to run that program).
Mark the output with your mouse, and copy it into the newfunctions.txt file. (Actually the program should take care of this, but it doesn't yet.) This keeps a record of all new changes for later reference.
Open the processed_functions.txt file and hand edit each function's category. The place to add these hand edits is marked with the symbol *** for each new function. You should not attempt to run gtkwidgets2docs.g until the hand edits have been done.
Each line consists of three or four space-separated strings, usually three, like this:
```
gdk_window_unref gdk-windows GDK
...
gtk_calendar_get_type GtkCalendar Cogent
```
The first string is the function name. The second string is either the widget name, or the category in the GTK docs where the function is documented. The third string is a code for further processing by the gtkwidgets2docs program. Current codes are GTK, GDK, and Cogent. In some cases, there will be a fourth string, like this:
```
gtk_rc_add_default_file gtk-resource-files GTK Note: Use gtk_rc_parse() instead of this function.
...
gtk_accel_group_create_add GtkAccelGroup GTK Category: gtk-keyboard-accelerators
```
When the function does not have an assoicated widget, the fourth string allows us to add notes to the documentation as necessary. When the function has an associated class, that class has its own page in our documentation, but not in the GTK docs. Therefore, the category has to be added here. The gtkwidgets2docs program knows how to pick it up from here and use it as the category.

When all hand edits are complete and the file has been tested, it should be copied to processed_functions.txt.backup in case something should go wrong, because the function_processor.g program writes over processed_functions.txt each time it runs, and all hand-edits could be inadvertently lost. We don't do an automatic backup, because we want to make sure the content is correct before we back up.

After making sure any new functions have been processed, cd to the doc/i/gtkgamma/autodocs/ directory and type gtkwidgets2docs.g (to run that program).
Make up the HTML or PDF documentation as usual.

The source code for the programs and a page of example output are shown in the Building Gamma/GTK docs appendix.


5.7. Glossary and FAQ		5.9. Windows HTML Help