[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: documentation suggestion
From: |
Trevor Daniels |
Subject: |
Re: documentation suggestion |
Date: |
Mon, 10 Nov 2008 09:18:43 -0000 |
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