[PD] standard library (was Re: [PD-announce] Pd-extended 0.43.4 released!)

[Jonathan Wilkes]

----- Original Message -----
> From: Hans-Christoph Steiner <hans at at.or.at>
> To: Jonathan Wilkes <jancsika at yahoo.com>
> Cc: "pd-list at iem.at" <pd-list at 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:
1) 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