Re: one other thing - documentation

[Simon Bailey]

Graham Percival wrote:
> On Tue, Apr 21, 2009 at 03:54:55PM +0200, Simon Bailey wrote:
> > 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.

my first idea was something along the lines of your refusal. :) i do 
have some other ideas about how to explain the syntax, but they depend 
on where you want to put it in the docs.

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

> 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 haven't found an explicit explanation of the syntax anywhere. 
lilypond's error message is very explicit about the nature of the error, 
but i can see how this may be confusing for beginning lilyponders.

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

where would you put it in 3.1.?

regards,
sb

--
Simon Bailey
Oompa Loompa of Science
+43 699 190 631 25