GTK Reference Documentation Notes =============================== Things to include: Compiling with GTK - gtk-config, gtk.m4, debugging options. g_warning, g_return_if_fail etc. - though these are in glib. Initialising the GTK library and entering the main loop. Widgets (see below) Object data hash (& GINT_TO_POINTER-type macros) Type functions Ref counting Widget Layout - size_request/size_allocate, coordinate system, X windows. Styles Accelerators - major changes for GTK 1.1 Signals - signal emission procedure, connecting to signals, stopping, adding new signals for new widgets, marshaller functions. X Events - signals ending in "_event" have extra param, event masks Keyboard input - focus, CAN_FOCUS, GRAB_FOCUS Default widgets - CAN_DEFAULT, HAS_DEFAULT Args - not complete yet. Drag-and-drop Selections Timers AddInput RC files Factories - major changes for GTK 1.1 Indices - functions, signals, widget hierarchy/alphabetical list/grouped - annotated For each widget: (We include a brief summary of the widget and its functions/signals at the top of the page, since a lot of the time people know how it works but have just forgotten a prototype or variable name.) * Name * Ancestors in widget hierarchy, with hyperlinks and set out like Java docs. Short description. ? '#Include ' line? * Index of functions, with prototypes, hyperlinks to descriptions below. ? Index of useful members of widget struct, hyperlinks to descriptions below. * Index of signals, with prototypes of signal handlers, and hyperlinks to descriptions below. * Standard widget functions and macros, with hyperlinks. Usage - example code covering common use of the widget, which may also use ancestor's properties, e.g. gtk_misc_set_alignment (GTK_MISC (label)... + Full description of functions. Show parameters listed like Java docs? A lot of the time there will just be one param - the widget itself. + Full description of struct members. Show how to access using macro? + Full description of signals. + Full description of standard functions and macros. See Also section showing related widgets, mainly for the man pages. Could also be some structs or enums which are used by the widget, e.g. the GtkTableChild/GtkPackerChild structs. Do we keep the enums separate? Or put them with the widget if they are only relevant to that widget? Include screenshots? + Include Args? - These still aren't fully supported, and they duplicate the functionality already available, but should probably be included. Issues: Some things have/will change between different GTK versions so we have to show the changes somehow - a 'deprecated' icon/entity/label or possibly show the version of GTK which each item was added to, e.g. a GTK 1.1 icon. 'Added in GTK 1.1', 'Deprecated in GTK 1.1', 'Not in GTK 1.1' ... Cross-references - any time a widget class/type/enum appears there should be a cross-reference (which will turn into a hyperlink for html). But for man pages/printed docs we don't want 'See Also's everywhere. Need to use an easy-to-remember naming scheme for ids - use widget names, function names, enum names as much as possible. Glib & GDK documentation - want this to be very similar, and we also need to add cross-references to glib/gdk types and functions. But glib documentation should also be separate? For man page output we should include keywords or something to make it easy to find the page with 'man -k' or similar. For printed output we should also index all widgets, functions etc., so the pages can be found easily. For the HTML version, we should create a database of entry points - widgets, functions, declarations, so that an IDE can easily open up the GTK documentation at a relevant page. e.g. If you move the mouse over a widget in the palette and press F1 it shows the page about the widget. GLib Reference ============== Sections: Intro - glib_major_version. Types - gint, gchar, TRUE, FALSE. Type conversion macros - GPOINTER_TO_INT. Limits - G_MINFLOAT etc. Macros - MIN, MAX, ABS, CLAMP, G_ENUM, G_STMT_START, G_GNUC_PRINTF, G_GNUC_FUNCTION, ATEXIT. Memory allocation - g_new, g_new0, g_malloc, g_mem_chunk_create, g_chunk_new. Warnings/assertions - g_assert, g_return_if_fail, g_error, g_warning. Timers. String utility functions. Utility functions - g_get_user_name, g_get_home_dir, g_snprintf. Scanner. Modules. Completion. Data structures: Doubly-linked lists. Singly-linked lists. Hash tables & hash functions - beware of adding pointers to dynamically-allocated memory! - it may never be freed. Caches. Trees. Strings. String chunks. Resizable arrays. Resizable pointer arrays. Byte arrays. Quarks ?? Datasets. Relation & Tuples. Reference Material ================== GTK Specific Stuff: GTK info pages - a number of widgets & functions are documented, as well as some more general GTK programming topics, e.g. signals, object data. GTK tutorial - has descriptions of many widgets. Shawn Admundson's example man page - nice structure, includes brief reference material at top and more detailed descriptions below which is good (like Java docs). Also has a 'Usage' section which describes common usage. Doesn't include GTK Args, or useful members of the widget struct. gtk+/gtk/testgtk gtk+/examples - lots of example code. Documentation of other languages/toolkits: Gnome's DocBook documentation. - gnome-libs/gnome-hello has a basic DocBook document. - perl script in gnome-libs/devel-docs/gdoc - what does it do?? - gnome-libs/devel-docs/gnome-dev-info.sgml has lots of stuff: uses '', 'literal', 'prompt', 'userinput' 'function', 'funcsynopsis', 'funcdef' 'paramdef', 'parameter' Java documentation - has a very nice structure and nice graphics to make it more attractive, cross-references, describes every function param. QT documentation - nice structure, screenshots, cross-references. man manual page - we want to output man pages, so we should try to keep close to the standard parts etc. (Use section 3 - library functions) From man man page: 'They may be labelled NAME, SYNOPSIS, DESCRIPTION, OPTIONS, FILES, SEE ALSO, BUGS, and AUTHOR.' see man (7) for the troff macros available (on Linux anyway).