Re: GDP: rearrange manual

[Reinhold Kainhofer]

Am Montag, 10. September 2007 schrieb Graham Percival:
> Rune Zedeler wrote:
> > Well, in its current state I find the "each subsection has its own page"
> > version of the manual unusable, and therefore always uses the one big
> > page manual. I suggest that we gives each section its own page containing
> > section and all subsections. Ofcourse each section should still contain a
> > table of links, but the links should stay on the same page (just as the
> > one big page documentation does now).
>
> What makes the "each subsection has its own page" unusable?  Is it the
> lack of a good index?  

Often I know what I need, but I don't know how to name it exactly, so an index 
with some selected keywords is not so helpful. In these cases, I tend to go 
to a page that treats that subject, and do a full text search (or with the 
short subsections in the lilypond documentation click through all subsections 
of that sections, manually scanning the section for what I'm looking for). If 
lilypond's documentation has larger sections (one for each larger topic), 
doing a text search is possible and I don't have to "read" (i.e. quickly scan 
each page visually for what I'm looking for).

The other reason is that it's easier to remember where to find somethings. 
Currently, whenever I look for that nice lilypond example of all 
articulations, I go to the contents, search for "articulation", and then from 
that page, I know I have to take the "Articulations" link to the page I'm 
actually looking for.

Having everything related on one page removes the need to click through many 
pages, and additionally makes it possible to print out only the wanted 
section.

> One possibility is to have larger subsections, but use @subheading to
> visually divide the page.  

Yes, I would prefer that. 

> In the table of contents, we would see a 
> single "Dynamics" subsection, but the HTML page itself would be

Cheers,
Reinhold


-- 
------------------------------------------------------------------
Reinhold Kainhofer, Vienna University of Technology, Austria
email: address@hidden, http://reinhold.kainhofer.com/
 * Financial and Actuarial Mathematics, TU Wien, http://www.fam.tuwien.ac.at/
 * K Desktop Environment, http://www.kde.org, KOrganizer maintainer
 * Chorvereinigung "Jung-Wien", http://www.jung-wien.at/