Re: How do new users feel about LilyPond's documentation?

[Wols Lists]

On 23/04/15 00:00, Kieren MacMillan wrote:
> Hi Wol,
> 
Hi Kieren
(NB, I've read Thomas' response)

>> What I'd like to see is worked, documented examples.
> 
> I’m happy to supply a few… But there are so many questions:
> 
> 1. Where would they be kept?

Actually, the thought just struck me, maybe Mutopia! :-) Have a location
on the lily website that points to Mutopia examples written specifically
as "good examples".
> 
> 2. How “rich” would the examples need to be, or not be? Even just a one-page 
> excerpt from my Passacaglia for String Quartet would require something on the 
> order of 20 separate files (stylesheets, general tweaks and functions, etc.), 
> which I think would be off-putting for someone just starting out.
> 
Depending on what you're intending to show, as rich as necessary. I get
the impression you are very much into separating style from content. If
you need that many files, then use them, and the comments will explain it.

Indeed, that might make it a lot easier to understand than one
monolithic file - the top-level file will have a bunch of includes, and
if each \include statement is accompanied by an explanation of what the
stuff in that file achieves, then the included file contains an
explanation of how it achieves it ...

That's where I often hit trouble, it's finding stuff in the docu, and
then working out how it's done. From my point of view, a worked and
commented example would be great. For example, I've always been unhappy
with the default header (in band parts, the instrument goes on the
left). But I've only just worked out how to change it. I know it's the
sort of thing that would go in the lsr, but half my trouble there is
knowing the search terms to find what I'm looking for!

And if it starts with "simple" examples, say a song sheet with melody
and words, (simple as in easy to understand with minimal messing with
defaults), up to your complex example, then people can dive in at
whatever level they feel comfortable. The idea would be to find an
example of the sort of work you're trying to do, and then you can either
try to understand it, or to use it as a "monkey see, monkey do" template.

> 3. How would questions of style (e.g., I am now a total crusader against 
> \relative mode) be resolved?
> 
> etc. etc. etc.

There's no right or wrong on style. I use \relative all the time, but if
you always use absolute pitches then just comment that that is what you
do, along with why! You may make converts :-)

It's like I make extensive use of transpose, often doing
"\transpose bf c' { \transpose c' bf { } }"
But I work with parts in a mix of C and Bb (and sometimes Eb etc) so my
style is that music expressions are always in concert pitch. If I'm
copying a transposed part, it is wrapped in a "transpose to concert"
command. If I'm outputting a transposed part, I transpose on output.

So long as we don't try and impose our style as an absolute, then what's
wrong with different styles. Just document it! Actually, the act of
documenting it and seeing what other people do is quite likely to lead
to a standard style as people copy each others' ideas.
> 
> If this is to be part of the official documentation, I imagine it will be 
> even more difficult getting something like that approved than a code patch 
> (which has fairly rigorous “black-and-white” rules), which as you may know is 
> notoriously difficult to get approved.

Well, each example is likely to be self-contained, so hopefully we will
be more concerned about it being well-documented in comments, rather
than objecting to someone else's style.
> 
>> I also keep seeing a lot of stuff about "separating notes from layout".
>> I try to do that, but again, a documented example would be great.
> 
> Again, happy to do it… once the questions are answered satisfactorily.

Thanks, that'd be great.
> 
> Best,
> Kieren.

Cheers,
Wol