[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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 (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:

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.


- 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
- @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?


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

- Graham

reply via email to

[Prev in Thread] Current Thread [Next in Thread]