[PD] Help Docs: element vs. item
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
> 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