[PD] pdmtl abstractions questions and comments (previously without a subject)

This a follow up to a few comments and questions sent by Mathieu Bouchard.

In this text, Mathieu's comments and questions are preceded by a "M:". My answers are preceded by a "T:". Every subject is separated by a: ********

Please feel free to contribute to this discussion.

                                       ********

M: 'several signal classes names end in "_~" instead of "~" for no apparent reason. It seems that some nonsignal classes also end in "_" for no apparent reason.'

T: In the http://wiki.dataflow.ws/PdMtlAbstractions/Usage page of the wiki, the "Special characters in abstraction names" section specifies that: a) abstractions that finish with "_~" are graphical signal objects (the only exception to this rule, and this might change, are the abstractions in the gui folder. These abstractions are used to create other "_" abstractions or to help debugging).

b) abstractions that finish with "_" are graphical abstractions. Sometimes, we create an abstraction without a gui, then we create a gui that wraps the same abstraction. The name of both abstractions will be the same, except that the second version will have a "_" appended.

                                      ********

M: 'some class names are "like-this", some are "like_this", and some are "likethis", for no apparent reason. While this happens in the much less controlled world of pd's externals repository, I would expect more from the pdmtl abstractions'

T: Although I prefer abstractions without a "-" or a "_" in their names, others do not. But, since our wiki states that "class names with multiple words in the name should use underscores to separate words (i.e [iem_anything_kernel], [curve_log], [define_loudspeakers], [my_canvas], etc.)", and this follows the http://puredata.info/docs/developer/CodeGuidelines, I will start the conversion of all names so it fits this standard. All abnormal abstractions will be renamed (thanks a lot for the work Mat :) ).

                                      ********

M: "I think it's pretty standard that every *-help.pd file has to contain an object of the class that it documents. Breaking this rule by cutting the documentation into that and *- example.pd files seems pointless. It seems even more pointless when the content of both files together is small enough that it would fit very well in one single patch on a small screen. If you're lacking space you can use subpatches, but really, so far, *- example.pd files seems like a superfluous concept."

T: This is probably an oversight, please give examples of the erroneous help files.

                                      ********

M:- 'it's not obvious that "generate" is only for audio, and there might be lot of other classes outside of "generate" who might be understood like their purpose is to generate something. Especially confusing is the "synth" folder: why is anything of "generate" not in "synth" instead or vice-versa? '

T: I agree. The tern "generate" does not limit itself only to audio, but encompasses a lot of control abstractions. The basic problem was that the list of abstractions in this category was getting way out of hand. We had to find a solution. We asked ourselfs if we only keept control or signal abstractions in the generate category? We decide to spread the control abstractions around the other categories. By the way, we definitely do not want to create a category that ends with a "~" because who wants to instantiate an abstraction with the name generate~/bell~ ?

The "synth" folder groups abstractions that are more like "complete" "midi" instruments (or at least try to be). Think of the "generate" category as the building blocks for the "synth" category. If this still seems to confusing, please reply with an alternative.

                                      ********

M: 'likewise, what's the difference between "fx" and "transform"? I don't get it.'

T: The transformation category groups abstractions that transform stuff with no direct reference to any musical context. The "fx" category groups abstractions that modify signals in a musical context. You can't ask a musician to "repeat~" or "smooth~" his guitar sound. But you can ask him to "delay~", "echo~" or distort it. That's the basic difference between both categories. Is it really confusing? If you still find it confusing, where should we move the abstractions from the "transform" category?

                                      ********

M: 'the "math" folder is especially useless. As a math graduate I feel that byour concept of "math" is something that I lost somewhere along my path, or maybe that I never had it. Anyhow, 99% of what I'd call math stuff is outside of the "math" folder, so, what's the point.'

T: The problem is that in any programming environment 99% of what you are doing has to do with math. The basic principle behind the categories where to think of them more as verbs, actions or types, instead of categorizing stuff along the c standard (or whatever it could/should be called). The verb, action or type categorization method tries to follow the dataflow method. For example, swap, print, send, receive, select, route, pack, etc are all verbs. That is why I imagined that categories should also follow this scheme. "math" is more of a category for stuff that hasn't found it's proper place yet. What do you think? Should the "number" category be include in "math"? How about "scale","random" or "anal". Tags instead of categories would be much better.

                                      ********

M: " _index.pd files don't actually contain a list of the patches in the folder, so why is it called an index?"

T: You are obviously not using either of the official pdmtl abstractions help browsers ( hbrowser.pd or hpopup.pd) as they automatically exclude all files that they consider are not help files. One of the "in progress" ideas of the pdmtl abstractions is to exclude from the listing of help files everything that starts with a "_".

So what is "_index.pd" for? There is a patch called "pdmtl_indexmaker.pd" in pdmtl's root folder. It scans all the help files, extracts information like the description of the abstraction, comments about it, etc, and then scans for the file "_index.pd" to get the description of the category. The end result gives you what you can find here: http://wiki.dataflow.ws/PdMtlAbstractions/Contents This system makes it VERY easy to list all the abstractions, their categories and descriptions. The whole process of getting the data and updating the web page takes less than a minute.

                                      ********

M: 'I see that you don't have a folder named "mapping" yet, but it's written in http://puredata.info/dev/PdLibraries, so I have to ask, what is a mapping? It seems like most object classes have the purpose "to map inputs to outputs". While browsing around in pdmtl abstractions, it seems like the term would apply to most of the stuff. So, what is that for?' T: Hum, so you asking us why we did not include a "mapping" category and then comment that "mapping" useless or too general???!!!

if you are looking for something similar to the "mapping" category, you can check pdmtl's "scale" category.