Brennon Bortz

Has scripting (thispatcher, Javascript, or otherwise) been fully documented ANYWHERE? Up until now, I have seemed to be able to cobble things together through forum searches, etc. I'm all for reading the manual, and I'm all for utilizing the forums, but is there really no place where these topics have been covered by C74 or other users? Just a couple examples:

-Scripting a [bpatcher] as shown in the documentation (at least when using the "replace" message) is just plain wrong. The forums have worked this kink out for me, thank goodness!

Has scripting (thispatcher, Javascript, or otherwise) been fully documented ANYWHERE?  Up until now, I have seemed to be able to cobble things together through forum searches, etc.  I'm all for reading the manual, and I'm all for utilizing the forums, but is there really no place where these topics have been covered by C74 or other users?  Just a couple examples:

-Does a DOM exist for Max patches?
-Scripting a [bpatcher] as shown in the documentation (at least when using the "replace" message) is just plain wrong.  The forums have worked this kink out for me, thank goodness!

scripting-documentation

Quote: Brennon Bortz wrote on Tue, 13 January 2009 19:57

----------------------------------------------------

> Has scripting (thispatcher, Javascript, or otherwise) been fully documented ANYWHERE?

The reference page for the thispatcher object, and 

"Javascript in Max." ( Help > Max Help ). You mean

Quote: Brennon Bortz wrote on Tue, 13 January 2009 19:57
----------------------------------------------------
> Has scripting (thispatcher, Javascript, or otherwise) been fully documented ANYWHERE?

The reference page for the thispatcher object, and 
"Javascript in Max." ( Help > Max Help ). You mean
that stuff?


> The reference page for the thispatcher object, and

> "Javascript in Max." ( Help > Max Help ). You mean

If by "You mean that stuff?", you mean, "Are these examples of horrible

documentation to which you are referring?", then yes--these are horrible

> The reference page for the thispatcher object, and
> "Javascript in Max." ( Help > Max Help ). You mean
> that stuff?

If by "You mean that stuff?", you mean, "Are these examples of horrible
documentation to which you are referring?", then yes--these are horrible
examples of documentation.


The snark was very amusing, but I would have to

say that the answer to the question as you define

We're always interested in specific and constructive

suggestions for improving our documentation.

The snark was very amusing, but I would have to
say that the answer to the question as you define
it would be "No."

We're always interested in specific and constructive
suggestions for improving our documentation.


Quote: Gregory Taylor wrote on Wed, 14 January 2009 16:05

> We're always interested in specific and constructive

> suggestions for improving our documentation.

Well, as someone who uses javascript in Max fairly regularly, I always consult the Max 4.x "Javascript in Max" reference pdf, which was really great and still seems very relevant (I haven't found anything in Max 5 that has changed to make this reference out of date, but I don't do much jsui coding).

I never understood why this wasn't updated and included in Max 5, it's extremely useful and I can't code javascript for Max without it on hand. I've already brought this up a few times and no one comments on it...

Brennon: you might want to go install Max 4.6 just to get your hands on this pdf. I think you'll find it fills in the gaps in the documentation quite nicely. It's a bona fide *reference* that explains all the available methods and such in the Max javascript API.

Quote: Gregory Taylor wrote on Wed, 14 January 2009 16:05
----------------------------------------------------
> We're always interested in specific and constructive
> suggestions for improving our documentation.
----------------------------------------------------

Brennon: you might want to go install Max 4.6 just to get your hands on this pdf. I think you'll find it fills in the gaps in the documentation quite nicely. It's a bona fide *reference* that explains all the available methods and such in the Max javascript API.


I think this refernce guide wasn't included at some point, but I haven't opened the main help page in a while. It's there now.

So that's a good reference if you ask me. I think the fundamental problem here is it is not linked to from other places. Like the js help file and js reference doc. (or did I just miss it there too?)

I think this refernce guide wasn't included at some point, but I haven't opened the main help page in a while. It's there now. 

So that's a good reference if you ask me. I think the fundamental problem here is it is not linked to from other places. Like the js help file and js reference doc. (or did I just miss it there too?)


