Re: GDP: length/page-splitting of subsections

[Juergen Reuter]

On Mon, 10 Sep 2007, Graham Percival wrote:

> To summarize some discussions:
> ...
>
> - Does anybody _like_ the current layout?  If so, speak up now or forever 
> hold your peace.  :)

I am _fine_ with the current layout.  However, I agree that for 
global searching in the web browser, you need a big html page, as has 
already pointed out by various other people.  However, if you really _cry_ 
for global searching, this fact may indicate that the current index is 
(for whatever reason) unsufficient.

Regarding the current index, I wonder why the items of the command index 
also appear in the large index, thus making it unnecessarily long.  Lack 
of consistency is IMHO another major problem (btw. there is a typo in the 
index as of .32: "\displayLilyMusc" iso. "\displayLilyMusic").  Another 
problem is that documentation writers often do not consider under which 
terms a reader of the manual may try to look up a feature; often only the 
most specific term is used; synonyms or categorizing terms are missing. 
One example (which is most likely my own fault ;-)) is ancient notation: 
if you are looking for "ancient" in alphabetical order, you will not find 
anything in the index.  "Ancient" only occurs in composed terms such as 
"rests, ancient" or as part of the associated section name.  At least in 
the printed version (i.e. without CTRL-F search available) you are lost. 
Similarly, you will find "killCues" only under "k" but not under "cues" 
(i.e. if you do not know the exact name, it will be hard for you to find 
it in the manual).

Furthermore, I would like to see entries like

  \displayLilyMusic: Displaying LilyPond notation
  \displayLilyMusic: Displaying music expressions

rather being structured as follows:

  \displayLilyMusic:
      Displaying LilyPond notation
      Displaying music expressions

Given the large size of the documentation, a single person probably can 
not care for documentation-wide consistency of these (important!) 
nitpicks.  Maybe a general good idea is to collect a couple of "do" and 
"don't" examples as guideline for documentation writers?

Greetings,
Juergen