[PD] Re: Mac OS X installer with library documentation

[B. Bogart]

Hey all,

I proposed a few things on pd-dev a while back.

I think we really do need to revaluate the doc/ structure and make it
standard.

I think the best solution for the help menu is to have the hierarhcy
generated directly from the directories in the doc/ folder. The build
scripts will put the reference/docs in standard places, and when those
are installed they will automagically come up in the help menu.

Your structure is very similar to my ideas, except I'm unclear why
"extras" are separate from "libs" I'm not sure if they is less confusing
to the end user.

Also the "stuff/" catagory is confusing, and seems a little too
organized without being clear "audio playpen" what does that mean? Where
does this stuff comefrom? I'm guessing its not in PD docs, from CVS
perhaps? Oh! I just looked and it is in PD! I did not realize all that
new stuff was in there. I still think the organization leaves a bit to
be desired.

I'll note here also that the "help-*" name format is damn ugly when you
see the 5.reference folder in the pull-down menu. (and you can't jump to
a certain entry because everything starts with "h") The jump-to thing
works fine on OSX, 38-2 tcl 8.4.9, how about on ther platforms?

So what if the "doc" PD folder looks like:

Manual
Control-Examples
Audio-Examples/
     Playpen/
     Soundfile-Tools/
     Synth/
     Sound-Files/ (ALL included WAV files.)
FFT-Examples
Data-Structure-Examples
Gem-Examples
pmpd-Examples
zexy-Examples
iemlib-Examples
PiDiP-Examples
Object-Reference/
     Gem/
     pmpd/
     zexy/
     iemlib/
     PiDiP/
     .
     .
     .
Writing-Externals


"reference" is very different from the other catagories, so I think it
should not be bundled with the rest. Also 6.externs is more code
examples than documentation, so that should not be visible in the PD
menu and have a more descriptive name. Same goes for the "sound" folder
that should be inside "audio" and/or have a more descriptive name. X.wav
should also be moved to this folder. Stuff like "audio-playpen" should
be in "audio examples" if needbe perhaps in a "toys" subfolder. Same
goes for soundfile-tools and "synth". This should be integrated into the
audio Examples. I'm not sure what to do with "tools" Maybe these should
be in a separate PD pull-down menu next to help, since they are really
not "help" nor documentation for that matter. "Tools" left of "Help".
"Object reference" will contain the help files for all EXTERNALS in the
format of *-help.pd. LIBS will have thier own directory in "Object
Reference" with the name of the lib.


Which generates a cascading menu that looks like:

Manual
Control-Examples
Audio-Examples
FFT-Examples
------------ <- seperator
Gem-Examples
pmpd-Examples
zexy-Examples
iemlib-Examples
PiDiP-Examples
------------
Object-Reference

I can work on doing the code for this but we absolutly need a better
standard for where all this stuff goes first, so that we can have the
help menu generated from the doc/ directory dynamically. Only those
externals/libs installed will be included in the menu.

I'll wait for the discussion before I start working on this...

Feedback?

B>

Burt wrote:
> Greetings again,
>
> I have posted a new version of an installer for OS X.
>
> http://pcm.peabody.jhu.edu/~sburt/pd/installing_pd_os_x.html
>
> Rob Lycett requested that I add the comport library and its documentation, so I did.  I was also frustrated by tcl/tk handling of submenus within submenus.  If anyone knows how to do this, please let me know.  So, I placed the 7.stuff subdirectories directly into the Help menu which is not elegant and only temporary.  I also added a zexy submenu to Help (which I had previously forgotten).  So, now there should be easy to find documentation on basic PD objects, the libraries Gem, vasp, pmpd, Han's hid, and Zexy, plus everything inside the stuff folder including (now) comport.
>
> I feel that a better way to organize the Help menu (with my segregated library approach) would be to do it with submenus for PD and major libraries and an extra folder for smaller things:
>
> PD Documentation/
>     HTML manual/
>     control examples/
>     audio examples/
>     fft examples/
> Gem/
> pmpd/
> vasp/
> zexy/
> extras/
>     hid/
>     comport/
>     stuff/
>        audio playpen/
>        data-structures/
>        soundfile-tools/
>        synth/
>        tools/
>
> Unfortunately, this would require a restructuring of PD documentation as it is now, and I would have to understand how to create submenus in submenus in tcl/tk.  Can anyone do this?  What would be really cool would be to adjust the Pd script so that Help documentation of a particular library does not appear until the library is loaded.  That way, we avoid users opening help patches and getting messages about objects not existing (or worse yet, PD crashing).
>
>
> Samuel Burt
>
>
>
>
>
>
>
>
> _______________________________________________
> PD-list at iem.at mailing list
> UNSUBSCRIBE and account-management -> http://iem.at/cgi-bin/mailman/listinfo/pd-list
>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 256 bytes
Desc: OpenPGP digital signature
URL: <http://lists.puredata.info/pipermail/pd-list/attachments/20050316/cd00b966/attachment.pgp>