[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: david . nalesnik
Subject: Re: Issue 3830: Document \offset command (issue 319150043 by address@hidden)
Date: Tue, 24 Jan 2017 08:09:01 -0800

Thanks so such for the detailed review!  Will post a patch update in the
near future.
File Documentation/notation/changing-defaults.itely (right):
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
talk about both context and grob properties as being distinct from one
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..."
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
location from it's expected location.

Though see here

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

Yes -- \override or \tweak
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
have a default would help educate a user when they look up the two
objects in our examples for themselves to see that one does and and
one does

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...
On 2017/01/24 14:36:08, pkx166h wrote:
Again I think this a bit 'talking through the code' (what's a

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.

@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

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


The property cannot be without a  @q{default setting} nor can that
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

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

But any help I can give you let me know.

I appreciate this!

reply via email to

[Prev in Thread] Current Thread [Next in Thread]