On 2004-12-30, at 09:35:28 +0100, H.Merijn Brand wrote:
On Wed 29 Dec 2004 21:37, Stas Bekman <[EMAIL PROTECTED]> wrote:
Marcus Holland-Moritz wrote:
On 2004-12-29, at 12:44:11 -0500, Stas Bekman wrote:
Marcus Holland-Moritz wrote:
On 2004-12-29, at 14:45:44 +0100, Marcus Holland-Moritz wrote: I'll mention it in perlhack. Let me know if you have any suggestions.
How about adding it at the top of perlapi.pod (or at least a pointer to perlhack where the full details are given).
Thinking about it, I guess something like perlxstut is a more appropriate place than perlhack. I wanted to add a section on Devel::PPPort to perlxstut anyway.
I think perlguts is more appropriate, since not everybody uses XS (e.g. embed perl)
/me agrees on this
What about this?
--- perlguts.pod.orig 2004-12-30 11:45:30.000000000 +0100
+++ perlguts.pod 2004-12-30 12:06:08.000000000 +0100
@@ -2283,6 +2283,19 @@
Please try and supply some documentation if you add functions to the
Perl core.
+=head2 Backwards compatibility
+
+The Perl API changes over time. New functions are added or the interfaces
+of existing functions are changed. The C<Devel::PPPort> module tries to
+provide compatibility code for some of these changes, so XS writers don't
+have to code it themselves when supporting multiple versions of Perl.
+
+C<Devel::PPPort> generates a C header file F<ppport.h> that can also
+be run as a Perl script. Besides checking existing XS code, this script
+can also be used to retrieve compatibility information for various API
+calls using the C<--api-info> command line switch. For details, see
+L<Devel::PPPort>.
+
The end is not good. Devel::PPPort doesn't explain how to use ppport.h, and directs to the perldoc of the latter (double indirect is not very friendly). And the latter doesn't give any examples on how this is used. So I suggest to change the last para to:
---------- <Devel::PPPort> generates a C header file F<ppport.h> that can also be run as a Perl script. Besides checking existing XS code, this script can also be used to retrieve compatibility information for various API calls using the C<--api-info> command line switch. For example:
% perl ppport.h --api-info=sv_magicext
For details, see C<perldoc ppport.h>. ----------
I've used "C<perldoc ppport.h>" since it's not obvious that ppport.h doc should be viewed with perldoc. With that change, one most likely doesn't even need to go and read any extra docs, since the example is sufficient.
Also I think it'd be an improvement to include this:
--- ext/Devel/PPPort/PPPort_pm.PL.orig 2004-12-30 10:01:45.797743528 -0500 +++ ext/Devel/PPPort/PPPort_pm.PL 2004-12-30 10:02:13.662977253 -0500 @@ -379,7 +379,7 @@ notes, and can even make suggestions on how to change your code. You can run it like any other Perl program:
- perl ppport.h + perl ppport.h [options] [files]
It also has embedded documentation, so you can use
-- __________________________________________________________________ Stas Bekman JAm_pH ------> Just Another mod_perl Hacker http://stason.org/ mod_perl Guide ---> http://perl.apache.org mailto:[EMAIL PROTECTED] http://use.perl.org http://apacheweek.com http://modperlbook.org http://apache.org http://ticketmaster.com