> Brennon: you might want to go install Max 4.6 just to get your hands on this pdf. I think you'll find it fills in the gaps in the documentation quite nicely. It's a bona fide *reference* that explains all the available methods and such in the Max javascript API.

I'll certainly do that! Thanks for the tip, Adam.

Adam Murray wrote:
> Brennon: you might want to go install Max 4.6 just to get your hands on this pdf. I think you'll find it fills in the gaps in the documentation quite nicely. It's a bona fide *reference* that explains all the available methods and such in the Max javascript API.
>
I'll certainly do that!  Thanks for the tip, Adam.


> I think this refernce guide wasn't included at some point, but I haven't opened the main help page in a while. It's there now. 

Ahh... I thought you were either referring to something different, or 

stating that the guide from 4.6 was more "fleshed out". This guide may 

work for you, but not for me... Is there really no object model for 

Javascript in Max? That, at the very least, would be a decent start. 

Without one, it's really a guessing game to get things working.

Adam Murray wrote:
> Duh... nevermind! 
>
> I think this refernce guide wasn't included at some point, but I haven't opened the main help page in a while. It's there now. 
Ahh...  I thought you were either referring to something different, or 
stating that the guide from 4.6 was more "fleshed out".  This guide may 
work for you, but not for me...  Is there really no object model for 
Javascript in Max?  That, at the very least, would be a decent start.  
Without one, it's really a guessing game to get things working.


Quote: Brennon Bortz wrote on Thu, 15 January 2009 04:58

> Is there really no object model for Javascript in Max? 

Hmm, I'm not really sure what you are expecting, but if I go to the "Javascript in Max" area of the documentation (linked from the home page of the help docs), there is a list of all the objects that Max *adds* to the standard javascript object model. Drilling into those we get a list of properties and methods for the object, along with descriptions of what they do. The key ones for scripting a patch are the Patcher and Maxobj objects.

This info is similar to the kind of reference material if I search for "javascript object model reference" and end up at a site like this: 

For the core javascript object model, I beleive Max uses JS 1.5 and there are plenty of online resources for that part of the object model (minus of course the things specific to web browsers, the "client side" object model).

Not trying to be argumentative, just wondering more specifically what you think is missing. Are you expecting some sort of elaborate DOM structure for everything in the patch that's similar to the HTML DOM? It doesn't really work that way. You can access the patcher and it's parents, or find specific objects by their scripting name, and iterate over all the objects. But it's much more limited than the HTML DOM in a browser and you can't traverse it the same way.

The other thing is you can't access object attributes as Maxobj properties in javascript. The closest thing you can do is call Maxobj.message() to send messages to objects to manipulate them. There are a bunch of things you might expect to do wirelessly with a javascript that simply cannot be done today.

So maybe this not a documentation issue so much as frustration with the limitations as compared to HTML DOM? I think this may be your issue, probably the kind of DOM you want does not currently exist in Max. Think of javascript as more of a language for building custom objects with some limited ability to script the other objects in your patch. Still, even with those limits, a lot is possible.

Quote: Brennon Bortz wrote on Thu, 15 January 2009 04:58
----------------------------------------------------
> Is there really no object model for Javascript in Max?  
----------------------------------------------------

This info is similar to the kind of reference material if I search for "javascript object model reference" and end up at a site like this: http://www.javascriptkit.com/domref/

Not trying to be argumentative, just wondering more specifically what you think is missing. Are you expecting some sort of elaborate DOM structure for everything in the patch that's similar to the HTML DOM? It doesn't really work that way. You can access the patcher and it's parents, or find specific objects by their scripting name, and iterate over all the objects. But it's much more limited than the HTML DOM in a browser and you can't traverse it the same way. 

The other thing is you can't access object attributes as Maxobj properties in javascript. The closest thing you can do is call Maxobj.message() to send messages to objects to manipulate them. There are a bunch of things you might expect to do wirelessly with a javascript that simply cannot be done today. 

So maybe this not a documentation issue so much as frustration with the limitations as compared to HTML DOM? I think this may be your issue, probably the kind of DOM you want does not currently exist in Max. Think of javascript as more of a language for building custom objects with some limited ability to script the other objects in your patch. Still, even with those limits, a lot is possible.


