[PD] Patterns for Pd Documentation

[Alexandre Torres Porres]

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 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
>
>
>> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puredata.info/pipermail/pd-list/attachments/20210525/ce976386/attachment-0001.htm>