Re: Documentation - index bug - noteheads

[Graham Percival]

On 7-Jun-06, at 3:19 AM, Anthony Youngman wrote:

> Section 6.6.1 should just be indexed as "NoteHead". It contains an
> example of its use - indeed as I say the only example that appears to 
> be
> for generic use. Looking at it in the index led me to believe the
> references were for ancient music (although in part that was me not
> looking hard enough, but I still wouldn't have found what I was looking
> for).

What's the section name of 6.6.1 in your docs?  In the latest 2.9 docs, 
6.6.1 is Articulations, and I can't see any noteheads in there.

> The existing "note heads" entry should be retitled "note heads, 
> ancient"
> because it points you at "7.7.1 Ancient note heads". Actually, having

Done, thanks.

> found and looked at the index for NoteHead, the "note heads" entry
> should either be dropped, or expanded to make it consistent with
> NoteHead. I'd prefer the latter, but the result will be a bloated index
> ...

The "NoteHead" entries are added automatically whenever the internals 
docs are referenced.  If I were writing the docs from scratch, I 
wouldn't have added them, but I'm reluctant to remove those links 
without a great reason.

> Suggestions are "note heads, special" for 8.4.5, "note heads, shape" 
> for
> 8.5.4, "note heads, easy notation" for 8.5.5 (sorry this was what I was
> looking for as a "practice notehead" - I obviously didn't look hard
> enough).

Done, thanks.  Again, please state the section title as well (8.4.5 
Special noteheads, 8.5.4 Shape note heads...).  When I'm looking at the 
source code for the docs, I don't see any numbers.  If I only have 
"8.5.4", I need to look at the HTML docs to find out what the title is.

I gave easy notation two entries:
@cindex note heads, practice
@cindex note heads, easy notation


> By the way, is there an overarching philosophy behind the manual, or 
> has
> it "just growed" as users have made suggestions?

It has mostly "just growed" as developers have added things.  User 
suggestions don't write documentation; people write docs.  And anybody 
can write docs; all you need is an email client and some interest.

I have a general idea of an overarching philosophy for the docs, and I 
make sure that new docs fit that.  And every so often I'll review a 
chapter and modify it to fit in with that overarching philosophy.  Each 
chapter review takes between 5 and 15 hours, though.  That's a large 
chunk of my volunteer time.

- Graham