perldelta: put some things in C<> tags

[perl5.git] / pod / perlxs.pod

diff --git a/pod/perlxs.pod b/pod/perlxs.pod
index c2cae22..5acc4de 100644 (file)
--- a/pod/perlxs.pod
+++ b/pod/perlxs.pod
@@ -74,7 +74,7 @@ See L<perlxstut> for a tutorial on the whole extension creation process.
 
 Note: For some extensions, Dave Beazley's SWIG system may provide a
 significantly more convenient mechanism for creating the extension
-glue code.  See http://www.swig.org/ for more information.
+glue code.  See L<http://www.swig.org/> for more information.
 
 =head2 On The Road
 
@@ -293,7 +293,7 @@ or less equivalent:
           ST(0) = newSVpv("Hello World",0);
           sv_2mortal(ST(0));
           XSRETURN(1);
-  
+
   SV *
   beta()
       CODE:
@@ -319,7 +319,7 @@ CPAN modules) in the typemap file, the reference count of the C<AV *>
 is not properly decremented. Thus, the above XSUB would leak memory
 whenever it is being called. The same problem exists for C<HV *>.
 
-When you're returning an C<AV *> or a C<HV *>, you have make sure
+When you're returning an C<AV *> or a C<HV *>, you have to make sure
 their reference count is decremented by making the AV or HV mortal:
 
   AV *
@@ -1211,6 +1211,12 @@ To disable version checking:
 
     VERSIONCHECK: DISABLE
 
+Note that if the version of the PM module is an NV (a floating point
+number), it will be stringified with a possible loss of precision
+(currently chopping to nine decimal places) so that it may not match
+the version of the XS module anymore. Quoting the $VERSION declaration
+to make it a string is recommended if long version numbers are used.
+
 =head2 The PROTOTYPES: Keyword
 
 The PROTOTYPES: keyword corresponds to B<xsubpp>'s C<-prototypes> and
@@ -1330,7 +1336,7 @@ where FALLBACK can take any of the three values TRUE, FALSE, or
 UNDEF.  If you do not set any FALLBACK value when using OVERLOAD,
 it defaults to UNDEF.  FALLBACK is not used except when one or 
 more functions using OVERLOAD have been defined.  Please see
-L<overload/Fallback> for more details.
+L<overload/fallback> for more details.
 
 =head2 The INTERFACE: Keyword
 
@@ -1428,10 +1434,26 @@ The XS module can use INCLUDE: to pull that file into it.
     INCLUDE: Rpcb1.xsh
 
 If the parameters to the INCLUDE: keyword are followed by a pipe (C<|>) then
-the compiler will interpret the parameters as a command.
+the compiler will interpret the parameters as a command. This feature is
+mildly deprecated in favour of the C<INCLUDE_COMMAND:> directive, as documented
+below.
 
     INCLUDE: cat Rpcb1.xsh |
 
+Do not use this to run perl: C<INCLUDE: perl |> will run the perl that
+happens to be the first in your path and not necessarily the same perl that is
+used to run C<xsubpp>. See L<"The INCLUDE_COMMAND: Keyword">.
+
+=head2 The INCLUDE_COMMAND: Keyword
+
+Runs the supplied command and includes its output into the current XS
+document. C<INCLUDE_COMMAND> assigns special meaning to the C<$^X> token
+in that it runs the same perl interpreter that is running C<xsubpp>:
+
+    INCLUDE_COMMAND: cat Rpcb1.xsh
+
+    INCLUDE_COMMAND: $^X -e ...
+
 =head2 The CASE: Keyword
 
 The CASE: keyword allows an XSUB to have multiple distinct parts with each
@@ -1796,7 +1818,7 @@ OUTPUT code fragments should be used to map a given C type to a Perl value.
 The section labels C<TYPEMAP>, C<INPUT>, or C<OUTPUT> must begin
 in the first column on a line by themselves, and must be in uppercase.
 
-The default typemap in the C<lib/ExtUtils> directory of the Perl source
+The default typemap in the F<lib/ExtUtils> directory of the Perl source
 contains many useful types which can be used by Perl extensions.  Some
 extensions define additional typemaps which they keep in their own directory.
 These additional typemaps may reference INPUT and OUTPUT maps in the main
@@ -1939,7 +1961,7 @@ and the module version number.
 
 =item typedef my_cxt_t
 
-This struct typedef I<must> always be called C<my_cxt_t> -- the other
+This struct typedef I<must> always be called C<my_cxt_t>. The other
 C<CXT*> macros assume the existence of the C<my_cxt_t> typedef name.
 
 Declare a typedef named C<my_cxt_t> that is a structure that contains
@@ -1958,10 +1980,10 @@ of C<my_cxt_t>.
 
 The MY_CXT_INIT macro initialises storage for the C<my_cxt_t> struct.
 
-It I<must> be called exactly once -- typically in a BOOT: section. If you
+It I<must> be called exactly once, typically in a BOOT: section. If you
 are maintaining multiple interpreters, it should be called once in each
 interpreter instance, except for interpreters cloned from existing ones.
-(But see C<MY_CXT_CLONE> below.)
+(But see L<MY_CXT_CLONE> below.)
 
 =item dMY_CXT