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

[Carl . D . Sorensen]

More comments inlined.

Thanks,

Carl



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

http://codereview.appspot.com/2642043/diff/1/Documentation/notation/spacing.itely#newcode1501
Documentation/notation/spacing.itely:1501: @item @emph{staff-like
contexts} (such as @code{Lyrics}).
On 2010/10/23 05:01:51, Mark Polesky wrote:
> On 2010/10/23 00:51:31, Carl wrote:
> > I would change this to "non-staff" contexts, I think.  I
> > liked the previous terminology.

> The original "non-staff lines" is still better than
> "non-staff contexts" (which can imply Voice and Score), but
> "non-staff lines" reads like "the opposite of staff lines",
> which is confusing.  I suppose defining the term clearly at
> the top will help.  If I change it back to "non-staff
> lines", I should change the others to "staves" and
> "staff-groups".

I don't think it's  confusing at all.

staff contexts are contexts that are displayed in a staff.

staff-group contexts are contexts that are displayed in a group of
staves

non-staff contexts are contexts that are displayed in something besides
a staff.

Voice is a context that is displayed in a staff.

Score is not displayed in anything, as far as this is concerned.

Also, we're not talking about non-Staff contexts, we're talking about
non-staff contexts.  The capital letter is important (and it can be
explained here if we need to).

http://codereview.appspot.com/2642043/diff/1/Documentation/notation/spacing.itely#newcode1506
Documentation/notation/spacing.itely:1506:
On 2010/10/23 05:01:51, Mark Polesky wrote:
> 23 00:51:31, Carl wrote:
> > I think that you should explain the different grobs that
> > are created by each of the contexts at this point.  I got
> > lost while I was waiting.

> Already in the intro?  I think just after the "Inter-system
> spacing properties" heading is a better place.  I'd prefer
> to just change the previous sentence to:

No, not already in the intro, but before I got to the real explanation.

You tell me about three different kinds of contexts, then you go talk
about the different spacing properties in terms of Grobs  --
VerticalAxisGroup and StaffGrouper.  But I don't know what those mean in
terms of staff-group, staff, and non-staff contexts that you've already
explained.  It's not until line 1746 (240 lines, or 4 pages + later)
that you explain that VerticalAxisGroup properties apply to ungrouped
staff contexts, and so forth.

If you're going to tell me about the three kinds of contexts, give me
some clues so I can understand the next stuff I'm reading.
> Also, even though staff-group
> contexts don't create the VerticalAxisGroup grob, their
> constituent staves do, and this in turn influences their
> spacing.  I think your suggestion might be a little
> misleading.

No, because later on you describe the full spacing algorithm.

The VerticalAxisGroup properties control the spacing of individual
staves.

The StaffGrouper properties control the spacing of groups of staves.

http://codereview.appspot.com/2642043/diff/1/Documentation/notation/spacing.itely#newcode1554
Documentation/notation/spacing.itely:1554: @item @code{minimum-distance}
-- the minimum required vertical
On 2010/10/23 05:01:51, Mark Polesky wrote:
> On 2010/10/23 00:51:31, Carl wrote:
> > I think I would change "minimum required" to "minimum
> > allowable"


That's true if you're starting from zero, I think.  But if you're
starting from a big number, and trying to squeeze it down, (which is
what we're doing), then I think the "minimum allowable" is more
descriptive.

But I don't feel strongly about this.
> Huh.  For me, the phrase associations are "minimum required"
> and "maximum allowable".  Such as "you must have at least x"
> and "you are allowed no more than y".

http://codereview.appspot.com/2642043/diff/1/Documentation/notation/spacing.itely#newcode1578
Documentation/notation/spacing.itely:1578: @subsubheading Modifying
spacing alists for grob properties
On 2010/10/23 05:01:51, Mark Polesky wrote:
> On 2010/10/23 00:51:31, Carl wrote:
> > Reference to the between system spacing, instead of
> > repeating.  Just introduce the new syntax as it applies to
> > the in-system contexts.

> You mean a link to NR 4.1.2 "Modifying spacing alists for
> \paper variables"?  That's not a bad idea, but that section
> is a texinfo "subsubheading", which IIRC can't be a
> cross-referencable node.  I'll look into this.

Great.  We should make it a node.

http://codereview.appspot.com/2642043/diff/1/Documentation/notation/spacing.itely#newcode1881
Documentation/notation/spacing.itely:1881: @item @code{ChordNames}
On 2010/10/23 05:01:51, Mark Polesky wrote:

> Hmm.  One argument for an exhaustive list would be that it's
> just good to know that FretBoards and FiguredBass are
> "non-staff lines" with spacing that's just as customizable
> as Lyrics.  Perhaps the ideal solution is to include a
> sentence in each of the sections that describe these
> contexts, such as:

> "For purposes of vertical spacing, FigureBass contexts are
> considered non-staff lines.  See `Spacing of non-staff
> lines'."

> But I still like the appearance of FretBoards and the others
> alongside Lyrics and ChordNames.  What if I just say:

> "Examples of non-staff lines include: ChordNames, Dynamics,
> FiguredBass, FretBoards, Lyrics, and NoteNames."

> That way, if a context is added to the code base later, it
> doesn't invalidate the sentence, since it doesn't claim to be
> exhaustive.

THat would be better.  It would be even better if we gave the user a
clue as to how to find an exhaustive list in the IR, e.g. all contexts
that create a VerticalAxisGroup but not a StaffSymbol (I'm not sure if
this is the right criterion or not).

http://codereview.appspot.com/2642043/diff/1/Documentation/notation/spacing.itely#newcode1897
Documentation/notation/spacing.itely:1897: @item
@code{inter-loose-line-spacing}
On 2010/10/23 05:01:51, Mark Polesky wrote:
> On 2010/10/23 00:51:31, Carl wrote:
> > Since the property name is inter-loose-line-spacing, we
> > may want to call these contexts "loose line contexts"
> > instead of staff-like or non-staff contexts.

> Um, I don't want to scare anyone, but I'll be proposing some
> name changes for these properties, too.  And I currently
> prefer "non-staff lines" over "loose line contexts".  But
> let's not get into that just yet.

I'm fine to defer it, but we should be consistent when it finally gets
done.

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