X-Git-Url: http://git.draconx.ca/gitweb/gob-dx.git/blobdiff_plain/daead564b9592e78d418deb56a211cd5ea399f76..2310330e7d4d724bf6641339836be8523f95c916:/doc/gob.1.in

diff --git a/doc/gob.1.in b/doc/gob.1.in
index ee42dd9..7691736 100644
--- a/doc/gob.1.in
+++ b/doc/gob.1.in
@@ -10,13 +10,39 @@
 GOB \- The GTK+ Object Builder
 .SH SYNOPSIS
 .PP
-.B gob
+.B gob [-?] [-h] [-w] [--exit-on-warn] [--no-exit-on-warn] [--for-cpp]
+[--no-touch-headers] file
 .SH DESCRIPTION
 .PP
 GTK+ Object Builder is a simple preprocessor for easily creating
 GTK+ objects.  It does not parse any C code and ignores any C errors.  It
 is in spirit similar to things like lex or yacc.
 
+.SH OPTIONS
+.PP
+.TP
+.B -?
+.TP
+.B -h
+Display a simple help screen.
+.TP
+.B -w
+.TP
+.B --exit-on-warn
+Exit with an errorcode even when you encounter a warning.
+.TP
+.B --no-exit-on-warn
+Exit with an error only on errors, not on warnings, this is the default.
+.TP
+.B --for-cpp
+Generate C++ code.
+.TP
+.B --no-touch-headers
+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.
+
+
 .SH TYPENAMES
 .PP
 Because we need to parse out different parts of the typename, 
@@ -35,19 +61,22 @@ separated by '-' and all in lower case.  For example for an object named
 
 .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
+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:
 .nf
 
   %h{
+  /* will be included in the header */
   void somefunc(int i);
   %}
+
   %{
+  /* will be included in the C file */
   void somefunc(int i)
   {
-	  /* some code */
+        /* some code */
   }
   %}
 
@@ -181,7 +210,8 @@ so that one can override the method in derived methods.  They can be empty
 which makes calling the methods he same as public methods.  This type of
 method is just a little bit "slower" then normal functions, but not as
 slow as signals.  You define them by using "virtual" keyword before the
-prototype.
+prototype. If you put the keyword "private" right after the "virtual"
+keyword, the wrapper will not be a public method, but a private one.
 .PP
 Signals:
 .PP
@@ -214,6 +244,13 @@ or
 
 .fi
 .PP
+If you don't want the wrapper that emits the signal to be public, you can
+include the keyword "private" after the "signal" keyword. This will make
+the wrapper a normal private method.
+.PP
+If you don't define a "first" or a "last", the default will be taken as
+"last".
+.PP
 Override methods:
 .PP
 If you need to override some method (a signal or a virtual method
@@ -234,8 +271,9 @@ get warnings during compilation.  Example:
 .PP
 Calling methods:
 .PP
-Inside the code, defines are set for the methods, so that you don't
-have to type the class name before each call.  Example:
+Inside the code, pointers are set for the methods, so that you don't
+have to type the class name before each call, just the name of the method.
+Example:
 .nf
 
   private int
@@ -268,11 +306,58 @@ will fetch a new object, so a fairly standard new method would look like:
 
 .fi
 
+.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 extention, 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 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.
+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
+try to make the lexer try to handle it properly, but no promises.
+.PP
+Another thing is that gob ignores preprocessor macros.  Since gob counts
+braces, the following code won't work:
+.nf
+
+  #ifdef SOME_DEFINE
+  if(foo) {
+  #else
+  if(bar) {
+  #endif
+          blah();
+  }
+
+.fi
+To make this work, you'd have to do this:
+.nf
+
+  #ifdef SOME_DEFINE
+  if(foo)
+  #else
+  if(bar)
+  #endif
+  {
+          blah();
+  }
+
+.fi
+There is no real good way we can handle this without parsing C code, so we
+probably never will.  In the future, I might add #if 0 as a comment but
+that's about as far as I can really take it and even that is problematic.
+Basically, if you use gob, just don't use the C preprocessor too extensively.
 
 .SH AUTHOR
 .PP