Re: doc enhancement for \headers

[Graham Percival]

On Thu, Jul 05, 2012 at 11:16:52AM -0700, -Eluze wrote:
> 
> Graham Percival-3 wrote:
> >> there are 13 variables that can be defined in the \header block and which
> >> will be used by the default header and footnote engraver:
> > 
> > The problem with such a list is that it's easy to forget to update it… 
> 
> certainly, but a documentation is only worthwhile if it shows the actual
> state - I think LilyPond does a great effort to keep documentations
> up-to-date and if there's a problem with it this should be attacked from
> another starting point.

It _is_ attacked from another starting point -- by explaining as
much as possible with working examples.

There's many reasons why people might not work on documentation.
Poor English from non-English speakers?  Hard-core math-logic
programmers intimidated by writing prose?  People fed up with
nitpicking words and grammar in doc reviews?  Those are all valid
reasons to avoid touching the docs.
(they're not _problematic_ reasons, of course -- but if somebody
doesn't want to edit docs and gives one of those reasons, I
wouldn't blame them)

But what's one "language" that we all speak?  Regardless of our
country, any programming mind-set, etc?  well, "lilypond", of
course.  The basic .ly format is the same regardless of language
(that only changes note names, lyrics, and markup text).  Even if
we have any non-musical programmers working on lilypond, they'll
still have a small "test case" so they can check if their code
works or not.

It's really easy (for some people) to write whole gobs of text to
explain stuff -- and it's easy (for some people) to skim through
whole gobs of text without understanding anything.  But if there's
an .ly example that shows exactly what to do, then it's easier for
people to update that .ly if needed, and it's easier for a "lazy
reader" (like me) to realize that the answer to their problem
really is in the docs and they just need to slow down and
understand the example.

- Graham