On Sun, Jul 11, 2010 at 3:31 AM, Daniel Carrera <[email protected]> wrote: .. > > On Sun, Jul 11, 2010 at 1:39 AM, Chris Marshall <[email protected]> wrote: .. >> * I suggest a bit more detail in "How do I search for a function?" >> and move it to the tutorials page. > > No no no. Let me explain. Imagine you are just learning PDL. When you > go to the "Reference" page, you are not planning to look up a module. > You don't even *know* the modules. You are most likely planning to > look up a function. When you see "Reference" you are probably > expecting a *function* reference. > > > The beginner user is coming to this page thinking "I bet PDL has a > cosine function, I want to look it up". But the Reference page will > not give him what he wants. He'll see a bunch of modules and will > frustratingly start clicking on modules... PDL::Basic, PDL::Primitive, > PDL::Func (hey, cosine is a useful function, right?), and so on. Often > he has to read the whole module doc before figuring out that this is > not what they want.
I concur. One of the most useful pages for me in the world of Perl is http://perldoc.perl.org/index-functions.html as it would help me look up a function no matter where that function resides. I find subject-wise indexing to be confusing. A simple, alphabetical, non-intelligent index is the best (for the same reason a surrogate PRIMARY KEY in a db is much better than a natural key). One person's intelligence is another person's confusion.Let me give an analogy using "Yellow Pages." I want to find a taxi. I have no idea if I should look under "Cabs" or "Taxis" or "Taxi Cabs" or "Cars" or "Auto" or "Car Rentals" or "Auto Rentals," etc. Even if there is a list of functions categorized by capability, or modules, or whatever, a simple, alphabetical, non-intelligent index will be incredibly useful, because I, as n00b, have no way of knowing whether $a->glue is in Core, or Basic or Primitive or Indexing or Slices or whatever. > > I am giving these users a way out. When a user goes to this page > expecting a function reference, the first link they'll see explains > how to get what they were really looking for when they came in. > > >> * The items in PDL Reference Documentation might better be >> termed PDL Modules Reference Documentation. From a user >> point of view, I think the references should be around >> features for using PDL to calculate and solve problems >> and not the breakdown of the Perl modules for implementation. > > The page *IS* divided around features: Graphics, IO, Image Processing, > Numerical Methods, etc. What more do you want? What more *can* I do? > > Please remember that what we had before was an *ALPHABETICAL* listing > of all Perl modules!! I have gone through this list and separated (1) > pages that are not modules at all (2) pages that are so incomplete or > low-level that they shouldn't be listed, (3) pages that are > "foundation" or "advanced". Of the remaining pages, I spent days > dividing them into meaningful categories. > The meaningful categories are definitely useful for modules. But, is there a way to create an alphabetical listing of *all* the functions in *all* the modules? Each function entry can then point to the specific module they reside in. This could be modeled exactly like the perldoc perl functions index, something like so -- A ==== append ----------- PDL::Primitive append two or more piddles by concatenating along their first dimensions $a = ones(2,4,7); $b = sequence 5; $c = $a->append($b); # size of $c is now (7,4,7) (a jumbo-piddle ;) "append" appends two piddles along their first dims. Rest of the dimensions must be compatible in the threading sense. Resulting size of first dim is the sum of the sizes of the first dims of the two argument piddles - ie "n + m". Similar functions include glue (below) and cat. append does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles. For more information, see /usr/local/lib/perl5/site_perl/5.12.1/darwin-2level/PDL/Primitive.pm average ----------- Module PDL::Ufunc Signature: (a(n); int+ [o]b()) Project via average to N-1 dimensions This function reduces the dimensionality of a piddle by one by taking the average along the 1st dimension. By using xchg etc. it is possible to use *any* dimension. $a = average($b); $spectrum = average $image->xchg(0,1) average does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles. Docs from /usr/local/lib/perl5/site_perl/5.12.1/darwin-2level/PDL/Ufunc.pm .. -- Puneet Kishor _______________________________________________ Perldl mailing list [email protected] http://mailman.jach.hawaii.edu/mailman/listinfo/perldl
