On 7/11/2010 4:31 AM, Daniel Carrera wrote: > >> * Tips and Suggestions: not really a tutorial > > Yeah. And neither is Philosophy. But they are not references either. > They fit better under Tutorial than Reference.
Maybe a Tips and Suggestions section? Isn't there a section on the wiki with cookbooks with PDL that would fall under the same category? >> * Object Orientation: not a tutorial and definitely not >> complete. Are we keeping a list of things needing updates? > > A lot of modules need updates. I haven't kept track. Should I just > remove it entirely? I think I'll remove it entirely. I would move it to the advanced section since it is definitely important reading if you want to subclass from PDL. Keep the "work in progress" note there. >> * 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. You had me at "No no no". :-) If it doesn't cost too much, how about putting that link at the top of all the top level doc pages. Tutorial users and Reference searchers can use the reminder. >> * 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 comment was only for the minor heading rename. We've already had a lot of discussion about module structure. I was pointing out that from a user's point of view, how to drive PDL is of much more relevance than what the engine components are under the hood (the perl modules of the implementation). >> * I would add a Fundamental category in the reference docs >> as well. The Perldl or Perldl2 shell is key for new users. >> The PDL::Core is the lowest level piddle support---more like >> unix/linix kernel functions rather than "beginner"ones. > > A fundamental problem is that the PDL docs themselves are *not* > organized with a view to what users need. The first function users > need to learn is "pdl" and that is in PDL::Core, but the rest of > PDL::Core is "advanced". > > Would you move PDL::Core to the "Advanced" section and leave the user > to learn about the "pdl" function from the tutorials? Again, this was about substituting Fundamentals for Beginner and not about restructuring modules to make the reference pages turn into optimal user level refs. >> * Breaking out External Library for the Numerical Methods >> and Images seems confusing to me. From a users point of >> view, the important thing is the functionality and that >> the module may or may not work unless PDL has been built >> to support it. > > Ok. But the ones that use an external library might require an > additional installation step. No? What would you do about that? > Imagine how frustrating it would be if you couldn't predict which > modules will work reliably and which ones will work in some computers > and not others depending on what other libraries they have installed. > How would you solve this problem? I think you lose a lot by not having the functional grouping. For example FFT and FFTW both calculate the FFT. Splitting them up means someone may end up using the slower internal routine even if they have installed the FFTW version. The key thing about modules with external dependencies is that they are *optional* . The PDL build will try its best but the result is either installed or not at the end. Maybe something like: Fast Fourier Transform: PDL::FFT PDL::FFTW (optional) PDL::Lib::GSL::FFT (optional) A second thing about optional modules is how to determine whether you have them. The simplest might be to check the %PDL::Config hash. Once the baseline PDL is working, we could make that simpler. > >> * PDL::MatrixOps is the most primitive matrix ops module >> in PDL. PDL::Matrix just wraps things up so folks can >> use column major syntax. > > Ok. How do you think I should organize them? In the documentation I > mention PDL::Matrix first. > > >> * Develop with Git definitely needs a link to the sf.net >> browse the git repository. > > What's the URL? The FAQ doesn't say anything. Top level PDL projects page at sf.net: http://sourceforge.net/projects/pdl/ Bugs tracker at sf.net: http://sourceforge.net/tracker/?group_id=612&atid=100612 Feature request tracker at sf.net: http://sourceforge.net/tracker/?group_id=612&atid=350612 PDL git page on sf.net: http://sourceforge.net/scm/?type=git&group_id=612 Browse PDL git repository at sf.net: http://pdl.git.sourceforge.net/ > >> * Would be much less confusing if the Develop with Git >> actually explained how to develop with git. Any explanation >> is delayed until Hg is thrown in the mix. I think Hg may >> be nicer than git in some respects but it is confusing to >> new developers to present them both as if they were on an >> equal footing. Nothing is wrong with Hg. The current presentation is like going to a Honda dealer to buy an Accord and having all your questions answered regarding the Accord and the Element. Hard to keep things straight and more confusing than necessary for new users. > I don't see what's wrong with Hg. You can use Hg to develop with PDL > and it is perfectly transparent. I was actually thinking about adding > Bazaar too (but bzr-git doesn't do "push"). It's like if a project > uses Subversion and they welcome Git users and points them to git-svn. > I don't see your point of "equal footing", if it works then it works. > You don't raise an issue with my choice of operating system or text > editor because this is all transparent for you. > > Anyway, I did try several ways of writing this page. Initially I had > Git and Hg completely separate, but I wasn't impressed with the > results. I tested several of my rewrites on my wife, who is definitely > a new user, and the version she found easiest to read is the one > currently on the website. She did not think it was confusing at all, > she thought it was the clearest version. Keeping the clarity focused on git seems the most helpful and important. > Lastly, I wouldn't want to just remove Hg entirely. I would rather > welcome all users, even those who do not prefer Git, and I would > emphasize that you can use whatever makes you happy as long as it > works and integrates with the project seamlessly. I think the main page on PDL development should help users to work with git. At the bottom, I suggest, along the lines you mentioned "Other ways of working with Git" where you would link to Hg,... > >> * Please put a direct reference to the PDL sf.net page and >> a link to Feature Requests tracker. > > By the sf.net page, do you mean pdl.sourceforge.net? Why? That's just > a redirect now. Nope, not the PDL project web page, the sf.net project pages. Links above already. > Can you give me a link to the Feature Requests tracker? How is it > different from the bug tracker I already link to? Done. --Chris _______________________________________________ Perldl mailing list [email protected] http://mailman.jach.hawaii.edu/mailman/listinfo/perldl
