[PD] Help Docs: element vs. item

Mathieu Bouchard matju at artengine.ca
Thu Aug 13 19:35:37 CEST 2009


On Wed, 12 Aug 2009, Jonathan Wilkes wrote:
>>> --- On Wed, 8/12/09, Mathieu Bouchard <matju at artengine.ca>
>> I'm not looking at a template, why?
> Because I'm using the pddp template to revise the help patches.  I don't 
> see a simple way to add column headings to the templates.  Were you 
> suggesting adding column headings, or something else?

Oh, column headings wouldn't have hurt, but I'm not gonna advocate it as 
long as PDDP doesn't have massive shortcuts for things like that... else 
it's a lot of wasted time.

>> I don't think that it's a good idea to directly connect "what you type" 
>> with "what you get", except in examples. The theory should connect 
>> "what you type" with an internal representation, and connect the 
>> internal representation with "what you get", or any other number of 
>> intermediate steps, whatever is needed to make people distinguish 
>> between "a symbol" and "the spelling out of a symbol by a user" and 
>> "the printing out of the symbol by pd" and other things. It's more 
>> obvious (and more critical) if you think of the float situation.
>
> I don't think I understand your point.  A float is referred to as a 
> "float" in the help patches.  The patches don't refer to a "float 
> message," or "float selector."  So I don't see a problem with how float 
> is handled in the current docs.

I mean things like: you can input a float as any number of digits, and 
that has a precision that has a power of ten, but then, once it enters Pd, 
it will have a precision that is a power of two, and that's when it enters 
actual objects, but whenever the numbers are printed out, they will be 
printed with a power-of-ten precision, but will have been converted from a 
number that has a power-of-two precision, and it will pick the number of 
digits that it wants to, which is probably not the number of digits you 
entered in the first place, and which is less digits than what is 
available in the float values as they are used in pd objects, and this 
affects directly what happens when you save/load patches... e.g. you can't 
even write "1234567" as a regular number in a regular sentence in a pd 
comment and have it stay that way when you save and load.

But this particular topic doesn't necessarily affect anything in most help 
patches.

> But if you look at the Max docs where they say, "the word 'set' followed 
> by a number", there's not even that.  Yet the wording is clear, 
> succinct, and unambiguous.

Well, it's not technically unambiguous, but pretty much everybody will 
understand that this means «set 123» and not «set123» nor «set, 123», and 
that this could be «set $1» as long as $1 represents a number. Frankly, 
those "unlikely" mistakes are done a lot more by beginners than we know or 
like to admit, but at once, the wording can't be complicated so much, 
especially if it's going to be repeated over 1000 help files... though I 
guess it's not a bad idea to make a help patch that shows how to read a 
help patch, and have beginners read it early on. In short, the Max-style 
wording is probably fine.

  _ _ __ ___ _____ ________ _____________ _____________________ ...
| Mathieu Bouchard - tél:+1.514.383.3801, Montréal, Québec


More information about the Pd-list mailing list