[PD] Help Docs: element vs. item

[Jonathan Wilkes]

> 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.

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