docs dir structure WAS Re: [PD] Re: Mac OS X installer with library documentation
B. Bogart
ben at ekran.org
Fri Mar 18 17:18:39 CET 2005
This is true that its difficult for the user to know what library a
particular object is from, unless they were taught a particular library.
(gem/pdp objects are generally easy to recognize)
Do you have an example on how this could be organized?
Part of the lib-centric approach was that it would be very easy for the
makefiles, since they just need to create a directory of the libs name
in a correct place and thats it. How I guess the same goes for putting
stuff in a directory containing objects of a certain class... as long as
we all agree on what catagories each lib/object belongs to. for example
the whole class of experimental algorithms.. Control yes.. but something
special as well. (chaos, PSO, ANN, etc..)
Maybe something like:
Manual
Control-Examples (includes zexy control objects)
Audio-Examples/ (includes zexy audio objects)
Playpen/
Soundfile-Tools/
Synth/
Sound-Files/ (ALL included WAV files.)
FFT-Examples
Data-Structure-Examples
Visual-Examples/
Vector (includes Gem)
Pixel (includes PDP, PiDiP, framestien (alive?),
Physical-Modeling-Examples (pmpd, dyn~ ?)
Object-Reference/
Control/
Audio/
FFT/
Data-Structures/
Visual-Vector/
Visual-Pixel/
Physical-Modeling
Writing-Externals
Or if help-* becomes *-help then Object reference could all be flat
without submenus/subdirs.
What this approach implies is the integration of functionality into a
more cohesive form. Sections for types of interaction.. Vector vs Pixel
is problematic but having all the visual objects in one directory/menu
is probably too confusing... To make this work the relationship between
libraries needs more consideration. (how PDP relates/overlaps with Gem
and framestein etc.. Maybe this could be discussed tonight on IRC. (but
I'll have only a little time.)
I think we're getting somewhere! Thanks for the feedback HC.
One sticky point may be author recognition. Each library has its own
name and identity and organizing them outside of that name may irk some
people.
B>
Hans-Christoph Steiner wrote:
>
> 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!
>
>
> _______________________________________________
> 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/20050318/bff3b449/attachment.pgp>
More information about the Pd-list
mailing list