Re: 2 bugs + documentation patch

[Mats Bengtsson]

> > - Its not obvious how the different sections should be ordered.
> 
> Yes, that's why I tried adding outline mode to see the structure more
> clearly, and be able to move closed topics around very easily.
> It proved a bit unmaintainable, though (to be fair, emacs outline
> modes are a mess and don't cooperate with texinfo mode).  If you find
> bugs in the order, please fix it by moving them.

Will be!

> > - The general structure of the manual, especially the division 
> >   between ordinary text and autogenerated text should be explained
> >   at one of the first pages. Can we replace the term "automatically 
> >   generated documentation" when referencing this part?
> 
> I don't really see what you mean here, but people don't tend to know
> that the autogenerated stuff exists, or may be useful to them.  We
> should really try to improve on that.
> 
> > - Almost all the reference manual requires a basic understanding
> >   of the syntax and the lexical modes. Also, it's important to 
> >   understand the property handling. Therefore, it's a pity that
> >   these concepts are explained first at the end of the manual.
> 
> Well, I don't know.  Technically, you're right.  But in practice, most
> examples can probably be parsed by a human without too much
> knowledge of LilyPond.
> 
> Problem is, if you start with lexical modes and syntax stuff (this is
> what we had before), you'll have to explain it to the very last
> detail.  The manual starts off with some 10 odd pages of difficult,
> generally unimportant and very boring details.  I hoped that the
> manual would be more attractive to read if it started off with easy,
> most used and important stuff first.
> 
> Maybe we need a small introduction?  But then, we have the tutorial.
> If you can't read the refman, you want to peek at the tutorial first.

I think an introduction/reading instruction to the reference manual
part is the way to go. I'll give it a try.

    /Mats