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.
Before I saw the PDDP template, I tried using an abstraction and entering all the inlet/outlet/argument info as args to the abstraction in order to separate the content from the formatting. It wasn't too bad because you can use semicolons in object boxes to get line breaks (and just filter them out later).
Since every help patch uses the same abstraction, you would just make formatting changes once. If there's an object that automatically lists the methods of an object, then all you would need for each help patch is to enter the name of an object (plus maybe some keywords) as arguments to the abstraction.
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.
I have a help-on-help abstraction (it's just called help) in each help patch, and I thought it would be cool to sprinkle little graphical ds arrows in it to point out the various parts of the help patch. They turned into little sprinkles of pepper when I tried to save and reopen the patch, but now I'm thinking maybe I can just make 1000s of broken ds-instances and cluster them all together to form the shape of arrows.
-Jonathan