Quote: Adam Murray wrote on Thu, 15 January 2009 17:47

> If I search for "javascript object model reference" and end up at a site like this: 

http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html

> For the core javascript object model, I beleive Max uses JS 1.5 and there are plenty of online resources for that part of the object model (minus of course the things specific to web browsers, the "client side" object model).

And with these other resources, I'm perfectly happy! Where does the Max documentation show how and where its own classes fit into these models, though?

> Not trying to be argumentative, just wondering more specifically what you think is missing. Are you expecting some sort of elaborate DOM structure for everything in the patch that's similar to the HTML DOM? It doesn't really work that way. You can access the patcher and it's parents, or find specific objects by their scripting name, and iterate over all the objects. But it's much more limited than the HTML DOM in a browser and you can't traverse it the same way.

Not trying to be argumentative, in turn, I understand what you're saying, but this isn't really the root of my problem. Part of being able to work efficiently in Javascript (as with other similar languages) is the ability to effectively traverse the OM. The information that the Max documentation DOES give doesn't clearly illustrate how these classes fit together in a cohesive way. This type of documentation would not be difficult to assemble and certainly exists somewhere in the C74 offices! :) Without such a map, structuring these extensions to Javascript would be a royal nightmare.

Further, and more related to your point, I can't count the number of times I've not been able to figure out how to do something in Javascript/Max, have turned to the list or colleagues, and then been pointed to the right method/property/etc. Surely I just missed something in the manual, right? Sometimes, yes. Many, many other times I have searched the documentation (now much more easily!) only to find that these things are NEVER mentioned--not once! Limitations to a language I can swallow. Missing documentation, on the other hand, can be a much hairier problem!

Quote: Adam Murray wrote on Thu, 15 January 2009 17:47
----------------------------------------------------
> If I search for "javascript object model reference" and end up at a site like this: http://www.javascriptkit.com/domref/

I'm thinking more along these lines: http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html

And with these other resources, I'm perfectly happy!  Where does the Max documentation show how and where its own classes fit into these models, though?

> Not trying to be argumentative, just wondering more specifically what you think is missing. Are you expecting some sort of elaborate DOM structure for everything in the patch that's similar to the HTML DOM? It doesn't really work that way. You can access the patcher and it's parents, or find specific objects by their scripting name, and iterate over all the objects. But it's much more limited than the HTML DOM in a browser and you can't traverse it the same way. 

Not trying to be argumentative, in turn, I understand what you're saying, but this isn't really the root of my problem.  Part of being able to work efficiently in Javascript (as with other similar languages) is the ability to effectively traverse the OM.  The information that the Max documentation DOES give doesn't clearly illustrate how these classes fit together in a cohesive way.  This type of documentation would not be difficult to assemble and certainly exists somewhere in the C74 offices! :)  Without such a map, structuring these extensions to Javascript would be a royal nightmare.

Further, and more related to your point, I can't count the number of times I've not been able to figure out how to do something in Javascript/Max, have turned to the list or colleagues, and then been pointed to the right method/property/etc.  Surely I just missed something in the manual, right?  Sometimes, yes.  Many, many other times I have searched the documentation (now much more easily!) only to find that these things are NEVER mentioned--not once!  Limitations to a language I can swallow.  Missing documentation, on the other hand, can be a much hairier problem!


Quote: Gregory Taylor wrote on Thu, 15 January 2009 00:05

> The snark was very amusing, but I would have to

> say that the answer to the question as you define

With all due respect (and I mean it genuinely), it's really not up to the developer to make this determination.

I do appreciate C74's willingness to work on things like this! There are certainly far poorer examples of documentation in the world, and I do appreciate that which we do have for Max/MSP. There are, however, lots of posts here in the forums from users struggling to make sense of the JS documentation--I'm not the first to speak up. Also, not everyone is able to specifically point out just what should be changed about or added to the documentation--this doesn't let C74 off the hook though! :) For the price we pay for Max/MSP, we should be able to expect updates to the documentation where it is lacking--even when there hasn't been any hand-holding by the end users.

That said, I hope that I've provided some more specific examples in my previous post in this topic, as well as here:

