Diff of /PDL/Book/PP.pod [8a974e] .. [99decf] Maximize Restore

  Switch to side-by-side view

--- a/PDL/Book/PP.pod
+++ b/PDL/Book/PP.pod
@@ -33,20 +33,18 @@
 I will use L<Inline::Pdlpp> for all of my examples, including this first
 one. If you need help getting L<Inline::Pdlpp> to work, see Appendix A.
-PP code generally consists of a collection of function declarations
-that produce new Perl functions in the "PDL" package.  Each declaration is
-implemented by a (Perl language) call to a PDL::PP method such as C<pp_def>,
-that sets up data structures within the PDL::PP module.  The makefile 
-ultimately causes these data structures to be emitted as both Perl code and as
-C/PerlXS code, then to be compiled and linked to create the operator in the
-PDL package.
+The contents of the L<Inline::Pdlpp> is no more than a Perl script that
+calls special functions defined in the L<PDL::PP> module. The final
+result of this Perl script are a Perl module (.pm file) and a Perl
+extension (.xs file). The latter gets expanded to C code and compiled
+to produce XSUBs that ultimately end up as methods in the PDL package.
 C<pp_def> accepts a collection of parameters that describe both the 
-way the new operator should interact with the threading engine (e.g.
+way the new method should interact with the threading engine (e.g.
 its dimensional signature and which data types it should support natively),
-and also the code for the core of the 
-=head2 Getting Started 
+and also the code for the core of the method.
+=head3 First Example
 Let's begin with a variation on the canonical Hello World.
@@ -265,7 +263,7 @@
 expression C<$a()>, and the value in C<b> with C<$b()>. Also notice that I
 can use those values in an arithmetic expression.
-=head2 Returning Values
+=head3 Returning Values
 The examples I have used have all demonstrated their behavior by printing
 out their results to STDOUT. If you are like me, you will be glad to know
@@ -400,6 +398,12 @@
 capability, can you guess why PDL lets you do this?
+=head2 Higher Dimensional Functions
+So far I have shown how to write rudimentary functions that accept
+zero-dimensional piddles. In this section, I will explain how to write
+functions that accept higher-dimensional data.
 =head3 Specifying Dimensions and Using Explicit Looping
@@ -551,6 +555,8 @@
 one-dimensional piddle, it returns a single result with the sum of all the
 elements. The calculation on C<$b> treats each row as a vector and performs
 the calculation on each row.
+=head3 Matrix-Matrix Multiplication
 Let's look at another example, matrix-matrix multiplication. (You remember
 how to do matrix-matrix multiplication, right? No? Brush-up on
@@ -625,6 +631,8 @@
 Oops! You can see that PDL considers the first argument to the number of
 columns, not the number of rows! I'll let you fix that in an exercise.
+=head3 Threadloops
 PDL::PP also has the C<threadloop> construct, which lets you declare the
 code over which PDL should thread, and the code that should come before
 and after the thread loop. Here's a simple example demonstrating the
@@ -745,6 +753,8 @@
 They are also handy if you need to perform a particularly expensive calculation
 once each time the function is invoked.
+=head3 A Complex Example
 To put this all together, I am going to consider writing a PDL::PP function
 that computes the first numerical derivative of a time series. You can read
@@ -919,7 +929,7 @@
-=head3 Tips
+=head2 Tips
 These are a couple of things I have learned which help me make effective use
 of PDL::PP, but which did not sensibly fit elsewhere.