Re: GDP: partial rearrangement done, technical problems

[Trevor Bača]

On 9/20/07, Graham Percival <address@hidden> 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
address@hidden