David, Thanks for doing this - I know how hard it is to add a large entry in the NR (and that is coming from a Native English speaker).
My comments below are, I hope, constructive. Anything I can do to help you, let me know. https://codereview.appspot.com/319150043/diff/1/Documentation/notation/changing-defaults.itely File Documentation/notation/changing-defaults.itely (right): https://codereview.appspot.com/319150043/diff/1/Documentation/notation/changing-defaults.itely#newcode2514 Documentation/notation/changing-defaults.itely:2514: Properties can be set to new values with the @code{\override}, Bearing in mind my not-very-deep understanding of LP, the preceding paragraphs talk about both context and grob properties as being distinct from one another and how 'grob properties' are just properties of a context's own 'grob definition'. Then explains how 'grob definitions' and 'context properties' are manipulated using different commands - i.e. \override and \revert - where as 'context properties' are manipulated with \set and \unset. Which is the \offset for? One, the other, both? This matters only because a user just looking up the \offset command just get's the explanation that it is just 'Properties' and it is ambiguous (at least to me). While we can show with examples, I think we can improve this opening para. I think, therefore it would be helpful to imply this in the opening para (with words like 'Both Grob properties and context definitions can be set to new ... etc.' or 'While it is possible to set [Grob definitions|Context properties] with the @code{\overrride} ... etc.' I'd be happy to make some grammatical suggestions but as I don't know which of the three possible cases this command affects I am loathe to waste everyone's time by guessing. https://codereview.appspot.com/319150043/diff/1/Documentation/notation/changing-defaults.itely#newcode2522 Documentation/notation/changing-defaults.itely:2522: [-]\offset @var{property} @var{offsets} @var{item} 'Displacements' is not the right word - you 'displace' one object/thing by imposing on it (in it) another 'object/thing' - both things have to exist at once for the displacement to happen, this is as distinct from 'replace'). We're not doing that here. We're simply moving the 'thing' to another/different location from it's expected location. I think 'offset-value' works, that implies a number or 'group' of numbers (to us lesser mortals who don't know what alists and those things with dots in between the two numbers and/or hash signs are called :). https://codereview.appspot.com/319150043/diff/1/Documentation/notation/changing-defaults.itely#newcode2535 Documentation/notation/changing-defaults.itely:2535: The leading hyphen may only be used with the @code{\tweak} form of the 'The leading ... ' or 'A leading ...' - again pardon my limited LP knowledge if it is obvious. However, I think this one sentence needs to be moved to an @knownissues as this seems like some limitation that maybe able to be improved in the future? Again, users look at @knownissues for these kinds of 'funnies'. Also it would be useful to show an @example of the '\tweak' form, as - unless I missed it - you don't show a '\tweak' example with '\offset' in this edit at all. https://codereview.appspot.com/319150043/diff/1/Documentation/notation/changing-defaults.itely#newcode2544 Documentation/notation/changing-defaults.itely:2544: I am a bit worried that, thinking about users like me, that we're starting to be a bit 'programmerish' in some of these following bullets. I also think that, with a bit more insight for me, I may be able to help you incorporate the bullets in the text with some examples. https://codereview.appspot.com/319150043/diff/1/Documentation/notation/changing-defaults.itely#newcode2549 Documentation/notation/changing-defaults.itely:2549: each grob in @rinternals{All layout objects}. Does that mean that if these properties do not, that just mean that the \offset command is redundant (i.e. a user should just use '\set' or '\override'? Perhaps we could show an @example with two properties one that has and one that doesn't have one to show that nothing changes? An example of a property that doesn't have a default would help educate a user when they look up the two layout objects in our examples for themselves to see that one does and and one does not. https://codereview.appspot.com/319150043/diff/1/Documentation/notation/changing-defaults.itely#newcode2555 Documentation/notation/changing-defaults.itely:2555: Again I think this a bit 'talking through the code' (what's a callback?) an @example showing something that doesn't have a numerical value and that doesn't changing when using the \offset command would be illustrative - assuming we're not going to thrown up errors during lilypond-book compilation of the @example. https://codereview.appspot.com/319150043/diff/1/Documentation/notation/changing-defaults.itely#newcode2558 Documentation/notation/changing-defaults.itely:2558: @code{TextSpanner.bound-details.left.padding}. @example would be useful here too. Especially if we can put it along side a 'property' that has a 'sub property' (if you see what I mean?). https://codereview.appspot.com/319150043/diff/1/Documentation/notation/changing-defaults.itely#newcode2561 Documentation/notation/changing-defaults.itely:2561: The property cannot default to @code{'(+inf.0 . -inf.0)}. What is the significance of this? Or should this be in the first bullet? E.g The property cannot be without a @q{default setting} nor can that @code{default setting} be @code{'(+inf.0 . -inf.0)}. See the grob's description in @file{scm/define-grobs.scm} and listed for each grob in @rinternals{All layout objects}. I'll stop here now. I know how tough it can be to do a big edit like this in the NR (and LM). But any help I can give you let me know. https://codereview.appspot.com/319150043/ _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