https://cycling74.com/forums/index.php?t=msg&th=37507&start=0&rid=4817&S=dcb6ddef5b72e9c6931abfc823a86d6f

Quote: Gregory Taylor wrote on Thu, 15 January 2009 00:05
----------------------------------------------------
> The snark was very amusing, but I would have to
> say that the answer to the question as you define
> it would be "No."

> We're always interested in specific and constructive
> suggestions for improving our documentation.

I do appreciate C74's willingness to work on things like this!  There are certainly far poorer examples of documentation in the world, and I do appreciate that which we do have for Max/MSP.  There are, however, lots of posts here in the forums from users struggling to make sense of the JS documentation--I'm not the first to speak up.  Also, not everyone is able to specifically point out just what should be changed about or added to the documentation--this doesn't let C74 off the hook though! :)  For the price we pay for Max/MSP, we should be able to expect updates to the documentation where it is lacking--even when there hasn't been any hand-holding by the end users.

https://cycling74.com/forums/index.php?t=msg&th=37507&start=0&rid=4817&S=dcb6ddef5b72e9c6931abfc823a86d6f


Here's another example, taken from the Patcher object section:

Any message to a patcher that you can send in Max (via the thispatcher object) you can send in Javascript in js.

p.fullscreen(1); // makes the patcher take up the whole screen 

p.dirty();     // make an editable patcher dirty

If fullscreen() and dirty() are methods of the Patcher object, why aren't they actually listed below as methods? Instead of having a list of ALL methods available to a class, it seems that there is a truncated listing with other available methods or properties scattered around in the examples. I'm glad to have found them in the examples, but how are we to know that we're actually seeing everything available? What if something didn't happen to make it into an example?

Any message to a patcher that you can send in Max (via the thispatcher object) you can send in Javascript in js.
Examples:

p = this.patcher; 
p.fullscreen(1); // makes the patcher take up the whole screen 
p.dirty();	 // make an editable patcher dirty

If fullscreen() and dirty() are methods of the Patcher object, why aren't they actually listed below as methods?  Instead of having a list of ALL methods available to a class, it seems that there is a truncated listing with other available methods or properties scattered around in the examples.  I'm glad to have found them in the examples, but how are we to know that we're actually seeing everything available?  What if something didn't happen to make it into an example?


"Any message to a patcher that you can send in Max (via the thispatcher object) you can send in Javascript in js."

if it's a thispatcher message/attribute, it's a Patcher method.

to see thispatcher message's, look at the reference for thispatcher.

if you find messages that don't work when you think they should, please let 'em know. otherwise, i think the way js works in max, and the way the documentation is worded and organized takes some getting used to.

Quote: Brennon Bortz wrote on Fri, 16 January 2009 12:22

> Here's another example, taken from the Patcher object section:

> Any message to a patcher that you can send in Max (via the thispatcher object) you can send in Javascript in js.

> p.fullscreen(1); // makes the patcher take up the whole screen 

> p.dirty();     // make an editable patcher dirty

> If fullscreen() and dirty() are methods of the Patcher object, why aren't they actually listed below as methods? Instead of having a list of ALL methods available to a class, it seems that there is a truncated listing with other available methods or properties scattered around in the examples. I'm glad to have found them in the examples, but how are we to know that we're actually seeing everything available? What if something didn't happen to make it into an example?

i also don't quite follow your question.
"Any message to a patcher that you can send in Max (via the thispatcher object) you can send in Javascript in js."

seems unambiguous to me.
if it's a thispatcher message/attribute, it's a Patcher method.
to see thispatcher message's, look at the reference for thispatcher.

Quote: Brennon Bortz wrote on Fri, 16 January 2009 12:22
----------------------------------------------------
> Here's another example, taken from the Patcher object section:
>
> Patcher Methods
>
> Any message to a patcher that you can send in Max (via the thispatcher object) you can send in Javascript in js.
> Examples:
>
> p = this.patcher; 
> p.fullscreen(1); // makes the patcher take up the whole screen 
> p.dirty();	 // make an editable patcher dirty
>
> If fullscreen() and dirty() are methods of the Patcher object, why aren't they actually listed below as methods?  Instead of having a list of ALL methods available to a class, it seems that there is a truncated listing with other available methods or properties scattered around in the examples.  I'm glad to have found them in the examples, but how are we to know that we're actually seeing everything available?  What if something didn't happen to make it into an example?
----------------------------------------------------


