@porres said:
so I wonder what is not clear about all this.
It is a tricky thing to explain when your audience includes everything from complete layman to accomplished programmers. I can see now that it is all there and have been studying it and a few other sections trying to figure out what tripped me up and I think it is just a minor structural and terminology issues. What a selector is and does should be covered in the first paragraph instead of being split out between the first and fourth. This is the main thing the user needs to understand in this section and it should be laid out up front so anytime they refer back to this section it gets beaten into our heads. Maybe something like this?
Messages contain a selector followed by any number of arguments. The receiver of a message uses the selector to 'select' how it should proceed and handle any arguments. Selectors can be any valid symbol and arguments are anything that follows the selector and may be symbols or numbers (aka atoms). For instance "list a b c" has a "list" selector, which tells the receiver to process the arguments "a b c" as a list data type. This message is only composed of symbols but a list message can combine two or more symbols and/or floats.
You are right about keeping methods out of this section, the detailed explanation including methods should be in 2.7.3 which is almost there, just needs a few things like methods added in and probably simple definitions of things like object, class and method in context of pd. Maybe a reference to 2.7.3 in 2.4.1, "this will be covered in more depth in 2.7.3" or the like? The rest seems good to me.
I really hate doing documentation.