Re: Doc: clashing note columns in example

[Graham Percival]

On Wed, Jun 15, 2011 at 08:31:37PM +0100, Neil Puttock wrote:
> On 15 June 2011 16:36, Phil Holmes <address@hidden> wrote:
> 
> > Strikes me we shouldn't be having examples in the documentation that throw
> > errors in the compilation, though?
> 
> Ideally, no.

Definitely!  In some weird cases[1] it may be impossible to avoid,
but the rule of thumb[2] should certainly be to avoid compilation
errors and warnings.

[1] things like the "removing engavers one by one" in the Essay
cause warnings; I think the only real way to avoid those is by
adding a "warning suppression" system.  That's been discussed a
few times.

[2] the anwer to a warning might be to rewrite the example (maybe
it uses an old/bad syntax?) possibly by asking for help on -user,
or it might be to send a bug report about good syntax causing
false warnings, or it might be something else.  We currently have
20 items with the "warning" label in the tracker.

That said, both possibilities (asking for help on -user and
reporting bugs) have a fairly low probability of actually fixing
stuff.  Before you embark on a large project to clean up these
warnings, seriously consider how much work you can do on your own,
because I personally would not assume that anybody else would help
me if I were to undertake this task.  If you don't feel like you
want to research every syntax possibility (to make sure the
example is good, or improve it if it's not good), and dig into any
false warnings that lilypond produces to produce patches to fix
those, then it will be less heart-breaking in the long run just to
ignore all these compile warnings.

You simply cannot afford to care about anything which you cannot
fix by yourself.  That's one of the biggest lessons I've learned
from 8 years of LilyPond development.

Cheers,
- Graham