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

[v . villenave]

Hi Mark,

It's the first time I read your NR4 patches, so I may certainly have
missed a few things.

Your patch looks good, but I was a bit surprised by the overall writing
style of NR4.
This chapter looks odd to me, and somehow not on par NR1 and 2. It's
obviously a whole chapter that hasn't been much affected by GDP -- but
of course, I'm not advocating that your patch should rewrite the whole
chapter! :)


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#newcode239
Documentation/notation/spacing.itely:239: @subsubheading Structure of
spacing alists for @code{\paper} variables
Isn't "alist" an abbreviation of "association list"?

http://codereview.appspot.com/2642043/diff/14001/Documentation/notation/spacing.itely#newcode305
Documentation/notation/spacing.itely:305: system-system-spacing #'space
= #8
I'd move the comments to the main text. "...demonstrates two ways these
alists can be modified: first by updating one key-value individually,
then by completely redefining a variable"

http://codereview.appspot.com/2642043/diff/14001/Documentation/notation/spacing.itely#newcode1794
Documentation/notation/spacing.itely:1794: % Here, we allow them to be
stretched more widely.
I would move this to the main text instead of leaving it as a comment.

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
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")...

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?

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