+.SH DEALING WITH DIFFERENT GOB VERSIONS
+.PP
+Defines:
+.PP
+In your generated C file, you can use the defines GOB_VERSION_MAJOR
+GOB_VERSION_MINOR and GOB_VERSION_PATCHLEVEL if you wish to for example
+use a feature that is only available in some newer gob version. Note however
+that you can only use these defines in the C code portions of your .gob file,
+and #ifdef's cannot span multiple functions. Check the BUGS section
+for more on using the C preprocessor and gob. Also note that these
+have only been available since the 0.92.1 version of gob.
+.PP
+Minimum version requires:
+.PP
+You can also make your .gob file require at least certain version of gob. You
+do this by putting 'requires x.y.z' (where x.y.z is the version number) outside
+of any C block, comment or class, usually you should make this the first line
+in the file or close to the top. If gob finds this and the version of gob used
+to compile the code is lower then that listed in the require, gob will generate
+an error and exit. For example to require that gob version 0.92.1 or higher
+be used to compile a file, put this at the top of that file:
+.nf
+
+ requires 0.92.1
+
+.fi
+It should be noted however that this feature was not added until 0.92.1, and
+so if the file gets compiled by a lower version, gob would generate a
+syntax error. Thus by putting in a requires line, you are implicitly
+requiring at least 0.92.1.
+
+.SH C++ MODE
+.PP
+There is a C++ mode so that gob creates C++ compiler friendly files. You need
+to use the --for-cpp argument to gob. This will make the generated file have
+a .cc instead of a .c extension, and several things will be adjusted to
+make it all work for a C++ compiler. One thing that will be missing is an
+alias to the new method, as that clashes with C++, so instead you'll have to
+use the full name of the method inside your code. Also note that gob does
+not use any C++ features, this option will just make the generated code
+compile with a C++ compiler.
+
+.SH OVERRIDING THE GET_TYPE METHOD
+.PP
+The get_type is not really a method, but a function which initializes your
+object. Recently objects appeared which require you to make a custom
+get_type function (BonoboXObject currently, see next section for direct
+BonoboXObject support). So in 1.0.7 it is now possible
+to override this function. To do so, just define a new public method called
+get_type, with no arguments. Example:
+.nf
+
+ public GtkType
+ get_type (void)
+ {
+ /* code goes here */
+ return some_type;
+ }
+
+.fi
+
+.SH DIRECT BonoboXObject SUPPORT
+.PP
+If you want to build a BonoboXObject class gob has direct support for these
+classes since 1.0.9. Just create a new object that derives from
+Bonobo:X:Object. Then use a "BonoboX" class flag with the interface name as an
+argument. The interface name should be as you would type it in C, that is with
+underscores as namespace separators. Then you add the methods (using exact
+same names as in the idl file) and prepend those methods with a BonoboX
+keyword. For example imagine you have an interface GNOME/Foo/SomeInterface,
+with a method fooBar that takes a single string:
+.nf
+
+ class Foo:Some:Interface from Bonobo:X:Object
+ (BonoboX GNOME_Foo_SomeInterface) {
+
+ BonoboX
+ private void
+ fooBar (PortableServer_Servant servant,
+ const CORBA_char *string,
+ CORBA_Environment *ev)
+ {
+ Self *self = SELF (bonobo_object_from_servant (servant));
+
+ /* your code here */
+ }
+
+ /* rest of class */
+ }
+
+.fi
+Note that the implementation method can be private, in fact that's probably
+a good idea to do. It won't work to make this a signal, it can however
+be a virtual. Note that the method prototype must match the one from the
+interface header file, or you will get a bad assignment warning. You should
+check the header file generated by orbit-idl and see the epv structure
+for the correct prototypes if you can't figure them out from the idl itself.
+Also note that the first argument is not "self", but the servant and you must
+use bonobo_object_from_servant function to get the actual object pointer.
+
+.SH IDENTIFIER CONFLICTS
+.PP
+Gob will need to define some local variables and functions in the generated
+files, so you need to take some precaution not to conflict with these. The
+general rule of thumb is that all of these start with three underscores. There
+is one, "parent_class" which doesn't because it's intended for use in your
+code. For virtuals or signals, you cannot use the identifier __parent__
+which is used for the parent of the object. You should actually never access
+__parent__ either as it not guaranteed that it will stay named this way.
+Data members cannot be named __parent__ nor _priv. For methods, you cannot
+use the identifiers "init" or "class_init" unless you mean the constructor
+methods. You shouldn't generally use 3 underscores even in override method
+argument lists and virtual and signal method names as it might confuse the
+PARENT_HANDLER macro. In fact avoiding all names with three underscores is
+the best policy when working with gob.
+.PP
+Also note that starting with version 0.93.5, method names that start with a
+an underscore are equivalent to the names without the initial underscore. This
+is done to avoid conflicts with the aliases. Thus you can define the method
+as "_name", if "name" happens to be some standard library function. This is
+the same as defining it as "name" except that the local alias will be "_name"
+rather then "name".
+.PP
+There are a couple of defines which you shouldn't be redefining in the code
+or other headers. These are SELF, IS_SELF, SELF_CLASS, ARG, VAR,
+PARENT_HANDLER, GET_NEW, GOB_VERSION_MAJOR, GOB_VERSION_MINOR and
+GOB_VERSION_PATCHLEVEL.
+.PP
+As for types, there are Self and SelfClass types which are only defined in your
+source files. Their generation (just like the generation of the SELF macros)
+can be turned off, see command line options.
+
+.SH USING GTK-DOC STYLE INLINE DOCUMENTATION
+.PP
+If you want to use gtk-doc style inline documentation for your objects, you
+can do one of two things. First, you could include the inline documentation
+comments in your %{ %} section which will then be put verbatim into the
+output source file. This is the way you should use for functions you define
+outside of the class.
+.PP
+For class methods, you should use a gtk+ style comment, however it can be
+indented any number of tabs or spaces and you can use the short method name
+without the type prefix. Gob will automatically try to extract these and
+translate to full names and put them in the output source file. An example
+would be:
+.nf
+
+ class Gtk:Button:Example from Gtk:Button {
+ /**
+ * new:
+ *
+ * Makes a new #GtkButtonExample widget
+ *
+ * Returns: a new widget
+ **/
+ public
+ GtkWidget *
+ new(void)
+ {
+ return GTK_WIDGET(GET_NEW);
+ }
+ }
+
+.fi
+If the function you are documenting is a signal or a virtual then it will
+be documenting the wrapper that starts that virtual function or emits
+that signal.
+
+.SH DEALING WITH CIRCULAR HEADERS
+.PP
+Sometimes you may need to use an object of type MyObjectA in the MyObjectB
+class and vice versa. Obviously you can't include headers for both. So you
+need to just declare the typedef in the header of A for B, and the other way
+around as well. The headers generated since v0.92.2 include a protecting
+define before it declares the typedef. This define is the
+__TYPEDEF_<upper case object name>__. So inside my-object-a.h there will be
+this:
+.nf
+
+ #ifndef __TYPEDEF_MY_OBJECT_A__
+ #define __TYPEDEF_MY_OBJECT_A__
+ typedef struct _MyObjectA MyObjectA;
+ #endif
+
+.fi
+Now instead of including my-object-a.h in the header section of
+my-object-b.gob, just copy the above code there and you're set for using
+MyObjectA as a type in the method parameters and public types.
+.PP
+Another way to get out of this problem is if you can use those types only
+in the private members, in which case they won't be in the generated public
+header.
+
+.SH BUILDING WITH MAKE
+.PP
+If you are using normal makefiles, what you need to do is to add a generic
+rule for .gob files. So you would include the following in the Makefile
+and then just use the .c and .h files as usual (make sure the space
+before the 'gob' is a tab, not spaces):
+.nf
+
+ %.c %.h %-private.h: %.gob
+ gob $<
+
+.fi
+
+.SH BUILDING WITH AUTOCONF and AUTOMAKE
+.PP
+This is a little bit more involved. Basically the first thing to do is to
+check for GOB in your configure.in file. You can use the supplied m4 macro
+which will also check the version of gob. Basically you include this:
+.nf
+
+ GOB_CHECK(0.93.4)
+
+.fi
+This will replace @GOB@ in your makefiles with the full path of gob. Thus
+when adding the generic rule to your Makefile.am file, it should look like:
+.nf
+
+ %.c %.h %-private.h: %.gob
+ @GOB@ $<
+
+.fi