Re: [PATCH] fix POD generation with COPYRIGHT section in source

[Torsten Schoenfeld <kaffeetisch gmx de>]

muppet wrote:
> > <fix-pod-generation-for-copyright.txt>
>
> If i'm reading GenPod.pm correctly, then i don't think this is right.
>
> xsdoc2pod() opens a whole bunch of sections, and the =cut is meant to 
> close them all.  I see that the docs say "replace the generated 
> COPYRIGHT section completely", but i don't think this is intended to 
> mean "so you should add your own =cut".  In other words, i think it's 
> wrong for the copyright text to include a =cut of its own.
>
> In fact, i don't see a =cut in Gnome2::Canvas's Makefile.PL.

I think the problem occurs due to the "=for position COPYRIGHT" in 
xs/GnomeCanvas.xs.  It's handled by Glib::GenPod::podify_pods() which means that 
the whole POD paragraph is returned, including the leading "=for" and the 
trailing "=cut".  So we get a double "=cut" for modules with such a "=for 
position COPYRIGHT" directive[1].

[1] Only Gnome2::Canvas and Gtk2::GLExt, as far as I can tell.

> So, while not having your patch breaks for some modules, i imagine 
> adding your patch might break for other modules.

Yeah.  I think one solution would be to always output complete POD paragraphs 
with a trailing "=cut", instead of relying on one final "=cut".  As in the 
attached patch.  It fixes the Gnome2::Canvas problem while apparently not 
breaking anything else.
Index: GenPod.pm
===================================================================
--- GenPod.pm   (revision 1092)
+++ GenPod.pm   (working copy)
@@ -272,9 +272,12 @@ sub xsdoc2pod
                        blurb => $pkgdata->{blurb},
                };
 
+               # podify_pods() always returns proper POD with a =cut at the
+               # end.  But all the other =head1 below need a closing =cut.
+
                print "=head1 NAME\n\n$package";
                print ' - '.$pkgdata->{blurb} if (exists ($pkgdata->{blurb}));
-               print "\n\n";
+               print "\n\n=cut\n\n";
 
                #                   pods            , position 
                $ret = podify_pods ($pkgdata->{pods}, 'SYNOPSIS');
@@ -285,13 +288,13 @@ sub xsdoc2pod
                
                my $parents;
                ($ret, $parents) = podify_ancestors ($package);
-               print "=head1 HIERARCHY\n\n$ret" if ($ret);
+               print "=head1 HIERARCHY\n\n$ret\n\n=cut\n\n" if ($ret);
                
                $ret = podify_pods ($pkgdata->{pods}, 'post_hierarchy');
                print "$ret\n\n" if ($ret);
                
                $ret = podify_interfaces ($package);
-               print "=head1 INTERFACES\n\n$ret" if ($ret);
+               print "=head1 INTERFACES\n\n$ret\n\n=cut\n\n" if ($ret);
                
                $ret = podify_pods ($pkgdata->{pods}, 'post_interfaces');
                print "$ret\n\n" if ($ret);
@@ -300,28 +303,28 @@ sub xsdoc2pod
                print "$ret\n\n" if ($ret);
 
                $ret = podify_deprecated_by ($package, @{ $pkgdata->{deprecated_bys} });
-               print "\n=head1 DEPRECATION WARNING\n\n$ret" if ($ret);
+               print "\n=head1 DEPRECATION WARNING\n\n$ret\n\n=cut\n\n" if ($ret);
 
                $ret = podify_methods ($package, $pkgdata->{xsubs});
-               print "\n=head1 METHODS\n\n$ret" if ($ret);
+               print "\n=head1 METHODS\n\n$ret\n\n=cut\n\n" if ($ret);
                
                $ret = podify_pods ($pkgdata->{pods}, 'post_methods');
                print "$ret\n\n" if ($ret);
 
                $ret = podify_properties ($package);    
-               print "\n=head1 PROPERTIES\n\n$ret" if ($ret);
+               print "\n=head1 PROPERTIES\n\n$ret\n\n=cut\n\n" if ($ret);
 
                $ret = podify_pods ($pkgdata->{pods}, 'post_properties');
                print "$ret\n\n" if ($ret);
 
                $ret = podify_signals ($package);       
-               print "\n=head1 SIGNALS\n\n$ret" if ($ret);
+               print "\n=head1 SIGNALS\n\n$ret\n\n=cut\n\n" if ($ret);
 
                $ret = podify_pods ($pkgdata->{pods}, 'post_signals');
                print "$ret\n\n" if ($ret);
 
                $ret = podify_enums_and_flags ($pkgdata, $package);     
-               print "\n=head1 ENUMS AND FLAGS\n\n$ret" if ($ret);
+               print "\n=head1 ENUMS AND FLAGS\n\n$ret\n\n=cut\n\n" if ($ret);
 
                $ret = podify_pods ($pkgdata->{pods}, 'post_enums');
                print "$ret\n\n" if ($ret);
@@ -342,7 +345,7 @@ sub xsdoc2pod
                                                 $pkgdata->{see_alsos}
                                                 ? @{ $pkgdata->{see_alsos} }
                                                 : ());
-                       print "\n=head1 SEE ALSO\n\n$ret" if ($ret);
+                       print "\n=head1 SEE ALSO\n\n$ret\n\n=cut\n\n" if ($ret);
                }
 
                $ret = podify_pods ($pkgdata->{pods}, 'COPYRIGHT');
@@ -355,11 +358,9 @@ sub xsdoc2pod
                {
                        # use normal copyright system
                        $ret = get_copyright ();
-                       print "\n=head1 COPYRIGHT\n\n$ret" if ($ret);
+                       print "\n=head1 COPYRIGHT\n\n$ret\n\n=cut\n\n" if ($ret);
                }
 
-               print "\n=cut\n\n";
-
                close POD;
        }