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

[Graham Percival]

Han-Wen said pretty much everything I was planning on saying, but I'll 
add/summarize some points:

1.  Long musical examples in the manual are out.  (cut+paste difficulty, 
looks complicated, adds unnecessary length to sections -- my ideal 
length is no more than two pages of HTML for each subsection)


2.  I'm open to replacing manual examples with musical ones, provided 
that the musical example is just as clear as the existing one... but 
this is much *much* harder than it looks.  That was the first lesson I 
learned when I started working on the docs: the easier it is to read, 
the harder it is to write.  (Which sucks, because if it's easy to read, 
everybody assumes that it's easy to write.  Then again, the same is true 
about performing music: better players make it look easier.  :)

I could elaborate on this point if you want.


3.  I completely agree that fancy, sexy, musical examples are a good 
thing for the manual.  We already have the place for it:   second item 
down on the right-hand column of the main doc page.

Unfortunately, with the possible exception of Cary (sorry about the 
missing accents), AFAIK this page hasn't been updated since 1.6.


If there's interest in adding fancy, sexy, musical examples, I'm 
completely available to organize it and improve the backend.  (starting 
in about a week, though)   If there's sufficient user interest, this 
could even make it into 2.14.  But I'm not interested in 
writing/transcribing these examples myself; it has to come from the users.

Cheers,
- Graham