Release 0.91.1

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

diff --git a/doc/gob.1.in b/doc/gob.1.in
index 426858045c287bc9e28fee27b6caf0723ac29072..9cada9a7ecafcee4cc130cf7afda4e12839c766a 100644 (file)
--- a/doc/gob.1.in
+++ b/doc/gob.1.in
@@ -41,7 +41,17 @@ Generate C++ code.
 Don't touch the generated header file unless it really changed, this avoids
 spurious rebuilds, but can confuse some make systems (automake in particular),
 so it is not enabled by default.
 Don't touch the generated header file unless it really changed, this avoids
 spurious rebuilds, but can confuse some make systems (automake in particular),
 so it is not enabled by default.

-
+.TP
+.B --always-private-header
+Always create a \fB<basename>-private.h\fR file, even if it would be empty.
+Otherwise, it is only created when there are private data members in the class.
+This option implicitly negates --no-private-header
+.TP
+.B --no-private-header
+Never create a private header file.  If we use any private datamembers,
+define the private data structure at the point in the .c source where
+the class definition begins.  This option implicitly negates
+--always-private-header

 
 .SH TYPENAMES
 .PP
 
 .SH TYPENAMES
 .PP


@@ -58,8 +68,13 @@ types.
 .PP
 The filenames are created from the typename.  The words are
 separated by '-' and all in lower case.  For example for an object named
 .PP
 The filenames are created from the typename.  The words are
 separated by '-' and all in lower case.  For example for an object named

-"Gtk:New:Button", the files are gtk-new-button.c and gtk-new-button.h.
-The header file is created to be human readable and to be used as a
+"Gtk:New:Button", the files are \fBgtk-new-button.c\fR and
+\fBgtk-new-button.h\fR.
+If you are using C++ mode, the output .c file will in fact be a .cc file.
+If you have any private data members, a private header file will also
+be created, called \fB<basename>-private.h\fR (for the example above it
+would be gtk-new-button-private.h).
+The public header file is created to be human readable and to be used as a

 reference to the object.  The .c source file is not created as a human
 readable source and is littered with #line statements, which make the
 compiler attempt to point you to the right line in your .gob file in
 reference to the object.  The .c source file is not created as a human
 readable source and is littered with #line statements, which make the
 compiler attempt to point you to the right line in your .gob file in


@@ -89,6 +104,23 @@ For example:
 
 .fi
 
 
 .fi
 

+.SH INCLUDE FILES
+.PP
+Gob will automatically include the class header file at the top of the .c 
+source file.  If you wish to include it somewhere else, put the include
+into some %{ %} section above the class definition, and gob will not include
+it automatically.  This way you can avoid circular includes and control
+where in the file do you want to include the header.
+.PP
+If you made any data members private, gob will also create a source file
+that will be called \fB<basename>-private.h\fR.  Same rule as above applies
+for this just as it does for the regular header file.  If you do explicitly
+include the regular header file, you should always include this private
+header file below it.  That is, if you use any private data members.  If you
+don't, the private header file automatically includes the public header file,
+and thus the public header file will be indirectly included at the very top
+of the file.
+

 .SH MAKING A NEW CLASS
 .PP
 The class header:
 .SH MAKING A NEW CLASS
 .PP
 The class header:


@@ -121,9 +153,28 @@ identifier allowed per typename unlike in normal C.  Example:
 
 .fi
 .PP
 
 .fi
 .PP

-The private members are not currently protected from outside use,
-they are just marked by a comment in the header file, this will most likely
-be somehow solved in some future version.
+Public datamembers are accessed normally as members of the object struct.
+Example where 'i' is as above a public data member:
+.nf
+
+  object->i = 1;
+
+.fi
+.PP
+The private data members are defined in a structure which is only available
+inside the .c file.  You must access them using the structure _priv.  Example
+where 'h' is the private data member (as in the above example):
+.nf
+
+  object->_priv->h = NULL;
+
+.fi
+Note that the _priv structure is defined in the \fB<basename>-private.h\fR.
+This file is automatically included if you don't include it yourself.  You
+should always explicitly include it if you explicitly also include the main
+header file.  In case you use the \fB--no-private-header\fR option, no
+private header file is created and you can only access the _priv pointer
+below the class definition in the .gob file.

 .PP
 The third type is an argument type.  It is a named datamember which
 is one of the features of the GTK+ object system.  You need to define a get
 .PP
 The third type is an argument type.  It is a named datamember which
 is one of the features of the GTK+ object system.  You need to define a get


@@ -276,6 +327,7 @@ class, you can use the PARENT_HANDLER macro with your arguments.  Example:
           /* some code here */
           PARENT_HANDLER(self, wid);
   }
           /* some code here */
           PARENT_HANDLER(self, wid);
   }

+

 .fi
 .PP
 Calling methods:
 .fi
 .PP
 Calling methods:


@@ -306,7 +358,7 @@ this method, you can use the GET_NEW macro that is defined for you and that
 will fetch a new object, so a fairly standard new method would look like:
 .nf
 
 will fetch a new object, so a fairly standard new method would look like:
 .nf
 

-  public GtkWidget *
+  public GtkObject *

   new(void) {
          GtkObject *ret;
          ret = GTK_OBJECT (GET_NEW);
   new(void) {
          GtkObject *ret;
          ret = GTK_OBJECT (GET_NEW);


@@ -328,10 +380,6 @@ compile with a C++ compiler.
 
 .SH BUGS
 .PP
 
 .SH BUGS
 .PP

-The generated header file is included as the first file in the .c file, no
-matter what. This means that you will have to put things that need to be
-included before that, into an %h{ } section.
-.PP

 Also the lexer does not actually parse the C code, so I'm sure that some corner
 cases or maybe even some not so corner cases of C syntax might confuse gob
 completely.  If you find any, send me the source that makes it go gaga and I'll
 Also the lexer does not actually parse the C code, so I'm sure that some corner
 cases or maybe even some not so corner cases of C syntax might confuse gob
 completely.  If you find any, send me the source that makes it go gaga and I'll