Re: Figured bass Documentation issue

[Graham Percival]

On 24-Nov-04, at 6:27 AM, Laura Conrad wrote:
> There might be better words to use than "eats".

I don't understand how FiguredBass works, but how's this?

Figured bass is created by the FiguredBass context which responds to
figured bass requests and rest-requests.  You must enter these using
the special @code{\figuremode @{ @}} mode, which allows you to type
numbers, like @code{<4 6+>}.

"eats" -> "responds to"

If that's a better way of phrasing it, I'll commit it.

> But I don't see that note-requests are being treated any differently
> from rest-requests.  In both cases, the FiguredBass context is taking
> the timing values and using them to decide where to put the figures,
> but not otherwise displaying them.  So leaving out note-requests from
> that sentence was really misleading, especially to someone who had
> read the previous version.

Umm... sorry, I'm really lost here.  Should I add an extra sentence?
(see below)

Figured bass is created by the FiguredBass context which responds to
figured bass requests and rest-requests.  You must enter these using
the special @code{\figuremode @{ @}} mode, which allows you to type
numbers, like @code{<4 6+>}.  It does not respond to note-requests.


>     Mats> Seriously, the comments in the Regression test files have 
> probably
>     Mats> been formulated mainly to be read by the LilyPond hackers. 
> The official
>     Mats> documentation is in the notation manual. Of course, this is 
> a pity,

I consider all the docs on the left-hand side of the Documentation page 
to be
user documentation.  The NEWS and INSTALL are semi-user stuff (ie a new
user doesn't care about previous news, and is either unix-y enough to 
need the
instructions for compiling on NetBSD or shouldn't be reading the 
"compile
from source" install page).

>     Mats> since I find the Regression Tests document one of the best 
> sources of
>     Mats> examples for LilyPond users on all levels.
>
> I consider the examples to be part of the documentation.  As do the
> Debian packagers, who put them in a directory called
> /usr/share/doc/lilypond/examples.  It really wouldn't be possible to
> write a clear, concise manual with all the stuff you need to have a
> working lilypond file, and lots of us never really write all that
> stuff -- we either snarf one of the example files or let a converter
> like abc2ly write it for us.

I agree that examples are vitally important, and we should include more.
But I don't consider the Regression Tests to be the best place for
examples.

If there's specific wording that's confusing (such as above), I'm happy
to change it -- provided that this is ok with developers who use the
Regression Tests as actual tests -- but I think it's better to spend 
more
effort working on the manual.  In this case, section "5.6.13  Figured
Bass"

Cheers,
- Graham