Quote: robtherich wrote on Fri, 16 January 2009 19:28

> i also don't quite follow your question.

> "Any message to a patcher that you can send in Max (via the thispatcher object) you can send in Javascript in js."

The statement is perfectly unambiguous to me, as well. This isn't what I was concerned with here.

> if it's a thispatcher message/attribute, it's a Patcher method.

> to see thispatcher message's, look at the reference for thispatcher.

I can't find "dirty" or "fullscreen" listed anywhere in the [thispatcher] reference. They are, however, shown in the .maxhelp file for [thispatcher]. Keep reading...

> if you find messages that don't work when you think they should, please let 'em know.

I have done so, referenced above in this message, and elsewhere.

> otherwise, i think the way js works in max, and the way the documentation is worded and organized takes some getting used to.

This is my point entirely. $400 dollars and plenty of other money thrown at multiple upgrades has bought me one hell of a program--I couldn't live without it. On the other hand, it hasn't bought me clear, concise, and complete documentation specifically with regards to scripting. We shouldn't have to go hunting and pecking all over the place to find a method we're looking for. If I'm looking for a method that pertains to a particular class, I should be able to find it in the complete list of properties and methods for THAT class. Is that really too much to ask?

I make no bones about it--I'm very pleased with the new documentation style. C74 has really come a long way there. However, I think I've made several valid points regarding these issues both here and elsewhere. If the best response I can get is, "Well...get used to it," then, well...that just really bites.

Furthermore, I'm not trolling here. I think there are some phenomenal capabilities in scripting waiting to be used--I'm just struggling to figure out how to unlock these with incomplete documentation.

Quote: robtherich wrote on Fri, 16 January 2009 19:28
----------------------------------------------------
> i also don't quite follow your question.
> "Any message to a patcher that you can send in Max (via the thispatcher object) you can send in Javascript in js."
>
> seems unambiguous to me.

The statement is perfectly unambiguous to me, as well.  This isn't what I was concerned with here.

> if it's a thispatcher message/attribute, it's a Patcher method.
> to see thispatcher message's, look at the reference for thispatcher.

I can't find "dirty" or "fullscreen" listed anywhere in the [thispatcher] reference.  They are, however, shown in the .maxhelp file for [thispatcher].  Keep reading...

This is my point entirely.  $400 dollars and plenty of other money thrown at multiple upgrades has bought me one hell of a program--I couldn't live without it.  On the other hand, it hasn't bought me clear, concise, and complete documentation specifically with regards to scripting.  We shouldn't have to go hunting and pecking all over the place to find a method we're looking for.  If I'm looking for a method that pertains to a particular class, I should be able to find it in the complete list of properties and methods for THAT class.  Is that really too much to ask?

I make no bones about it--I'm very pleased with the new documentation style.  C74 has really come a long way there.  However, I think I've made several valid points regarding these issues both here and elsewhere.  If the best response I can get is, "Well...get used to it," then, well...that just really bites.

Furthermore, I'm not trolling here.  I think there are some phenomenal capabilities in scripting waiting to be used--I'm just struggling to figure out how to unlock these with incomplete documentation.

"clean" is shown as an available message in thispatcher.maxhelp, but not listed as an available method for the Wind object. It is, in fact, a legal method for the Wind object, however.

"clean" is shown as an available message in thispatcher.maxhelp, but not listed as an available method for the Wind object.  It is, in fact, a legal method for the Wind object, however.


Quote: Brennon Bortz wrote on Fri, 16 January 2009 14:15

> "clean" is shown as an available message in thispatcher.maxhelp, but not listed as an available method for the Wind object. It is, in fact, a legal method for the Wind object, however.

Hey Brennon, I think this is really good feedback for C74.

At some point I got a handle on how to use js for my purposes, but I remember there was a lot of frustration at first. I'll try to be better about giving this kind of feedback in the future when I notice holes in the docs.

