Re: GDP: partial rearrangement done, technical problems
On 9/20/07, Graham Percival [EMAIL PROTECTED] wrote: 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. The notation / instrument-specific division is fine, imo. But it does seem odd to have Chord names as part of the instrument-specific stuff. Are chord names instrument specific? If you think of chords names as primarily useful in theory class, then Educational use might make sense; on the other hand, if you think of chord names for lead sheets, then maybe they should just become their own chapter in the notation section. Either way, maybe move Chord names to the notation section. Also, I agree with an earlier comment (somehow lost it in the thread) that both Strings and Bagpipe should promote to full sections in the instrument-specific part. It's OK that they be small; they can just function as placeholders until more such content shows up later. That will get rid of the other instrument stuff junk drawer. - 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? Ew. I don't like. Reading 1.2.3 is choppy. And the bold subsection titles hurt rather than help. Here's an extraction of the 1.2.3 subsection titles right now: 1.2.3 Displaying rhythms Time signature Commonly tweaked properties See also Bugs Upbeats Bugs Unmetered music Bugs Polymetric notation Bugs Automatic note splitting Bugs See also Doesn't flow. And makes us look like we have an undue preoccupation with bugs. A better structure would be: 1.2.3 Displaying rhythms Time signature Upbeats Unmetered music Polymetric notation Automatic note splitting See also We don't need but bug subsections printed as separate subsections with separate headers. Just format the content of the @refbugs as regular old paragraphs with no special headers. The chunking will then look like the revised ex above (focusing on the musical ideas), and we won't appear to be so wrapped around the axle about bugs. As far as the LSR stuff, maybe include all external links (whether LSR or see also, or whatever) in a single See also section at page bottom? -- Trevor Bača [EMAIL PROTECTED] ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
GDP: partial rearrangement done, technical problems
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 ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: partial rearrangement done, technical problems
On 20.09.2007 (00:55), Graham Percival wrote: GENERAL DISCUSSION - I still like the division of musical notation / instrument-specific? No? I have nothing against it, as long as vocal music isn't stuffed in there. :-) - 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? I think it should be next to where the properties that are commonly tweaked are described. That particular section reminded me of something that's been bugging me before: Lilypond has many defaults, which is fine, but somehting like: Setting it to #'() uses fraction style for 4/4 and 2/2 time, just makes me wonder: why!?! This is one of those cases where the middle ground is missing between the beginner (who would take it as a piece of information and that's that) and the programmer (who would know how to look up the program reference. 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? I don't mind. ... and are you guys _sure_ you prefer the manual like this? Other than that I still don't like the headings Displaying ... Thanks to the defaults, you are, for all intents and purposes, displaying a rhythm by writing c8, aren't you? For some of the topics something like Modifying the display/presentation... might work, but I'd like to see the reader who would go to a heading like that to find out how to write a key signature. Eyolf -- Q: How many mathematicians does it take to screw in a light bulb? A: One. He gives it to six Californians, thereby reducing the problem to the earlier joke. ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user