Re: Issue 3830: Document \offset command (issue 319150043 by address@hidden)

[pkx166h]

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/