Issue 3830: Document \offset command

Issue 3830:  Document \offset command

[david.nalesnik, 2017-01-23 00:04:26]

Please review.  Thanks!

[simon.albrecht, 2017-01-23 08:26:06]

LGTM.

[thomasmorley651, 2017-01-23 23:52:54]

Two thoughts, otherwise

LGTM

https://codereview.appspot.com/319150043/diff/1/Documentation/notation/changi...
File Documentation/notation/changing-defaults.itely (right):

https://codereview.appspot.com/319150043/diff/1/Documentation/notation/changi...
Documentation/notation/changing-defaults.itely:2522: [-]\offset @var{property}
@var{offsets} @var{item}
Would it be even more clear to have instead of @var{offsets} something like
@var{offset-value} or @var{property-value}?
(Same below and in the docstring for the offset-command in
music-functions-init.ly)

Please keep in mind I'm not a native speaker, so I may be wrong here.

https://codereview.appspot.com/319150043/diff/1/Documentation/notation/changi...
Documentation/notation/changing-defaults.itely:2539: @code{\once} or
@code{\temporary} and reverted by using @code{\revert}
Does \undo work?
If so, please mention it as well.

[david.nalesnik, 2017-01-24 13:34:27]

https://codereview.appspot.com/319150043/diff/1/Documentation/notation/changi...
File Documentation/notation/changing-defaults.itely (right):

https://codereview.appspot.com/319150043/diff/1/Documentation/notation/changi...
Documentation/notation/changing-defaults.itely:2522: [-]\offset @var{property}
@var{offsets} @var{item}
On 2017/01/23 23:52:54, thomasmorley651 wrote:
> Would it be even more clear to have instead of @var{offsets} something like
> @var{offset-value} or @var{property-value}?
> (Same below and in the docstring for the offset-command in
> music-functions-init.ly)
> 
> Please keep in mind I'm not a native speaker, so I may be wrong here.

"offsets" works, but I could change this to "displacements" -- you know, sort of
like not using a word in its own definition.  There would also be no confusion
between noun and verb senses, since "displacements" is only a noun.

But maybe, since the docs are supposed to be clear to native and non-native
speakers, "offset-values" or "offset-amounts" would be best?

[pkx166h, 2017-01-24 14:36:09]

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/changi...
File Documentation/notation/changing-defaults.itely (right):

https://codereview.appspot.com/319150043/diff/1/Documentation/notation/changi...
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/changi...
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/changi...
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/changi...
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/changi...
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/changi...
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/changi...
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/changi...
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.

[david.nalesnik, 2017-01-24 16:09:02]

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/changi...
File Documentation/notation/changing-defaults.itely (right):

https://codereview.appspot.com/319150043/diff/1/Documentation/notation/changi...
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/changi...
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/changi...
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/changi...
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/changi...
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/changi...
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/changi...
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/changi...
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/changi...
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!

[david.nalesnik, 2017-01-24 22:30:41]

Be more expansive

[david.nalesnik, 2017-01-24 22:38:21]

I've posted an extensive rewrite which hopefully addresses all the concerns.  I
think the result is a lot more user-friendly.

Note that I did not change the argument-name "offsets".

My preference would be to use "displacements" here, because I think it is
exactly expressive of its use.  The documentation of \shape in the NR uses
displacements.

In second place would be "offsets."  (Interestingly, the listing of "shape" in
Available Music Functions uses "offsets," in contrast with the NR documentation.
 I suppose I'm responsible for the function docstring.  IIRC, Trevor wrote the
\shape documentation.)

I've left it as-is for the moment, to invite other opinions.

[david.nalesnik, 2017-01-24 22:57:55]

Question:

How do I get a backslash in @subsubsubheading{} ?

The literal symbol doesn't show up, and @backslashchar{} displays
@backslashchar{}

[t.daniels_treda.co.uk, 2017-01-24 23:32:51]

david.nalesnik@gmail.com wrote Tuesday, January 24, 2017 10:57 PM

> Question:
> 
> How do I get a backslash in @subsubsubheading{} ?
> 
> The literal symbol doesn't show up, and @backslashchar{} displays
> @backslashchar{}

From memory it's @bs{}.

Trevor

[david.nalesnik, 2017-01-24 23:48:57]

On 2017/01/24 23:32:51, t.daniels_treda.co.uk wrote:
> mailto:david.nalesnik@gmail.com wrote Tuesday, January 24, 2017 10:57 PM
> 
> > Question:
> > 
> > How do I get a backslash in @subsubsubheading{} ?
> > 
> > The literal symbol doesn't show up, and @backslashchar{} displays
> > @backslashchar{}
> 
> From memory it's @bs{}.
> 
> Trevor

Thaat's it!

Thanks, Trevor.

David

[david.nalesnik, 2017-01-25 02:28:39]

Improve wording, add slashes

[david.nalesnik, 2017-01-25 16:16:14]

Clarify criteria/examples

[david.nalesnik, 2017-01-25 20:43:23]

diagram syntax, other improvements

[david.nalesnik, 2017-01-25 20:47:23]

On 2017/01/25 20:43:23, david.nalesnik wrote:
> diagram syntax, other improvements

This is as clear as I can make this I think, so I will resist the temptation to
post a follow-up patch in case reviewers would like to comment!

[simon.albrecht, 2017-01-25 22:33:33]

One typo did I spot :-)

https://codereview.appspot.com/319150043/diff/80001/Documentation/notation/ch...
File Documentation/notation/changing-defaults.itely (right):

https://codereview.appspot.com/319150043/diff/80001/Documentation/notation/ch...
Documentation/notation/changing-defaults.itely:2777: The @code{\offset} command
used in this manner is similiar to the
s/similiar/similar

[david.nalesnik, 2017-01-26 14:33:18]

https://codereview.appspot.com/319150043/diff/80001/Documentation/notation/ch...
File Documentation/notation/changing-defaults.itely (right):

https://codereview.appspot.com/319150043/diff/80001/Documentation/notation/ch...
Documentation/notation/changing-defaults.itely:2777: The @code{\offset} command
used in this manner is similiar to the
On 2017/01/25 22:33:32, simon.albrecht wrote:
> s/similiar/similar

Yup--thanks.  Will bundle that with whatever changes may come.