If we're persistent and patient and keep pushing for things to get better, things will get better. It may take a while though, they're a small company and they've been busy pulling off some amazing feats these last couple years, so I'm not all that surprised things like this haven't gotten the attention they need. But that's what user feedback is for, right?

Quote: Brennon Bortz wrote on Fri, 16 January 2009 14:15
----------------------------------------------------
> "clean" is shown as an available message in thispatcher.maxhelp, but not listed as an available method for the Wind object.  It is, in fact, a legal method for the Wind object, however.
----------------------------------------------------

Hey Brennon, I think this is really good feedback for C74. 

If we're persistent and patient and keep pushing for things to get better, things will get better. It may take a while though, they're a small company and they've been busy pulling off some amazing feats these last couple years, so I'm not all that surprised things like this haven't gotten the attention they need. But that's what user feedback is for, right?


Quote: Adam Murray wrote on Fri, 16 January 2009 22:45

> If we're persistent and patient and keep pushing for things to get better, things will get better. It may take a while though, they're a small company and they've been busy pulling off some amazing feats these last couple years, so I'm not all that surprised things like this haven't gotten the attention they need. But that's what user feedback is for, right?

Quite true, Adam. Having worked for software developers before, though, I know that the cause of inconsistent or incomplete documentation is most often disorganization on the front end, or a lack of priority given to documentation. That C74 has begun to give documentation more attention is certainly obvious, but my concern is that scripting, in particular, continues to fail to receive such attention. The Java and C APIs seem to be more well-documented, but I haven't spent a huge amount of time in them. The Javascript extensions, provide the opportunity for a form of extending Max than either Java or C that is much more accessible to the common user. (I may only think this from learning C one of my first languages, though.) If this is in fact the case, I'm surprised that C74 hasn't given it more attention.

I will admit that my assumptions as to why these "holes" exist may not be accurate, as there's really no way for me to know! Nevertheless, the fact is that what I've specifically asked for wouldn't take more than a week's time for someone who has the Max source available and already knows the extension. True, this wouldn't solve the problem altogether, but it would be a wonderful start!

Quote: Adam Murray wrote on Fri, 16 January 2009 22:45
----------------------------------------------------
> If we're persistent and patient and keep pushing for things to get better, things will get better. It may take a while though, they're a small company and they've been busy pulling off some amazing feats these last couple years, so I'm not all that surprised things like this haven't gotten the attention they need. But that's what user feedback is for, right?

Quite true, Adam.  Having worked for software developers before, though, I know that the cause of inconsistent or incomplete documentation is most often disorganization on the front end, or a lack of priority given to documentation.  That C74 has begun to give documentation more attention is certainly obvious, but my concern is that scripting, in particular, continues to fail to receive such attention.  The Java and C APIs seem to be more well-documented, but I haven't spent a huge amount of time in them.  The Javascript extensions, provide the opportunity for a form of extending Max than either Java or C that is much more accessible to the common user.  (I may only think this from learning C one of my first languages, though.)  If this is in fact the case, I'm surprised that C74 hasn't given it more attention.

I will admit that my assumptions as to why these "holes" exist may not be accurate, as there's really no way for me to know!  Nevertheless, the fact is that what I've specifically asked for wouldn't take more than a week's time for someone who has the Max source available and already knows the extension.  True, this wouldn't solve the problem altogether, but it would be a wonderful start!


Quote: Brennon Bortz wrote on Fri, 16 January 2009 16:23

> I will admit that my assumptions as to why these "holes" exist may not be accurate, as there's really no way for me to know!

https://cycling74.com/story/2009/1/15/112631/799):

"I think it would be safe to say that Cycling '74 operates in a manner that, by comparison to Ableton, could be characterized as complete and utter chaos"

That might have something to do with it ;)

Quote: Brennon Bortz wrote on Fri, 16 January 2009 16:23
----------------------------------------------------
> I will admit that my assumptions as to why these "holes" exist may not be accurate, as there's really no way for me to know!

From David Z himself (https://cycling74.com/story/2009/1/15/112631/799):

That might have something to do with it ;)


Scripting documentation