Re: documentation suggestion

[Trevor Daniels]

John Williams wrote Monday, November 10, 2008 2:50 AM


> I think it would be extremely helpful for people attempting to tweak 
> lilypond,
> if there were examples in the documentation whenever a tweak is mentioned. 
> This
> is already the case for most of the beginner's documentation, but when we 
> get in
> to the advanced documentation trying to write our own tweaks, the 
> information
> tends to be spread over many different pages, and requires several 
> searches of
> the mailings lists to find examples of the information actually put 
> together
> into a real tweak.
>
> For example, section 4.5.1
> <http://lilypond.org/doc/v2.11/Documentation/user/lilypond-learning/Moving-objects#Moving-objects>
> talks about the extra-offset property, saying "It takes a pair of 
> numbers..."
> It is quite rare to find a musician who also knows lisp well enough to 
> translate
> that phrase to "#'(1 . 2)".  But one example of an actual tweak in the
> description would make that clear.

There is no need to search the mailing lists.  Section 4.5.1
is just an overview - an introduction to all the usual methods of
moving objects.  Examples are omitted there to give the big picture
more clearly.  Everything mentioned, though, including extra-offset,
is then covered again, with an example, in section 4.5.2.
I would not want to change this separation of overview and
detailed examples.

However, I have noticed that the index does not include a reference
to the extra-offset example in 4.5.2, thanks to your mail.  I'll
definitely fix that!

> Other things examples could clarify is when context is required, or when 
> one of
> the tweak commands works better than others.  I like that lilypond tries 
> to
> determine the correct context when it is omitted, but if I see an example 
> for
> RehearsalMark (maybe on 3.1.80
> <http://lilypond.org/doc/v2.11/Documentation/user/lilypond-internals/RehearsalMark#RehearsalMark>)
> which says "\override Score.RehearsalMark #'extra-offset = #'(0 . 2)" then 
> it
> will help me realize that I should use override instead of set, and that 
> the
> Score context might be required in this situation.

If the context is omitted then Voice is always assumed.  If
Voice is not correct then the context is always shown in
the examples in the Learning Manual and Notation Reference -
the examples there would not work otherwise.  However, this
cannot be done in the Internals Reference, which is generated
automatically from the source code.  The hope is that users
will have become familiar with the need to check the context by
the time they have progressed to using the IR, but I know from
experience this is a common trip-up - I still do it too!  By
now, though, I have learned to check this if something doesn't
work as expected.

Trevor