Re: For future 2.14 doc discussion -- increasingly realistic musical examples

[Valentin Villenave]

2007/8/30, Trevor Bača <address@hidden>:


> [I'm a little hesitant to speak on this issue because I think my
> opinions differ a bit from the rest of the team. So fair warning,
> subjective opinion coming up. I personally *love* and adore the
> manual. I use it every day. I read it more often than I read the
> newspaper. I couldn't write a thing without it. And it gets better
> every time I look for something new in it. So I've actually always
> been a little frustrated that there are multiple different places to
> look for things in the docsite as a whole.

About this "feature page" obsession of mine:
don't get me wrong : this page would *not*, should *not*, will *not*
in a million years, be another documentation place. The manual and the
LSR are perfect for that, and there shouldn't be hundreds different
places to browse when searching for answers. This page would just be a
demo, an "avant-goût", for users who haven't tried LilyPond yet. What
I have in mind is just a nice, appealing page, with wonderful score
samples. Nothing more, nothing less.

> Tuplets are a good example.
> I use them all the time. And there are a billion different genuinely
> interesting settings for tuplets. But 6.2.3 doesn't capture this. What
> does capture the greatest number of tuplet settings? The reg tests.
> I'm completely fine with that (because I know where to look when I
> need to), but it's always seemed to me like the contents of the
> various tuplet reg tests should be cleaned up (made musically
> realistic) and inserted at 6.2.3.]

About the reg tests:
allow me to quote my official mentor GP: when I became the new LSR
guy, the first assignment he gave me was to add to the LSR any of the
regression tests that might be useful.
--------------------------------------------------------
From: Graham Percival <address@hidden>
Date: 13 avr. 2007 21:08
Subject: Re: LSR Contribution
To: Valentin Villenave <address@hidden>

You'll be dealing with items in the "regression tests" document.
It's currently a huge page (you'll notice this when you first click on
the link).  Users should never have to look at this page (because it's
such a mess); you should be the last user to ever use this page!  :)
---------------------------------------------------------

I completely agree with this way of thinking. I do use the manual as
often as you do, and every time I have to reach for the reg tests, my
first reaction is to think "OK, this one is missing in the LSR", and
add it instantly. Same goes for the list archives. The LSR is
obviously the right place for an exhaustive tuplets demonstration; if
you gave me the precise tests reference, I'll be happy to add it
myself.

> So, like I said, just my opinion. Anyway, with that as background,
> maybe you can see why I'm a little hesitant to advocate for a features
> page? I just really want solid descriptions / examples in the manual,
> which is my bible. (And yet I definitely don't want to be accused of
> bloat.)

Leaving the feature page aside, what I often tried to figure out was:
how to better integrate the LSR with the manual. I can't put links to
the manual in the snippets descriptions (since the links are likely to
be broken soon); neither can I put links to the LSR snippets in the
manual. LSR directories are progressively becoming closer to the
manual structure ; maybe there could be some links at this level (e.g.
in each section of the manual, a link to the corresponding LSR
directory?).

As for the realistic integrated examples, maybe another thing has to
be mentioned: actually, AFAICT there are already two kinds of examples
in the manual: the verbatim ones, and the non-verbatim ones. The
non-verbatim ones tend to be longer, and more complex, whereas the
verbatim examples are basically just a few cut-and-past-able lines of
code. Your second Debussy example, for instance, could hardly be
marked as verbatim (it would double the HTML page length). Maybe this
could help us make a clear distinction between verbatim, pedagogical,
examples, and non-verbatim, "cultural" ones to illustrate the formers.

But then again -- what was your word -- "subjective opinion coming up" :)

Regards,
Valentin