Release 0.92.2

[gob-dx.git] / doc / gob.1.in

diff --git a/doc/gob.1.in b/doc/gob.1.in
index be027ace0f6b2b7faa4e79d09d01535837287a9a..40916fd87335d3b33ccdc8456dad984225724bb5 100644 (file)
--- a/doc/gob.1.in
+++ b/doc/gob.1.in
@@ -43,6 +43,9 @@ Exit with an error only on errors, not on warnings, this is the default.
 .B --for-cpp
 Generate C++ code.
 .TP
+.B --no-extern-c
+Never add the extern "C" to the header.
+.TP
 .B --no-gnu
 Never generate any code with GNU C extensions.  However all the GNU C
 extensions are always wrapped in #ifdef __GNUC__, so code using them compiles
@@ -98,11 +101,25 @@ you should only edit the .gob file.
 .SH INCLUDING NORMAL C CODE IN THE OUTPUT FILES
 .PP
 To include some code directly in the output C file begin with '%{'
-on an empty line and end the code with a '%}' on an empty line.  To
-put the code in the output header file, start the code with a '%h{'.
-For example:
+on an empty line and end the code with a '%}' on an empty line.  These
+sections will appear in the output files in the order they are given.
+There are several other \fIsections\fR to which you can put code.  You can
+put it in the 'header' section (which can be abbreviated 'h') and it will
+go into the public header file.  You can also put it in the 'privateheader'
+section (abbreviated 'ph') which will make the code go into the private
+header file.  Sometimes you want some code (other includes) to appear before
+the extern "C" and the protecting define.  To do this you can put them
+into the 'headertop' (or 'ht') section.  For example:
 .nf
 
+  %headertop{
+  /* this will be on top of the public header */
+  %}
+
+  %privateheader{
+  /* this will go into the private header file */
+  %}
+
   %h{
   /* will be included in the header */
   void somefunc(int i);
@@ -531,6 +548,31 @@ 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.
 
+.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 BUGS
 .PP
 Also the lexer does not actually parse the C code, so I'm sure that some corner