GDP: partial rearrangement done, technical problems

From:

Graham Percival

Subject:

GDP: partial rearrangement done, technical problems

Date:

Thu, 20 Sep 2007 00:55:43 -0700

User-agent:

Icedove 1.5.0.12 (X11/20070607)

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

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