Re: one other thing - documentation

[Graham Percival]

On Tue, Apr 21, 2009 at 03:54:55PM +0200, Simon Bailey wrote:
> On 20 Apr 2009, at 14:34, address@hidden wrote:
>> You could make these conventions explicit - I had to learn about them 
>> by trial and error.
>>
>> cis'4 is a valid command; cis4' is not.
>
> there is a perverse logic to this, which makes it not a convention but  
> syntax. the ' and , are actually part of the pitch, the numbers only  
> designate the duration and can be omitted. you are right, it is not  
> explicitly stated anywhere, if graham's ok with it, i'll add a patch to 
> the LM 2.1.2 to clarify this point.

If you have an idea for a general clarification that the syntax is
"pitch duration other", then I'm all for it.  If it's a simple
"you need to put the ' before the duration", then I'd probably
reject it as being insufficiently general.

... of course, I'm not certain if 2.1.2 is the right place for it,
nor whether somebody reading only 2.1.1 and 2.1.2 will know what
we mean by "other".


I'm not just being grumpy here.  Writing good documentation --
newbie documentation in particular -- is *hard*.  (then again, I
suppose that doing /anything/ well is hard)
I'm all for clarifying this point, but it needs to be in the right
place.  I'm not convinced that it shouldn't be in 3.1.x.  Granted,
a first-time reader might not get that far before running into
some problems... but then again, *none* of the documentation
examlpes use 4' so I'm not certain we need to be vitally explicit
about this as soon as possible.

I think I've just convinced myself that a paragraph-long
discussion of each note -- pitch, duration, other -- belongs
somewhere in 3.1.  I can be convinced otherwise with a
sufficiently good argument.

Cheers,
- Graham