[PD] Help Docs: element vs. item

[Jonathan Wilkes]

--- On Mon, 8/10/09, Mathieu Bouchard <matju at artengine.ca> wrote:

> From: Mathieu Bouchard <matju at artengine.ca>
> Subject: Re: [PD] Help Docs: element vs. item
> To: "Jonathan Wilkes" <jancsika at yahoo.com>
> Cc: "Hans-Christoph Steiner" <hans at at.or.at>, "puredata mailing list" <pd-list at iem.at>
> Date: Monday, August 10, 2009, 6:05 AM
> On Sun, 9 Aug 2009, Jonathan Wilkes
> wrote:
> > --- On Sun, 8/9/09, Hans-Christoph Steiner <hans at at.or.at>
> wrote:
> >> Check the Pd Definitions wiki on http://puredata.info/dev for some discussion on this
> >> stuff.  And please add anything there that you
> think
> >> should be there.
> > On the Pd Definitions wiki, they are referred to as
> elements, and I've
> > already changed the reference patches to reflect
> this.
> 
> I wouldn't quite advocate using the PdDefinitions as they
> are now. Much of the way people talk about pd is ambiguous,
> and that includes Miller too. The Pd Manual itself has a
> fair amount of vague talk, but then, the PdDefinitions page
> handpicks quotes in it without regard to whether "the
> definition of float" is about float-values, float-atoms,
> floatatom-objects, the floatatom class, the strings
> recognised as floats, or the strings that floats are
> outputted as; and likewise for several other definitions
> lifted from the manual.
> 
> "atoms are either numbers or symbols" -> that's only
> when you look at what you can write in a messagebox that can
> end up as-is in a message. This ignore comma atoms,
> semicolon atoms, dollar atoms ($1), dollsym atoms ($1-blah),
> and pointer atoms (which can't be produced by the parser).
> 
> "There are two atom boxes, floatatom and symbolatom" ->
> this is irrelevant to the definition of an atom, of a float,
> or of a symbol, in that you could make patches without ever
> using any atomboxes and you could still see all the
> characteristics of float values and symbol values shine
> through.
> 
> "Anything that is not a valid number is considered a
> symbol." -> this is only in the context of parsing, and
> only once the commas and semicolons are dealt with.
> 
> "The selector is a symbol, which appears in the patch as a
> non-numeric string with no white space, semicolons, or
> commas." -> the manual doesn't take into account any
> weird thing you can do in Pd, even with pure pd, and even
> without hand-editing any .pd files. E.g. this patch:
> 
> #N canvas 0 0 450 300 10;
> #X obj 12 31 makefilename %d;
> #X msg 12 13 123;
> #X msg 12 67;
> #X msg 12 49 set \$1 \, bang;
> #X obj 12 85 f;
> #X connect 0 0 3 0;
> #X connect 1 0 0 0;
> #X connect 2 0 4 0;
> #X connect 3 0 2 0;
> 
> ends up saying:
> 
>   no method for '123'
> 
> but "no method for" errors always state the selector, and
> here, 123 is a selector, which is a symbol, but is printed
> in a way that makes it look like a float.
> 
> > Because of the way they are laid out, I don't think
> there is any ambiguity between first element and selector in
> the help patches (I don't think "selector" is used in any of
> them, but I'll check and make sure).
> 
> Selector ought to be used to talk about all those so-called
> "meta-messages", not only because the Pd Manual does, but
> also because the manuals of several other programming
> languages call that same thing by the same name. It's not
> like selectors are a weird thing from outerspace that got
> stuck into Pd for no reason (even though some facts about
> Pd's selectors are a bit weird).

Other than the help patch for [list], the term "selector" hasn't 
come up much because each inlet/outlet just has a list of accepted 
messages and a description.  So for the left inlet of [delay], "bang", 
"float", and "stop" are listed (without quotes), and the description 
for "stop" is the phrase "causes [delay] to cancel its scheduled output." 
When referencing selectors I've just been using a phrase like "sending 
a 'stop' message."  This fits the terminology that is already in the 
bulk of the help patches, and I think the meaning is clear.

The word "selector" appears mainly where the presence or absence 
of a selector could easily lead to confusion- in a subpatch in 
print-help.pd, route-help.pd, and probably for [symbol] and [list] though 
I haven't done those yet.  Unlike the word "message" (or the word "word"), 
I think "selector" requires a definition when it is used, or at least 
a reference to the manual where it is explained in detail.

-Jonathan