fix quoting in t/io/inplace.t
[p5sagit/p5-mst-13.2.git] / pod / perlxstut.pod
index 501a348..867d42a 100644 (file)
@@ -25,21 +25,21 @@ features were added to Perl 5.
 
 =item *
 
-In versions of 5.002 prior to the gamma version, the test script in Example
-1 will not function properly.  You need to change the "use lib" line to
-read:
+In versions of Perl 5.002 prior to the gamma version, the test script
+in Example 1 will not function properly.  You need to change the "use
+lib" line to read:
 
        use lib './blib';
 
 =item *
 
-In versions of 5.002 prior to version beta 3, the line in the .xs file
+In versions of Perl 5.002 prior to version beta 3, the line in the .xs file
 about "PROTOTYPES: DISABLE" will cause a compiler error.  Simply remove that
 line from the file.
 
 =item *
 
-In versions of 5.002 prior to version 5.002b1h, the test.pl file was not
+In versions of Perl 5.002 prior to version 5.002b1h, the test.pl file was not
 automatically created by h2xs.  This means that you cannot say "make test"
 to run the test script.  You will need to add the following line before the
 "use extension" statement:
@@ -55,7 +55,7 @@ to use the following line:
 
 =item *
 
-This document assumes that the executable named "perl" is Perl version 5.  
+This document assumes that the executable named "perl" is Perl version 5.
 Some systems may have installed Perl version 5 as "perl5".
 
 =back
@@ -145,7 +145,7 @@ And the Mytest.xs file should look something like this:
        #ifdef __cplusplus
        }
        #endif
-       
+
        PROTOTYPES: DISABLE
 
        MODULE = Mytest         PACKAGE = Mytest
@@ -185,11 +185,11 @@ example only, we'll create a special test script.  Create a file called hello
 that looks like this:
 
        #! /opt/perl5/bin/perl
-       
+
        use ExtUtils::testlib;
-       
+
        use Mytest;
-       
+
        Mytest::hello();
 
 Now we run the script and we should see the following output:
@@ -222,7 +222,7 @@ the four lines starting at the "CODE:" line to not be indented.  However,
 for readability purposes, it is suggested that you indent them 8 spaces
 (or one normal tab stop).
 
-Now re-run make to rebuild our new shared library.
+Now rerun make to rebuild our new shared library.
 
 Now perform the same steps as before, generating a Makefile from the
 Makefile.PL file, and running make.
@@ -428,7 +428,7 @@ Let's now take a look at a portion of the .c file created for our extension.
                } else {
                        arg = 0.0;
                }
-               sv_setnv(ST(0), (double)arg);   /* XXXXX */
+               sv_setnv(ST(0), (double)arg);           /* XXXXX */
            }
            XSRETURN(1);
        }
@@ -452,8 +452,8 @@ this behavior is tolerated.  The next example will show how to do this.
 
 =head2 EXAMPLE 4
 
-In this example, we'll now begin to write XSUB's that will interact with
-pre-defined C libraries.  To begin with, we will build a small library of
+In this example, we'll now begin to write XSUBs that will interact with
+predefined C libraries.  To begin with, we will build a small library of
 our own, then let h2xs write our .pm and .xs files for us.
 
 Create a new directory called Mytest2 at the same level as the directory
@@ -475,7 +475,7 @@ Also create a file mylib.c that looks like this:
 
        #include <stdlib.h>
        #include "./mylib.h"
-       
+
        double
        foo(a, b, c)
        int             a;
@@ -490,12 +490,13 @@ And finally create a file Makefile.PL that looks like this:
        use ExtUtils::MakeMaker;
        $Verbose = 1;
        WriteMakefile(
-           'NAME' => 'Mytest2::mylib',
-           'clean'     => {'FILES' => 'libmylib.a'},
+           NAME      => 'Mytest2::mylib',
+           SKIP      => [qw(all static static_lib dynamic dynamic_lib)],
+           clean     => {'FILES' => 'libmylib$(LIB_EXT)'},
        );
 
 
-       sub MY::postamble {
+       sub MY::top_targets {
                '
        all :: static
 
@@ -528,12 +529,13 @@ and a new replacement subroutine too:
        sub MY::postamble {
        '
        $(MYEXTLIB): mylib/Makefile
-               cd mylib && $(MAKE)
+               cd mylib && $(MAKE) $(PASTHRU)
        ';
        }
 
 (Note: Most makes will require that there be a tab character that indents
-the line "cd mylib && $(MAKE)".)
+the line C<cd mylib && $(MAKE) $(PASTHRU)>, similarly for the Makefile in the
+subdirectory.)
 
 Let's also fix the MANIFEST file so that it accurately reflects the contents
 of our extension.  The single line that says "mylib" should be replaced by
@@ -703,7 +705,7 @@ definition is placed.
 
 There is absolutely no excuse for not documenting your extension.
 Documentation belongs in the .pm file.  This file will be fed to pod2man,
-and the embedded documentation will be converted to the man page format,
+and the embedded documentation will be converted to the manpage format,
 then placed in the blib directory.  It will be copied to Perl's man
 page directory when the extension is installed.
 
@@ -716,7 +718,7 @@ See L<perlpod> for more information about the pod format.
 =head2 INSTALLING YOUR EXTENSION
 
 Once your extension is complete and passes all its tests, installing it
-is quite simple: you simply run "make install".  You will either need 
+is quite simple: you simply run "make install".  You will either need
 to have write permission into the directories where Perl is installed,
 or ask your system administrator to run the make for you.
 
@@ -727,7 +729,7 @@ and L<perlpod>.
 
 =head2 Author
 
-Jeff Okamoto E<lt>F<okamoto@corp.hp.com>E<gt>
+Jeff Okamoto <F<okamoto@corp.hp.com>>
 
 Reviewed and assisted by Dean Roehrich, Ilya Zakharevich, Andreas Koenig,
 and Tim Bunce.