On Mon, Apr 19, 2010 at 4:21 PM, David Mertens <[email protected]> wrote: > On Mon, Apr 19, 2010 at 1:52 PM, P Kishor <[email protected]> wrote: >> >> Breaking this thread into what should have been two threads to begin >> with... >> >> >> On Mon, Apr 19, 2010 at 1:45 PM, Judd Taylor <[email protected]> >> wrote: >> .. >> > >> > As far as documentation problems, it sounds like something went wrong >> > with your build of the .pd file, which autogenerates most of the OO >> > functions, and autogenerates the documentation as well. The PDL online >> > docs don't show any placeholders as you describe: >> > http://pdl.sourceforge.net/PDLdocs/IO/GD.html >> > >> >> Man, I never even considered looking at the above link. I usually just go >> to search.cpan.org, and that is where I see all the documentation gaps. See >> for yourself... >> <http://search.cpan.org/~chm/PDL-2.4.6/IO/GD/GD.pd> >> >> The link you sent me at pdl.sf.net is indeed way more comprehensive. >> >> To the maintainers... is there a reason we have two locations for PDL >> stuff... cpan and sf? Can't they be merged, so when I say "tomahto" >> you don't understand "tomayto"? > > Yes. The reason is because PDL::PP does a lot of documentation generation > for its authors. It was written with pdldoc - not CPAN - in mind. By the > time you try perldoc or pdldoc, all of the .pd files have been procesed and > you get pretty output. Anyway, this has led to a whole lot of documentation > that displays correctly with perldoc and pdldoc (and Padre), but not on > CPAN. It turns out that you can put in all sorts of things into the .pd > file by hand that will make it display properly, but nobody has endeavored > to do this for the bulk of PDL. As my first project to fix this, I tackled > PDL::Slices, and you can compare the results. For best contrast, look near > the bottom of the pages: > > http://search.cpan.org/~chm/PDL-2.4.6_001/Basic/Slices/slices.pd (corrected) > http://search.cpan.org/~chm/PDL-2.4.5/Basic/Slices/slices.pd (old) > > I started working on PLplot but got sidetracked. I've had a mind to write up > how to clean up the old documentation and write new PDL documentation > guidelines, but I've not gotten around to it. For now, the rule of thumb is > this: use your local copy of the documentation (which for me displays > beautifully in Padre) or use the documentation generated for Sourceforge.
Sorry, Padre is not an option for me. I could never get it to work on my Mac, and the purported rewards from installing it are simply not high enough for me to justify bearing the pain. I tried to install it from source, and found that I needed a threaded perl. I installed a threaded perl and failed in installing Padre even then. Then I found a binary .dmg for Macs on the Padre web site, downloaded it, but it crashes on every invocation. I informed the folks on Padre IRC, but no one responded. I go back to my stable Coda or TextWrangler. pdldoc, on the other hand, is an interesting option, but I would prefer an htmlized version locally on my machine for my disconnected viewing pleasure. Yes, now that I know I can use sf.net, but can I generate the real pdl docs as html on my own laptop? > All sorts of people new to PDL will look on CPAN and will be confused until > it's fixed. I know it's a problem and I'm slowly working on it. Sorry I've > not covered more ground. > > David -- Puneet Kishor http://www.punkish.org Carbon Model http://carbonmodel.org Charter Member, Open Source Geospatial Foundation http://www.osgeo.org Science Commons Fellow, http://sciencecommons.org/about/whoweare/kishor Nelson Institute, UW-Madison http://www.nelson.wisc.edu ----------------------------------------------------------------------- Assertions are politics; backing up assertions with evidence is science ======================================================================= _______________________________________________ Perldl mailing list [email protected] http://mailman.jach.hawaii.edu/mailman/listinfo/perldl
