Classic new user errors (was Re: Second staff beginning with an acciaccatura defeats "\override Staff.TimeSignature #'stencil = ##f" in the first staff)

[Colin Hall]

On Sat, Aug 18, 2012 at 12:25:12PM +0200, Štěpán Němec wrote:
> On Sat, Aug 18, 2012 at 10:56:17AM +0100, Colin Hall wrote:
> > 
> > About the docs, can you say where you looked and failed to find the
> > correct guidance? It might help with preparation of a documentation
> > enhancement.
> > 
> > To check I went to the section on grace notes:
> > 
> > http://lilypond.org/doc/v2.15/Documentation/notation/special-rhythmic-concerns#grace-notes
> > 
> > Under "Known issues and warnings" there is an example of using skip
> > notes in the voice without the grace note. In that example it is clear
> > in the bad output that something is missing and one might easily think
> > of inserting a grace in the other voice, and then turn that into a
> > skip.
> > 
> > For the case where the music starts with a grace note the source of
> > the problem is much less obvious for an inexperienced user.
> 
> Your diagnosis is quite correct -- I have very little experience with
> Lilypond, so the problem was far from obvious to me. I saw a problem
> with time signature, so that's what I searched for. In the docs I saw
> examples where the override expression worked and had no idea why it
> didn't in my case. Then I just gradually stripped my score into the
> minimal example that showed that the real problem had something to do
> with the grace note.

Well, if it is any consolation, you took exactly the right course.

> _Then_ (i.e., after managing to find the real cause myself) reading the
> Grace notes issues and warnings section would help, indeed, but I don't
> know how likely it is to end up in that section right away when seeing a
> problem with time signatures.

Agreed, very unlikely.

> So to me it seems that having a standalone top level "Known issues and
> warnings" section possibly just accumulating all similar problem
> sections in the documentation and linking to the bug tracker where
> relevant (such as here) would save a lot of head scratching or outright
> frustration for people like me.

I just had a look and there is nothing like that in the docs right
now. There is a faq which appears to be a brief directory to sections
in the documentation.

http://lilypond.org/faq.html

Troubleshooting sounds promising. The link is broken but here is the
correct link:

http://lilypond.org/doc/v2.15/Documentation/usage/troubleshooting.html

That section is good because it describes the process you followed but in the 
vein of compilation failure, rather than unexpected engraving.

However there is no documentation that describes common errors for new
users and their solutions, so perhaps that would be a good idea.

Anyone care to reply with their favourites?

Cheers,
Colin.


-- 

Colin Hall