Re: 2 bugs + documentation patch

[Jan Nieuwenhuizen]

Mats Bengtsson <address@hidden> writes:

> I spent some more time on the reference manual, I'm soon 
> half way through now!

Good work!

> - 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.

> - Why not rename "Bugs" to "Limitations"?

I don't like euphemisms too much but, oh well.

> - 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.

> - Should the manual be written in Brittish or American english?

The GNU project standardises on american english.  Much as I
personally detest it, I agree with Han-Wen that it's best to go
american spelling.

> - The section titling is not consequential, some are in singular form
>   and some in plural. For example, we have a section "Breath marks"
>   followed by a section "Text spanner". 

Please fix.  Also, we have `Beaming' vs `Slur'.  I guess singular
makes most sense.

Btw, a lot of these details just haven't got the attention that they
deserve, if someone notices something strange, best is to fix it right
away (if you want) and not think Han-Wen or I had some grand visions
about it.

Jan.

-- 
Jan Nieuwenhuizen <address@hidden> | GNU LilyPond - The music typesetter
http://www.xs4all.nl/~jantien       | http://www.lilypond.org