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

muppet wrote:

If i'm reading 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.
---   (revision 1092)
+++   (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} }
                                                 : ());
-                       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;

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]