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

[david . nalesnik]

Thanks so such for the detailed review!  Will post a patch update in the
near future.


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},
On 2017/01/24 14:36:08, pkx166h wrote:
> 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.'


Will clarify that it's _grob_ properties only.  I like the "while..."
construction.

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}
On 2017/01/24 14:36:08, pkx166h wrote:
> '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.

Though see here
(https://www.merriam-webster.com/dictionary/displacement):

"the difference between the initial position of something (as a body or
geometric figure) and any later position"


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

I'm happy to use "offset-value" though!

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
On 2017/01/24 14:36:08, pkx166h wrote:
> '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.

Yes, I give a number of examples with the "tweak" form.  The "tweak"
form doesn't explicitly use "\tweak".  As I explained above, the effect
of the \offset command is to create a tweak when the last argument is a
musical expression.

The presence/absence of the leading hyphen is exactly analogous to the
actual \tweak command.  So I can't consider it a known limitation unless
it is a known limitation of \tweak.

I'll add a comment which stresses that the syntax of \offset in its
"tweak" form is modeled after \tweak itself.

https://codereview.appspot.com/319150043/diff/1/Documentation/notation/changing-defaults.itely#newcode2539
Documentation/notation/changing-defaults.itely:2539: @code{\once} or
@code{\temporary} and reverted by using @code{\revert}
On 2017/01/23 23:52:54, thomasmorley651 wrote:
> Does \undo work?
> If so, please mention it as well.

Will check that out.  Thanks!

https://codereview.appspot.com/319150043/diff/1/Documentation/notation/changing-defaults.itely#newcode2544
Documentation/notation/changing-defaults.itely:2544:
On 2017/01/24 14:36:09, pkx166h wrote:
> 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.

Yeah, sorry.  I'll try to clarify. But at the end of the day, this is
always going to be somewhat technical -- which is why it doesn't belong
in the LM :)


> 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}.
On 2017/01/24 14:36:08, pkx166h wrote:
> 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'?

Yes -- \override or \tweak
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.

OK, I was trying to keep this pithy and (somewhat) formal in keeping
with Reference Manual policy, but as nothing is going into the LM, I
could be a little more expansive...

https://codereview.appspot.com/319150043/diff/1/Documentation/notation/changing-defaults.itely#newcode2555
Documentation/notation/changing-defaults.itely:2555:
On 2017/01/24 14:36:08, pkx166h wrote:
> Again I think this a bit 'talking through the code' (what's a
callback?)

All I can do here is add something like "for example, Arpeggio.positions
is set to ly:arpeggio::calc-positions -- a callback -- which when
evaluated during typesetting yields a @code{number-pair}"  If there's an
explanation of callback somewhere, I could link to it.

 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.

We will throw warnings.  I suppose I could direct Lily to ignore the
warnings.  I think, though, that there should at most be only one
example that shows nothing happening.  I can mention examples that won't
work, but I don't think we should clutter the visual space with actual
music showing no side-by-side changes.

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}.
On 2017/01/24 14:36:08, pkx166h wrote:
> @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?).

I'm thinking a text example would be enough.  The TextSpanner bit is
meant to be such an example, but I suppose I could be more clear that
padding is a property of another property (actually, a property of a
property of a property here) and hence won't work.  (Though the command
could be enhanced at some point.)

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)}.
On 2017/01/24 14:36:08, pkx166h wrote:
> 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}.

That's a good idea.  (The rationale behind excluding the '(+inf.0 .
-inf.0), BTW, is that it doesn't make sense to add to infinity.)

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

I appreciate this!

https://codereview.appspot.com/319150043/