GDP: partial rearrangement done, technical problems

[Graham Percival]

People who offered to help: I'm sorry I still haven't started the actual 
documentation work yet.  However, these stupid technical problems need 
to get sorted out -- or at the very least, I need to be certain that the 
technical issues _can_ be sorted out -- before I'm going to commit hours 
and hours of documentation editing.  I don't want to waste your time.
-----


I've rearranged the non-instrument-specific portion of the docs; you can 
see them here:

http://opihi.cs.uvic.ca/~gperciva/lilypond/


KNOWN ISSUES  (don't bother pointing these out)

- the subsections in vocal music and ancient music are messed up.

- some HTML links aren't working.  See below.


GENERAL DISCUSSION

- I still like the division of musical notation / instrument-specific? 
No?  Nobody else?  ok, I'll divide up that chapter and stuff it all into 
the monster Musical notation.

- Assuming that the technical issues are solved, how do you want these 
merged subsections to look?  Specifically, consider 1.2.3. Displaying 
rhythms.  There's

Time signature
- @commonprop
- @seealso
- @refbugs
Upbeats
- @refbugs
Unmetered music
- @refbugs
...
Automatic note splitting
- @refbugs
- @seealso


Do you like this format, or would you prefer one @commonprop at the end 
of each page?  Do you want links to LSR stuff at the end of each 
portion, or just one set of links at the bottom of the page?

... and are you guys _sure_ you prefer the manual like this?



TECHNICAL PROBLEMS

This version of the manual was produced by abusing some texinfo 
constructs (ie removing @node -- I tried replacing with them with 
@anchor{}, but those don't do much ).  I've discussed the matter with 
Karl Berry (the texinfo guy), and apparently this was really not the 
right solution.

As I understand it, there are three possibilities:
1)  @node Foo @unnumberedsubsubsec Foo: this will split the manual into 
small HTML pages, which apparently is overwhelmingly hated by users.

2)  @anchor{Foo} @unnumberedsubsubsec Foo: this is the version that is 
currently online; some links don't work.  This kind-of abuses the 
texinfo format.

3)  @subheading Foo: don't print the smallest portions in the table of 
contents.  For example, "Clef" or "Ties" won't show up; users will only 
see "Displaying pitches" and "Curves".

Karl suggested that we could use a post-texinfo script to add these 
items to the TOC.  If somebody wants to play around with python to get 
this working, I'm definitely interested in this possibility.

4)  Use texi2html instead of makeinfo --html.  I've spent an hour trying 
to get this to work; apparently texi2html parses the manual in a 
different way than makeinfo, because our manual compiles with makeinfo 
but not with texi2html (it complains about node / "not in a menu" stuff).

Even if we get texi2html to work, we might need more custom tweaks to 
get texi2html to produce exactly what we want.  It's written in perl, so 
in theory it should be easier to modify than makeinfo (which uses c). 
Another plus is that it looks like development recently re-started on 
texi2html, and they're preparing for a big 2.0 release, so they might be 
more interested in patches that add new functionality.

While we're at it, this could be a good way to produce that frame / 
CSS-not-frame-but-like-a-frame thing that people were talking about a 
week ago.

I'm quite willing to use the CVS-version of texi2html to compile the GDP 
docs.  So if you're a perl developer and interested in this stuff, speak 
up.  I haven't looked at the source code myself, so I don't know what 
kind of perl it is, though.  :)


Cheers,
- Graham