Re: Issue 3830: Document \offset command (issue 319150043 by david.nales...@gmail.com)
https://codereview.appspot.com/319150043/diff/80001/Documentation/notation/changing-defaults.itely
File Documentation/notation/changing-defaults.itely (right):
https://codereview.appspot.com/319150043/diff/80001/Documentation/notation/changing-defaults.itely#newcode2777
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.
https://codereview.appspot.com/319150043/
___
lilypond-devel mailing list
lilypond-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Issue 3830: Document \offset command (issue 319150043 by david.nales...@gmail.com)
One typo did I spot :-)
https://codereview.appspot.com/319150043/diff/80001/Documentation/notation/changing-defaults.itely
File Documentation/notation/changing-defaults.itely (right):
https://codereview.appspot.com/319150043/diff/80001/Documentation/notation/changing-defaults.itely#newcode2777
Documentation/notation/changing-defaults.itely:2777: The @code{\offset}
command used in this manner is similiar to the
s/similiar/similar
https://codereview.appspot.com/319150043/
___
lilypond-devel mailing list
lilypond-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Issue 3830: Document \offset command (issue 319150043 by david.nales...@gmail.com)
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! https://codereview.appspot.com/319150043/ ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Issue 3830: Document \offset command (issue 319150043 by david.nales...@gmail.com)
On 2017/01/24 23:32:51, t.daniels_treda.co.uk wrote:
mailto:david.nales...@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
https://codereview.appspot.com/319150043/
___
lilypond-devel mailing list
lilypond-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Issue 3830: Document \offset command (issue 319150043 by david.nales...@gmail.com)
Question:
How do I get a backslash in @subsubsubheading{} ?
The literal symbol doesn't show up, and @backslashchar{} displays
@backslashchar{}
https://codereview.appspot.com/319150043/
___
lilypond-devel mailing list
lilypond-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Issue 3830: Document \offset command (issue 319150043 by david.nales...@gmail.com)
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. https://codereview.appspot.com/319150043/ ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Issue 3830: Document \offset command (issue 319150043 by david.nales...@gmail.com)
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.
Re: Issue 3830: Document \offset command (issue 319150043 by david.nales...@gmail.com)
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
Re: Issue 3830: Document \offset command (issue 319150043 by david.nales...@gmail.com)
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#newcode2522
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?
https://codereview.appspot.com/319150043/
___
lilypond-devel mailing list
lilypond-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Issue 3830: Document \offset command (issue 319150043 by david.nales...@gmail.com)
Two thoughts, otherwise
LGTM
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#newcode2522
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/changing-defaults.itely#newcode2539
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.
https://codereview.appspot.com/319150043/
___
lilypond-devel mailing list
lilypond-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Issue 3830: Document \offset command (issue 319150043 by david.nales...@gmail.com)
LGTM. https://codereview.appspot.com/319150043/ ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Issue 3830: Document \offset command (issue 319150043 by david.nales...@gmail.com)
Reviewers: , Message: Please review. Thanks! Description: Issue 3830: Document \offset command Please review this at https://codereview.appspot.com/319150043/ Affected files (+142, -0 lines): M Documentation/notation/changing-defaults.itely ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
