I definitely agree that the docs directory structure needs to be
reorganized, but I don't think that it should be based on the
libraries. If there is going to be some hierarchy, I think it should
be based on object functionality instead. That is a much more
intuitive way to navigate for help.
.hc
On Mar 16, 2005, at 4:12 PM, B. Bogart wrote:
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@iem.at mailing list UNSUBSCRIBE and account-management ->
http://iem.at/cgi-bin/mailman/listinfo/pd-list
¡El pueblo unido jamás será vencido!