Re: Doc: NR 4.1: Reorganize, clarify details. (issue2758042)

[Carl . D . Sorensen]

Mark,

What a lot of work!  Thanks for taking this on!

I think that this is a big improvement, because of its thoroughness.

I think that your subheadings need to become nodes (subsubsections?).

I think that it would be nice if the defaults are easily accessible in a
file somewhere to point us to them instead of explaining them all.  If
they're not easily accessible, then go ahead with what you've got here.

Thanks,

Carl



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

http://codereview.appspot.com/2758042/diff/1/Documentation/notation/spacing.itely#newcode246
Documentation/notation/spacing.itely:246: the default paper size,
@code{paper-height} is @code{297\mm}.
I don't like the idea of putting the default in the docs in this way,
because it's a detail to try to keep up.  A reference to a file that
declares the default is better long-term.

http://codereview.appspot.com/2758042/diff/1/Documentation/notation/spacing.itely#newcode275
Documentation/notation/spacing.itely:275: @c TODO: why? -mp
Because it's much nicer in a sparsely-populated page to have the space
at the bottom of the page than spread out among all the staves in the
system.

http://codereview.appspot.com/2758042/diff/1/Documentation/notation/spacing.itely#newcode590
Documentation/notation/spacing.itely:590: the default is
@code{(address@hidden@address@hidden/210)@tie{}\mm}, where
Can these defaults be looked up easily in a file somewhere?  If so, I
think a reference would be better here.  There's too much detail, and I
can't easily see the big picture.

If this is defined in a file somewhere, then I think this constitutes
"talking through the code" of the file where it's defined.

http://codereview.appspot.com/2758042/diff/1/Documentation/notation/spacing.itely#newcode647
Documentation/notation/spacing.itely:647: @subsubheading Two-sided mode
I think reorganization is needed, because this should be a node, IMO.

http://codereview.appspot.com/2758042/