Release 0.90.4

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

diff --git a/doc/gob.1.in b/doc/gob.1.in
index ee42dd9d513f411bd20f384786ef6313aa803d0e..7691736c75a578f90001a4a9dc8d696766020d83 100644 (file)
--- a/doc/gob.1.in
+++ b/doc/gob.1.in
@@ -10,13 +10,39 @@
 GOB \- The GTK+ Object Builder
 .SH SYNOPSIS
 .PP
 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 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, 
 .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
 
 .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{
 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);
   %}
   void somefunc(int i);
   %}

+

   %{
   %{

+  /* will be included in the C file */

   void somefunc(int i)
   {
   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
 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
 .PP
 Signals:
 .PP


@@ -214,6 +244,13 @@ or
 
 .fi
 .PP
 
 .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
 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
 .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
 .nf
 
   private int


@@ -268,11 +306,58 @@ will fetch a new object, so a fairly standard new method would look like:
 
 .fi
 
 
 .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
 .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
 
 .SH AUTHOR
 .PP