Index: trunk/lib/Text/FormBuilder.pm
===================================================================
--- trunk/lib/Text/FormBuilder.pm	(revision 73)
+++ trunk/lib/Text/FormBuilder.pm	(revision 74)
@@ -820,7 +820,7 @@
 CGI script to render the form. This way, you only need CGI::FormBuilder on
 your server, and you don't have to parse the form spec each time you want 
-to display your form. The generated module has one function (not exported)
-called C<get_form>, that takes a CGI object as its only argument, and returns
-a CGI::FormBuilder object.
+to display your form. The generated module is a subclass of L<CGI::FormBuilder>,
+that will passa long any constructor arguments to FormBuilder, and set up
+the fields for you.
 
 First, you parse the formspec and write the module, which you can do as a one-liner:
@@ -828,5 +828,5 @@
     $ perl -MText::FormBuilder -e"Text::FormBuilder->parse('formspec.txt')->write_module('My::Form')"
 
-B<FIXME> And then, in your CGI script, use the new module:
+And then, in your CGI script, use the new module:
 
     #!/usr/bin/perl -w
@@ -837,5 +837,5 @@
     
     my $q = CGI->new;
-    my $form = My::Form::get_form($q);
+    my $form = My::Form->new;
     
     # do the standard CGI::FormBuilder stuff
@@ -868,22 +868,17 @@
     use warnings;
     
-    use CGI;
     use CGI::FormBuilder;
     
-    my $q = CGI->new;
-    
     my $form = CGI::FormBuilder->new(
-        params => $q,
-        # ... lots of other stuff to set up the form ...
+        # lots of stuff here...
     );
     
-    $form->field( name => 'month' );
-    $form->field( name => 'day' );
-    
-    unless ( $form->submitted && $form->validate ) {
+    # ...and your field setup subs are here
+    $form->field(name => '...');
+        
+    unless ($form->submitted && $form->validate) {
         print $form->render;
     } else {
-        # do something with the entered data ...
-        # this is where your form processing code should go
+        # do something with the entered data
     }
 
@@ -935,4 +930,6 @@
 =head1 LANGUAGE
 
+    # name field_size growable label hint type other default option_list validate
+    
     field_name[size]|descriptive label[hint]:type=default{option1[display string],...}//validate
     
@@ -986,5 +983,5 @@
 =item C<!field>
 
-Include a named instance of a group defined with C<!group>.
+B<DEPRACATED> Include a named instance of a group defined with C<!group>.
 
 =item C<!title>
@@ -1019,5 +1016,5 @@
 =back
 
-=head2 Fields
+=head2 Strings
 
 First, a note about multiword strings in the fields. Anywhere where it says
@@ -1042,11 +1039,13 @@
     unlabeled_field|''
 
-Now, back to the beginning. Form fields are each described on a single line.
-The simplest field is just a name (which cannot contain any whitespace):
+=head2 Fields
+
+Form fields are each described on a single line. The simplest field is
+just a name (which cannot contain any whitespace):
 
     color
 
 This yields a form with one text input field of the default size named `color'.
-The generated label for this field would be ``Color''. To add a longer or more\
+The generated label for this field would be ``Color''. To add a longer or more
 descriptive label, use:
 
@@ -1100,4 +1099,15 @@
     person*:text
 
+To create a C<radio> or C<select> field that includes an "other" option,
+append the string C<+other> to the field type:
+
+    position:select+other
+
+Or, to let FormBuilder decide whether to use radio buttons or a dropdown:
+
+    position+other
+
+Like growable fields, 'other' fields require FormBuilder 3.02 or higher.
+
 For the input types that can have options (C<select>, C<radio>, and
 C<checkbox>), here's how you do it:
@@ -1213,4 +1223,6 @@
 =head2 Language/Parser
 
+Deprecate the C<!field> directive
+
 Allow renaming of the submit button; allow renaming and inclusion of a 
 reset button
Index: trunk/lib/Text/FormBuilder/grammar
===================================================================
--- trunk/lib/Text/FormBuilder/grammar	(revision 73)
+++ trunk/lib/Text/FormBuilder/grammar	(revision 74)
@@ -146,5 +146,6 @@
 
 group_field: '!field' group_name name label(?)
-    { 
+    {
+	warn "[Text::FormBuilder] The !field directive has been DEPRECATED (input file line $thisline). Please use the name:GROUP style";
 	push @lines, [ 'group', { name => $item{name}, label => $item{'label(?)'}[0], group => $item{group_name} } ];
     }
@@ -154,5 +155,5 @@
 field_group: name label(?) hint(?) group_type comment(?)
     {
-	warn "[$thisline] comment = $item{'hint(?)'}[0]\n" if $item{'hint(?)'}[0];
+	#warn "[$thisline] comment = $item{'hint(?)'}[0]\n" if $item{'hint(?)'}[0];
 	#warn "[$thisline] field $item{name} is $item{group_type}\n";
 	push @lines, [ 'group', {