Re: Doc: NR 4.4.1: Rewrite. (issue2642043)

[markpolesky]

Wow, this is almost done.  New patch set uploaded.  I've
responded to some comments individually, and made a lot of
small changes requested, but I want to call everyone's
attention to the TODO on l.1504, regarding this clause:

"the reference point of a non-staff line is its highest
point."

Keith points out that the refpoint for Lyrics seems to be
the lowest point (or perhaps the baseline?).  It would be
nice if someone could clear this up (or figure it out).
What are the actual reference points for each type of
non-staff line (ChordNames, Dynamics, FiguredBass,
FretBoards, Lyrics, and NoteNames).

I'd like to fix this before pushing.

Also, in an attempt to improve the examples, I made some
changes.  So feel free to look them over if you like.

I know this is a lot longer than what's there now; hopefully
that's more a reflection of the amount of information than
any wordiness on my part.

Thanks again to everyone reviewing this.
It's a big help.
- Mark


http://codereview.appspot.com/2642043/diff/14001/Documentation/notation/spacing.itely
File Documentation/notation/spacing.itely (right):

http://codereview.appspot.com/2642043/diff/14001/Documentation/notation/spacing.itely#newcode256
Documentation/notation/spacing.itely:256: a system is the middle line of
the nearest staff---even if a
On 2010/11/04 16:11:54, Graham Percival wrote:
> I think that we normally write "staff -- even".  I don't
> know if texinfo treats different amounts of hyphens
> differently, or whether the space matters.

Looks like yet another UK vs. US thing:
http://en.wikipedia.org/wiki/En_dash#En_dash_versus_em_dash

http://codereview.appspot.com/2642043/diff/14001/Documentation/notation/spacing.itely#newcode1528
Documentation/notation/spacing.itely:1528: To change any spacing
settings globally, put them in the
On 2010/11/05 05:20:39, Keith wrote:
> "throughout a score" instead of "globally"

But a toplevel \layout block can apply to multiple scores,
right?

http://codereview.appspot.com/2642043/diff/14001/Documentation/notation/spacing.itely#newcode1540
Documentation/notation/spacing.itely:1540: The global defaults for the
following grob properties are defined
On 2010/11/05 05:20:39, Keith wrote:
> if you say "defaults for StaffGrouper and
> VerticalAxisGroup are" then you can skip the list.

I'd rather not since there are 5 properties that are *not*
initialized there.

http://codereview.appspot.com/2642043/diff/14001/Documentation/notation/spacing.itely#newcode1572
Documentation/notation/spacing.itely:1572: staff-group, it is usually
best to leave this property unset,
On 2010/11/05 05:20:39, Keith wrote:
> Let's be honest here " ... it is usually best to leave
> this property at its default, which is a function that
> chooses the appropriate spacing from the StaffGrouper
> object."

But every time I write something like that, I get
complaints about "talking through the code"!

http://codereview.appspot.com/2642043/diff/14001/Documentation/notation/spacing.itely#newcode1584
Documentation/notation/spacing.itely:1584: staves.  Does not apply to
the bottom staff of a system.
On 2010/11/05 05:20:39, Keith wrote:
> Suggest : "The value used for next-staff-spacing, if you
> did not override next-staff-spacing explicitly, for a
> staff that is not in a group (or for which StaffGrouper
> does not define a spacing)."

This is better, so I'll use it (with a few changes).

http://codereview.appspot.com/2642043/diff/14001/Documentation/notation/spacing.itely#newcode1836
Documentation/notation/spacing.itely:1836: @code{staff-affinity} from
top to bottom.  For example, the
On 2010/11/04 08:37:34, Valentin Villenave wrote:
> I wouldn't use the property name here in the main text,
> but rather write a sentence describing its effect (in
> order to not "talk through the code")...

Or should I just remove this altogether, since it's already
discussed on line 1592?

> Also, I find that the sentence "the following code is
> undefined" isn't very clear.  Could you rephrase it as
> "the following code does not have any effect", or
> something like that?

Ah yes, the correct word is "unspecified".

http://codereview.appspot.com/2642043/