X-Git-Url: http://git.draconx.ca/gitweb/gob-dx.git/blobdiff_plain/509cf0693fc440c71bdd3e71ea8947a6b4eb0bcf..486240dc4c5d57b0afaddba60d87fe375112bed5:/doc/gob.1.in

diff --git a/doc/gob.1.in b/doc/gob.1.in
index 34ad853..01d66cd 100644
--- a/doc/gob.1.in
+++ b/doc/gob.1.in
@@ -22,19 +22,13 @@ is in spirit similar to things like lex or yacc.
 .SH OPTIONS
 .PP
 .TP
-.B -?
-.TP
-.B -h
-.TP
-.B --help
+.B -? -h --help
 Display a simple help screen.
 .TP
 .B --version
 Display version information (note, --version was not added until 0.92.0)
 .TP
-.B -w
-.TP
-.B --exit-on-warn
+.B -w --exit-on-warn
 Exit with an error code even when you encounter a warning.
 .TP
 .B --no-exit-on-warn
@@ -70,14 +64,12 @@ define the private data structure at the point in the .c source where
 the class definition begins.  This option implicitly negates
 --always-private-header
 .TP
-.B -n
-.TP
-.B --no-write
+.B -n --no-write
 Do not write any output files, just check syntax of the input file.
 .TP
 .B --no-lines
 Do not print out the '#line' statements into the output.  Useful for debugging
-the autogenerated generated code.
+the auto-generated generated code.
 .TP
 .B --no-self-alias
 Do not create the Self and SelfClass type aliases and the SELF, IS_SELF
@@ -85,6 +77,11 @@ and SELF_CLASS macros.
 .TP
 .B --no-kill-underscores
 Do not remove the initial underscore from method names.
+.TP
+.B --always-private-struct
+Always include the private pointer in the public header file.  This is useful for
+files which are part of a library and you want to reserve the right to add some
+private data members without breaking binary compatibility.
 
 .SH TYPENAMES
 .PP
@@ -341,7 +338,7 @@ take up more space in the file and it may become more cluttered.
 .PP
 The data is zeroed out after being destroyed.  This is to make debugging easier
 in case your code might try to access an already destroyed object.  In case
-you have overriden the destroy method, your code will be run first and
+you have overridden the destroy method, your code will be run first and
 only then will the destructors be called.  You should not however make any
 assumptions about the order at which the destructors are called.  If you have
 interdependencies between destructors for different data members, you will
@@ -434,7 +431,7 @@ is just like
   set { self->foo = ARG; };
 
 .fi
-Similiarly,
+Similarly,
 .nf
 
   private char * foo;
@@ -447,7 +444,7 @@ is just like
   private char * foo;
   argument POINTER (type char *) foo
   get {
-        ARG = self->_priv->foo;
+        ARG = g_strdup(self->_priv->foo);
   } set {
   	g_free(self->_priv->foo);
         self->_priv->foo = g_strdup(ARG);
@@ -480,10 +477,9 @@ is just like
 .PP
 As you see it will handle NULLs correctly (for the string, g_free and g_strdup
 handle NULLs).  And it will also handle private, protected and public members.
-Also you should notice that when the get is used, only a pointer is always
-returned for both objectlink and strinklink.  So you should treat the returned
-value with care and never free it (and notice that it will only be around
-until you set the argument to something else or destroy the object).
+For objectlink, just a pointer is returned on get, if you wish to keep it around,
+you should call gtk_object_ref on it.  For stringlink, get makes a copy of
+the string which you should free after use.  This is the behaviour since 1.0.2.
 .PP
 Methods:
 .PP
@@ -637,7 +633,9 @@ signal just like a public method.  Example:
 	  ...
   }
   
+.fi
 or
+.nf
 
   signal last NONE(NONE) void foo(self);
 
@@ -724,13 +722,13 @@ function.  For example:
   }
 .fi
 Thus you see that the "_foo" method still generates the method "my_object_foo"
-just as "foo" would generate.  You can turn off this behaviour if you depend
-on the old (pre 0.93.5) behaviour with the --no-kill-underscores option.  This
+just as "foo" would generate.  You can turn off this behavior if you depend
+on the old (pre 0.93.5) behavior with the --no-kill-underscores option.  This
 also means that if both "_foo" and "foo" are defined, it is treated as a
 conflict.
 .PP
 This does not apply to override methods.  Override methods are special beasts
-and this is not neccessary and would make the code behave in weird ways.
+and this is not necessary and would make the code behave in weird ways.
 .PP
 Making new objects:
 .PP
@@ -752,7 +750,7 @@ Self alias casts:
 .PP
 There are some standard casts defined for you.  Instead of using the full
 macros inside the .c file, you can use SELF, IS_SELF and SELF_CLASS.  Using
-these makes it easier to for example change classnames around.
+these makes it easier to for example change class names around.
 .PP
 Self alias types:
 .PP
@@ -809,7 +807,7 @@ compile with a C++ compiler.
 
 .SH IDENTIFIER CONFLICTS
 .PP
-Gob will need to define some local varibles and functions in the generated
+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
@@ -824,7 +822,7 @@ 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 eqivalent to the names without the initial underscore.  This
+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"
@@ -852,7 +850,7 @@ 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:
-.fi
+.nf
 
   class Gtk:Button:Example from Gtk:Button {
           /**
@@ -872,7 +870,7 @@ would be:
 
 .fi
 If the function you are documenting is a signal or a virtual then it will
-be documentating the wrapper that starts that virtual function or emits
+be documenting the wrapper that starts that virtual function or emits
 that signal.
 
 .SH DEALING WITH CIRCULAR HEADERS
@@ -900,9 +898,63 @@ 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
+.PP
+For Makefile.am you have to set up a couple more things.  First you have to
+include the generated .c and .h files into BUILT_SOURCES variable.  You
+have to include both the .gob and the .c and .h files in the SOURCES for your
+program.
+
+.SH DEBUGGING
+.PP
+GOB does several things to make debugging the code easier.  First it adds
+preprocessor commands into the output c file that point to the correct places
+in your .gob input file.  However sometimes there might be some bigger
+confusion and this is just not helpful.  In this case you will probably want
+to have gcc point you directly at the generated files.  For this use
+the --no-lines command line option.  You should also note that these commands
+are not generated for the public header file at all.  If there is an error which
+points you to the public header file, make sure you fix this error in the .gob
+file, otherwise your changes will not have any effect after gob recompiles the
+sources again.
+.PP
+Sometimes you might want to know which method you are in for some debugging
+output.  GOB will define __GOB_FUNCTION__ macro, which is just a string constant
+with a pretty name of the method.
+
 .SH BUGS
 .PP
-Also the lexer does not actually parse the C code, so I'm sure that some corner
+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
 try to make the lexer try to handle it properly, but no promises.
@@ -941,6 +993,25 @@ Basically, if you use gob, just don't use the C preprocessor too extensively.
 Comments will not get through to the generated files unless inside C code.
 This makes using something like gtk-doc harder.  However I'm planning to
 fix this somehow.
+.PP
+The short name aliases are actually implemented as pointers to functions.  Thus
+if you want to get the pointer of a function using the short name alias you
+can't use the '&'.  Thus:
+.nf
+
+  void (*foo)(Self *);
+
+  /* this will NOT work */
+  foo = &short_name;
+
+  /* this will work */
+  foo = short_name;
+
+  /* Both of these will work */
+  foo = &my_class_long_name;
+  foo = my_class_long_name;
+
+.fi
 
 .SH AUTHOR
 .PP