On 2004-12-30, at 10:03:03 -0500, Stas Bekman wrote:
> Marcus Holland-Moritz wrote:
> > 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.
Right, I've added a couple of examples to the docs.
> 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>.
> ----------
Yes, that makes sense.
> 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.
I've also added the command line needed to generate a ppport.h.
> 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
Yup, also integrated into my development version.
Thanks Stas!
--
Chemicals, n.:
Noxious substances from which modern foods are made.
