On Wed, 12 Aug 2009, Jonathan Wilkes wrote:
--- On Wed, 8/12/09, Mathieu Bouchard matju@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