docs dir structure WAS Re: [PD] Re: Mac OS X installer with library documentation
Hans-Christoph Steiner
hans at eds.org
Fri Mar 18 07:47:22 CET 2005
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 at iem.at mailing list
>> UNSUBSCRIBE and account-management ->
>> http://iem.at/cgi-bin/mailman/listinfo/pd-list
>>
>>
________________________________________________________________________
____
¡El pueblo unido jamás será vencido!
More information about the Pd-list
mailing list