----- Original Message -----
From: Hans-Christoph Steiner hans@at.or.at To: Jonathan Wilkes jancsika@yahoo.com Cc: "pd-list@iem.at" pd-list@iem.at Sent: Sunday, February 3, 2013 1:41 PM Subject: Re: [PD] standard library (was Re: [PD-announce] Pd-extended 0.43.4 released!)
[...]
If you want I can put together a Kickstarter campaign that outlines all of this doc work that will be needed. I suspect it'd be about two or three months of full-time work. If people are willing to pay me to make these changes I'm happy to do them. As my resume I offer my work on PDDP, in which I contacted lib authors to accept my revisions, updated core docs, reworked the FLOSS manual to be consistent with core docs, and wrote a search plugin to make use of all the changes. (As well as testing that the results worked across platforms.)
-Jonathan
These things are all true, I think its worth it. I think you might be thinking that there will be more changed than there need to be. Most of the objects would not need documentation changes, or just small changes.
Here's the doc work:
- search plugin - for classes that are copied into the new libs, don't show
duplicate results from the legacy library (which is only there for backwards compatability). Probably the best way to do this is add a "legacy" tag to the old lib stuff. 2) Change the relative pddp links for all 200+ PDDP help patches that points to stuff outside of 5.reference/ (probably can automate much of this process) 3) Find and change all the pddplinks and comments in docs of externals that refer to 5.reference (absolute and relative). (Somewhat automated) 4) Make a good faith effort to amend FLOSS references and other common PD learning materials to document new libs. (Otherwise new users read about legacy stuff while using new stuff, get confused, and write to the list to ask about why the same exact objects get different prefixes in different docs.) 5) Lots of iterative changes to places in the documentation that make a distinction between "internal" and "external" objects, including the search plugin, "all about Pd" patches, tutorials, the Pd manual, and probably a lot else that I'm not thinking of at the moment. 6) Create new documentation to explain _exactly_ how to use standard libs, explaining how to a) get the old behavior of just loading all libs in Pd-extended, b) how to use [import], c) how to use the lib prefix, and d) any other ways of loading libs and the benefits/drawbacks of those approaches. 7) Making a user-friendly doc or patch about legacy libs that explains the legacy author-oriented approach for new (and old) users, focusing esp. on the most popular legacy libs. Without this a lot of documentation on puredata.info-- and esp. on the user and dev list-- becomes difficult to understand and follow. 8) Find entry points into the common Pd learning materials and inject a note about the move from the legacy approach to the new approach, with a link to the doc from #7. 9) Keep a list of all easily translatable sources of documentation on this change, so that translations of the new approach can happen as soon as possible. 10) Check for cross-platform compatibility, to make sure none of the core doc changes or search-plugin changes introduce weirdness somewhere.
However, after doing some initial research I see there's a bigger issue before any of this could even happen. Let's say I put up a Kickstarter for a month's worth of doc work on this. I'd have to schedule it for a date after the work is done deciding what names the standard libs should get and what code goes in those libs.
That process will probably turn into bikeshedding where none of the real work actually gets done-- I can say this because _substantial_ preliminary discussions for this work already took place 4 years ago on the dev list and we don't have standard libs today.
So here's my proposition: I'll work on compiling a list of classes that should have been included in vanilla but aren't yet. I'll exclude objects which are currently in a maintained, "aptly-named" library build around classes that share some core functionality in common, as those libraries are already "standard libraries". I should end up with a list of classes which, in conjunction with the vanilla classes, make it possible to get substantially more work done without relying on hacks or workarounds. We can worry about libname and relationship with vanilla later-- the main point will be that these "core" objects can all be typed into an object box in Pd extended, without any namespace prefixes, and as long as nothing has been [import]ed or [declare]d it should all just work. If it goes the way I think it will, there won't be any need to have a bunch of new libs, just one that adds long-desired functionality to "vanilla" that's been missing for so long. None of this initial work requires any discussion whatsoever, since it all exists already on the user and dev lists. So this way we can avoid the bikeshedding. BTW-- I assume copying the classes to the new "standard lib" will be automated with a script. Or are you proposing keeping copies of the code in two locations? -Jonathan