[PD] Patterns for Pd Documentation

Alexandre Torres Porres porres at gmail.com
Fri May 28 21:02:47 CEST 2021

Em sex., 28 de mai. de 2021 às 14:37, Miller Puckette <
mpuckette at cloud.ucsd.edu> escreveu:

> One thing I'm hoping to be able to do this summer is extend the number box
> to do this (and unify it with the symbol box while I'm at it :)
> Miller

Awesome, replying to the list as I suspect you meant to ;)

and while we're at it, I have many things I'd like to fix for atom boxes
and iemguis on the next release, they're all organized here


> On Tue, May 25, 2021 at 10:23 AM Alexandre Torres Porres <porres at gmail.com>
> wrote:
>> By the way, one thing that is very useful for ELSE's help files is my
>> [display] object (similar to Extended's [PRINT] from 'pddp') that can print
>> any data from the outlets right on the patch, which is something people
>> seem to hope for in a friendlier documentation - [display] also flashes
>> when receiving data.
>> I have a solution for atom boxes that I already proposed in
>> https://github.com/pure-data/pure-data/issues/1321
>> <https://urldefense.com/v3/__https://github.com/pure-data/pure-data/issues/1321__;!!Mih3wA!XTLMWMN0aQsMfeFO1KzOZcHWoHQMd4ICIQldiC1ZRMd4oMK0mxW49yuRGjL8$>
>> I could give it a try in a PR.
>> But Pd would still need an object for 'anything', an 'anything' box (yes,
>> a newly compiled GUI object), or an abstraction like [PRINT]/[display]. In
>> order to ship it as part of Pd, it makes better sense to me a compiled
>> object, instead of a new 'extra' object. Unless we have this abstraction as
>> a helper abstraction for the help files only. Pd already does something
>> like that with its 'output~.pd' abstraction.
>> By the way, recently, we've been discussing if 'output~.pd' should be
>> part of 'extra', because we're using it in 3 different places (that is, we
>> have 3 different copies of it): - in the help files folder (5.reference),
>> in 3.audio.examples and 4.data.structures. I can't find now where me and
>> IOhannes were discussing it, but it's somewhere on github.
>> I don't think it's worth 'promoting' output~ to extra, but I wouldn't
>> oppose it either. I'm also unsure about having something like [display] in
>> extra. I don't have a strong opinion on this though and I could go either
>> way with the crowd.
>> What I think it's important is that we have an object to help us in the
>> documentation, so my strong opinion is that we should find a solution. A
>> compiled 'anything' box would be nice, but I don't think I can easily do
>> that myself, so my offer is that I can design a vanilla abstraction like
>> [display] - first as a helper abstraction (not an 'extra' object), and
>> that's it.
>> Cheers
>> Em ter., 25 de mai. de 2021 às 13:51, Alexandre Torres Porres <
>> porres at gmail.com> escreveu:
>>> Em ter., 25 de mai. de 2021 às 05:50, Dan Wilcox <danomatika at gmail.com>
>>> escreveu:
>>>> Does anyone have a link, etc to the pddoc project/external from
>>>> Pd-extended?
>>> I feel a lot of this was already approached over 10 years ago but not
>>>> ported over into Pd vanilla. It might be worth checking it out before
>>>> starting from scratch.
>>> this? => http://puredata.info/dev/pddp/pddp-drafts
>>> <https://urldefense.com/v3/__http://puredata.info/dev/pddp/pddp-drafts__;!!Mih3wA!XTLMWMN0aQsMfeFO1KzOZcHWoHQMd4ICIQldiC1ZRMd4oMK0mxW495lysFQu$>
>>>> Also, keep in mind that old habits may be hard to break so don't be
>>>> surprised if enforcing "one pattern to rule them all" might become
>>>> "whack-a-mole."
>>> :)
>>> > To point some examples of things already done in regard to better
>>> documentation:
>>>  > - Porres' ELSE documentation and the Live Electronics Tutorial are
>>> good because of
>>> > the care to register and create patches that are visually unified,
>>> that show a concern
>>> > with good practices of patches creation.
>>> Thanks for the compliments.
>>> Well. For ELSE and Cyclone I adopted a similar template than the ones
>>> above. They're all a bit different in design, but I think they all follow
>>> the same idea/concept, and here's the shocking revelation: *I think
>>> it's a bad idea and I hate them!*
>>> I know it can be useful and helpful, but forcing any of these templates
>>> into every possible help file ends up in a nightmare in some cases. It
>>> might be good for most help files but there'll always be exceptions where
>>> it's just not pertinent at all to stick to the restrictions that were good
>>> for the other cases. Take my word after applying this over 600 times. I can
>>> say I regret it and would like to change it but it's just undoable at this
>>> point.
>>> I'm totally onboard doing a complete rework of Pd's help files and
>>> contributing to the documentation in general. In fact, I've been doing a
>>> lot of that in recent times, by writing new manual sections and rewriting
>>> and fixing many help files. But I wouldn't embrace the idea of choosing a
>>> template for all. I wouldn't work on that and I can go on and on why I
>>> think it's a bad idea, giving many examples why I think this is bad, in
>>> opposition of anyone who thinks this is great and would like to do it
>>> themselves.
>>> The one good thing about these templates is that they do offer a quick
>>> reference guide telling you what are the accepted messages, number of
>>> arguments and things like that. Sometimes you wanna get to this information
>>> very very quickly, immediately, as you're "in the zone" creating a
>>> masterpiece and don't want to interrupt the workflow for any second - but
>>> Pd Vanilla's help files force you to hold your horses for a moment and fish
>>> for that info.
>>> I'm not saying we can't have that when I say the templates are
>>> problematic. I like that too! But I've been thinking of a
>>> different solution that doesn't involve forcing the same window area for
>>> every patch and having that kind of information right in the parent window.
>>> In short, the options are:
>>> - having a subpatch in a standardized way in the same spot of every help
>>> patch called [pd reference] with that info.
>>> - having a html file, available with the Pd application and called from
>>> within the help patch, kinda like [slop~].
>>> By the way, such a separate 'reference' information is sort of what we
>>> have in MAX, totally detached from the help file and its examples. For my
>>> work in Cyclone, I can say I hate MAX's documentation and that it is quite
>>> flawed, but I like this concept!
>>> The easy option is to have this as a subpatch and this can also be done
>>> first as an initial step for the second option (where we can get the
>>> information and put it in a separate html file).
>>> Cheers
>> _______________________________________________
>> Pd-list at lists.iem.at mailing list
>> UNSUBSCRIBE and account-management ->
>> https://urldefense.com/v3/__https://lists.puredata.info/listinfo/pd-list__;!!Mih3wA!XTLMWMN0aQsMfeFO1KzOZcHWoHQMd4ICIQldiC1ZRMd4oMK0mxW49xf4dICS$
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puredata.info/pipermail/pd-list/attachments/20210528/d1003469/attachment-0001.htm>

More information about the Pd-list mailing list