Doc: new syntax for \tweak, \override (2936)

Doc: new syntax for \tweak, \override (2936)

  Also remove text saying spaces are required
  around the . in Lyric overrides

[Trevor Daniels, 2012-11-14 16:44:34]

@James
I'm afraid this patch-set will give you conflicts
in changing-defaults with your patch-set 6742057,
but as you "_expect_ to have lots of edits and go 
through a few iterations of this" I guess rebasing
it and resolving them (assuming this gets pushed 
soonish) will not cause you too much pain.  I think 
removing these inconsistencies quickly is important, 
but I do apologise for the extra work this will 
cause you.

Trevor

[benko.pal, 2012-11-14 21:53:23]

LGTM

http://codereview.appspot.com/6852052/diff/1/Documentation/notation/vocal.itely
File Documentation/notation/vocal.itely (left):

http://codereview.appspot.com/6852052/diff/1/Documentation/notation/vocal.ite...
Documentation/notation/vocal.itely:170: 
I'm sort of sorry to see this funny paragraph disappear :)
earnest: this (and some other examples) may well be worth mentioning in Changes.

[dak, 2012-11-14 23:16:17]

http://codereview.appspot.com/6852052/diff/1/Documentation/notation/vocal.itely
File Documentation/notation/vocal.itely (left):

http://codereview.appspot.com/6852052/diff/1/Documentation/notation/vocal.ite...
Documentation/notation/vocal.itely:170: 
On 2012/11/14 21:53:23, benko.pal wrote:
> I'm sort of sorry to see this funny paragraph disappear :)
> earnest: this (and some other examples) may well be worth mentioning in
Changes.

This is actually something that is not easy to explain.  It is more or less

"Similarly, in lyric mode, a period will be included in the alphabetic sequence
that it follows. As a consequence, it would appear spaces must be inserted
around the period in @code{\override} commands.  However it works without doing
so since LilyPond will accept a single string with dots inside here as well as
several ones separated by dot."

Ugh.  I think it is hard enough to explain _why_ this works here that we should
not even try.  The only people who would feel offended by it working without
good reason will likely analyze the code.

[Trevor Daniels, 2012-11-15 08:59:10]

On 2012/11/14 23:16:17, dak wrote:
> Ugh.  I think it is hard enough to explain _why_ this works here that we
should
> not even try.

Agreed.  We should not include how or why things work in
a Reference Manual for _using_ LilyPond.  It's sufficiently
long and complicated enough without ;)

[dak, 2012-11-16 13:13:26]

http://codereview.appspot.com/6852052/diff/1/Documentation/learning/tweaks.itely
File Documentation/learning/tweaks.itely (right):

http://codereview.appspot.com/6852052/diff/1/Documentation/learning/tweaks.it...
Documentation/learning/tweaks.itely:221: @var{value}.  This must always be
present in exactly this form.
"in exactly this form" is a bit of a stretch now when we are only talking about
# rather than also #'.  I'd also write
"This must always be present when writing values in Scheme." since there are
LilyPond syntax expressions that work fine without #.

http://codereview.appspot.com/6852052/diff/1/Documentation/notation/changing-...
File Documentation/notation/changing-defaults.itely (right):

http://codereview.appspot.com/6852052/diff/1/Documentation/notation/changing-...
Documentation/notation/changing-defaults.itely:1913: @c This section should be
moved to the Extending Manual -td
This section seems rather wrong (the internals of overrides and sets look
different).  Where did it come from?  I don't think it would be feasible to make
it both correct and useful, so I would rather delete it completely than
commenting it out.

http://codereview.appspot.com/6852052/diff/1/Documentation/notation/changing-...
Documentation/notation/changing-defaults.itely:1988: or to modify the two ends
of spanners, use the form
"two ends of spanners" -> "the left end of a text spanner" ?

http://codereview.appspot.com/6852052/diff/1/Documentation/notation/changing-...
Documentation/notation/changing-defaults.itely:2133: This is still valid but is
likely to become deprecated in some
No, it is not still valid: you can't optionally specify layout-object in this
manner any more.

http://codereview.appspot.com/6852052/diff/1/Documentation/notation/spacing.i...
File Documentation/notation/spacing.itely (right):

http://codereview.appspot.com/6852052/diff/1/Documentation/notation/spacing.i...
Documentation/notation/spacing.itely:1204: TextScript.padding = #1
This is not a new problem, but I don't understand why there is no \override
before the lines in this example.  Put into a layout block like that, it will
likely cause segfaults.  But I really don't understand what "would consist of"
in the above paragraph is supposed to mean.

http://codereview.appspot.com/6852052/diff/1/Documentation/notation/spacing.i...
Documentation/notation/spacing.itely:1218: NoteHead.font-size= #4 % (written in
the variable definition)
The equals sign is placed uglily.  And again, I have no idea what the example is
supposed to show.  Maybe one should check which commit these example come from
originally and see whether it can be made to actually documents what it was
intended to do.

[Trevor Daniels, 2012-11-19 09:13:27]

Thanks for the review David.  I'll post a modified patch shortly.

Trevor

http://codereview.appspot.com/6852052/diff/1/Documentation/learning/tweaks.itely
File Documentation/learning/tweaks.itely (right):

http://codereview.appspot.com/6852052/diff/1/Documentation/learning/tweaks.it...
Documentation/learning/tweaks.itely:221: @var{value}.  This must always be
present in exactly this form.
On 2012/11/16 13:13:26, dak wrote:
> "in exactly this form" is a bit of a stretch now when we are only talking
about
> # rather than also #'.  I'd also write
> "This must always be present when writing values in Scheme." since there are
> LilyPond syntax expressions that work fine without #.

I take your point but I don't want to mention Scheme 
at this stage in the LM.  Every example in the LM
includes a leading #, so I'll just mention that there
are situations where it may be omitted.

http://codereview.appspot.com/6852052/diff/1/Documentation/notation/changing-...
File Documentation/notation/changing-defaults.itely (right):

http://codereview.appspot.com/6852052/diff/1/Documentation/notation/changing-...
Documentation/notation/changing-defaults.itely:1913: @c This section should be
moved to the Extending Manual -td
On 2012/11/16 13:13:26, dak wrote:
> This section seems rather wrong (the internals of overrides and sets look
> different).  Where did it come from?  I don't think it would be feasible to
make
> it both correct and useful, so I would rather delete it completely than
> commenting it out.
It dates from 2006, so things may have changed.  Deleted.

http://codereview.appspot.com/6852052/diff/1/Documentation/notation/changing-...
Documentation/notation/changing-defaults.itely:1988: or to modify the two ends
of spanners, use the form
On 2012/11/16 13:13:26, dak wrote:
> "two ends of spanners" -> "the left end of a text spanner" ?
Changed example to show both ends being modified.

http://codereview.appspot.com/6852052/diff/1/Documentation/notation/changing-...
Documentation/notation/changing-defaults.itely:2133: This is still valid but is
likely to become deprecated in some
On 2012/11/16 13:13:26, dak wrote:
> No, it is not still valid: you can't optionally specify layout-object in this
> manner any more.
Done

http://codereview.appspot.com/6852052/diff/1/Documentation/notation/spacing.i...
File Documentation/notation/spacing.itely (right):

http://codereview.appspot.com/6852052/diff/1/Documentation/notation/spacing.i...
Documentation/notation/spacing.itely:1204: TextScript.padding = #1
On 2012/11/16 13:13:26, dak wrote:
> This is not a new problem, but I don't understand why there is no \override
> before the lines in this example.  Put into a layout block like that, it will
> likely cause segfaults.  But I really don't understand what "would consist of"
> in the above paragraph is supposed to mean.

This came from the fix to 2560.  If this is still
unclear a separate issue should be raised to fix it.

http://codereview.appspot.com/6852052/diff/1/Documentation/notation/spacing.i...
Documentation/notation/spacing.itely:1218: NoteHead.font-size= #4 % (written in
the variable definition)
On 2012/11/16 13:13:26, dak wrote:
> The equals sign is placed uglily.  And again, I have no idea what the example
is
> supposed to show.  Maybe one should check which commit these example come from
> originally and see whether it can be made to actually documents what it was
> intended to do.

See comment above.

[Trevor Daniels, 2012-11-19 10:36:13]

http://codereview.appspot.com/6852052/diff/1006/Documentation/notation/input....
File Documentation/notation/input.itely (right):

http://codereview.appspot.com/6852052/diff/1006/Documentation/notation/input....
Documentation/notation/input.itely:2645: @cindex MIDI, instrument
This is an artefact due to rebasing.  It appears only
in the comparison with Patch set 1, not in the patch
itself.   

Maybe one shouldn't rebase between patch sets?

[Keith, 2012-11-19 20:58:09]

lgtm

http://codereview.appspot.com/6852052/diff/1/Documentation/learning/tweaks.itely
File Documentation/learning/tweaks.itely (right):

http://codereview.appspot.com/6852052/diff/1/Documentation/learning/tweaks.it...
Documentation/learning/tweaks.itely:221: @var{value}.  This must always be
present in exactly this form.
On 2012/11/19 09:13:27, Trevor Daniels wrote:
> I take your point but I don't want to mention Scheme 
> at this stage in the LM.  

The original "don't worry about the #" made me cringe. ("Why are you telling me
about it if I'm not supposed to worry about it? You patronizing ...")

Early on, I had to realize that # indicated some mysterious shift in the
interpretation of my input.  While #4. is number, 4. is a dotted-quarter
duration.  For a while I thought # meant 'number' so that #red was the number of
the color in some palette, as opposed to the usual note name, ré dièse.

It would be helpful to have some idea of what # means.  New users do need to
worry about it in that we have to follow with a single word or something in
balanced () parentheses.  I do not think anyone will be afraid of "LilyPond uses
'#' to indicate an expression in a programming language called Scheme.  We often
use # in overrides to indicate values like the number #-2 and the predefined
color #red as distinct from musical notation."

http://codereview.appspot.com/6852052/diff/1006/Documentation/notation/input....
File Documentation/notation/input.itely (right):

http://codereview.appspot.com/6852052/diff/1006/Documentation/notation/input....
Documentation/notation/input.itely:2645: @cindex MIDI, instrument
On 2012/11/19 10:36:14, Trevor Daniels wrote:
> This is an artefact due to rebasing.  It appears only
> in the comparison with Patch set 1, not in the patch
> itself.   
> 
> Maybe one shouldn't rebase between patch sets?

It is surprising to see changes from other commits when we compare two versions
of a pending patch-set, but we do want to be /able/ to see them, just in case
they conflict.

[Trevor Daniels, 2012-11-19 22:55:57]

http://codereview.appspot.com/6852052/diff/1006/Documentation/learning/tweaks...
File Documentation/learning/tweaks.itely (right):

http://codereview.appspot.com/6852052/diff/1006/Documentation/learning/tweaks...
Documentation/learning/tweaks.itely:223: include it.
Keith suggested alternative wording for the first
sentence in this paragraph:
"LilyPond uses@tie{}@code{#} to indicate an
expression in a programming language called
Scheme.  We often use@tie{}@code{#} in overrides
to indicate values like the number @code{#-2}
and the predefined color @code{#red} as distinct
from musical notation."
I quite like this.  Thanks Keith!

[dak, 2012-11-20 19:08:46]

http://codereview.appspot.com/6852052/diff/7/Documentation/learning/tweaks.itely
File Documentation/learning/tweaks.itely (right):

http://codereview.appspot.com/6852052/diff/7/Documentation/learning/tweaks.it...
Documentation/learning/tweaks.itely:226: include it.  For more details, see
@rextend{LilyPond Scheme syntax}.
This may be a bit of bikeshedding here, but I'd suggest reversing the narrative
of the first paragraphs, like

LilyPond's basic expressions are musical items like notes, durations, and
markups.  Several simple values like the number @samp{-2} or the predefined
color code @samp{red} don't fit in this syntax, so we deal with them by
specifying them in LilyPond's embedded programming language Scheme.

Escaping to Scheme for a single expression can simply be done by prefixing the
expression with @samp{#}.  Tweaked values usually are non-musical expressions;
the examples in the manual will favor using @samp{#} even when LilyPond might be
able to interpret some input correctly in its musical mode without
using@tie{}@samp{#}.  For more details...

[Trevor Daniels, 2012-11-20 21:39:54]

On 2012/11/20 19:08:46, dak wrote:
> This may be a bit of bikeshedding here, 

Yes.

> but I'd suggest reversing the narrative
> of the first paragraphs, like

I still think this amount of detail is not quite in
keeping with the tenor of the Learning Manual.  At
this stage of learning there is a danger new users
will get discouraged at this point.  However, your
text is indisputably more accurate, and for those who
just might understand it, more informative.

As I'd like to just get this pushed now I'll add
your suggested text and post a new patch set. 

Trevor

[dak, 2012-11-20 23:57:36]

On 2012/11/20 21:39:54, Trevor Daniels wrote:
> On 2012/11/20 19:08:46, dak wrote:
> 
> > but I'd suggest reversing the narrative
> > of the first paragraphs, like
> 
> I still think this amount of detail is not quite in
> keeping with the tenor of the Learning Manual.

I am bad at keeping with the tenor of the Learning Manual (my
experience in choirs has been that the tenor section in particular was
prone to dragging).

> At
> this stage of learning there is a danger new users
> will get discouraged at this point.  However, your
> text is indisputably more accurate, and for those who
> just might understand it, more informative.

Being accurate is something I am more skilled at than being useful,
and it is not easy to argue against that.

> As I'd like to just get this pushed now I'll add
> your suggested text and post a new patch set. 

If you feel you can boil this down into something that is better
suited for putting the reader on the right track without exhausting
him, feel free to improve this, if necessary skimming over information
that is likely to cause more harm than good at this stage.  I am bad
at prioritising information.

[dak, 2012-11-21 00:33:23]

On 2012/11/20 23:57:36, dak wrote:

> If you feel you can boil this down into something that is better
> suited for putting the reader on the right track without exhausting
> him, feel free to improve this, if necessary skimming over information
> that is likely to cause more harm than good at this stage.  I am bad
> at prioritising information.

Let me try again:

LilyPond's primary expressions are musical items like notes,
durations, and markups.  More basic expressions like numbers,
strings, and lists can be entered and processed in @q{Scheme mode}
which is entered with @samp{#}.  Tweaked values are usually
non-musical and only sometimes have a valid representation in
LilyPond's musical mode.  The manual will favor using @samp{#} for
their entry for the sake of consistency.  For more information about
Scheme mode, see @rextend{LilyPond Scheme syntax}.

[Trevor Daniels, 2012-11-21 08:59:39]

On 2012/11/21 00:33:23, dak wrote:

> LilyPond's primary expressions are musical items like notes,
...

Thanks David.  Much better, although I have simplified it
further in my next upload.  I'm happy with this now.

Trevor

[Graham Percival, 2012-11-23 22:05:47]

https://codereview.appspot.com/6852052/diff/14001/Documentation/notation/chan...
File Documentation/notation/changing-defaults.itely (right):

https://codereview.appspot.com/6852052/diff/14001/Documentation/notation/chan...
Documentation/notation/changing-defaults.itely:1918: (The syntax used prior to
Release 2.17.6 was
I don't think we should be talking about deprecated syntax; otherwise we could
end up with tons of side comments.  The documentation is large enough as it is. 
We should keep "used prior" material in Changes.

[Trevor Daniels, 2012-11-23 23:51:13]

https://codereview.appspot.com/6852052/diff/14001/Documentation/notation/chan...
File Documentation/notation/changing-defaults.itely (right):

https://codereview.appspot.com/6852052/diff/14001/Documentation/notation/chan...
Documentation/notation/changing-defaults.itely:1918: (The syntax used prior to
Release 2.17.6 was
On 2012/11/23 22:05:47, Graham Percival wrote:
> I don't think we should be talking about deprecated syntax; otherwise we could
> end up with tons of side comments.  The documentation is large enough as it
is. 
> We should keep "used prior" material in Changes.

I agree in general, but the point is both forms of the
syntax are still valid and so should be documented.
Furthermore it's only /likely/ to become deprecated;
it hasn't yet been deprecated.  When it does this 
paragraph can go.  It also contrasts with \tweak -
its syntax /has/ changed.

I've minimised the effect on the documentation by using
the new form alone everywhere (or at least David did) 
and restricting the description of the old form to 
just this one paragraph and one example.  I don't see 
any other situations where this has arisen, so it's
unlikely to get out of control.  I think we should 
leave this as it is.

[dak, 2012-11-24 06:22:43]

On 2012/11/23 23:51:13, Trevor Daniels wrote:
>
https://codereview.appspot.com/6852052/diff/14001/Documentation/notation/chan...
> File Documentation/notation/changing-defaults.itely (right):
> 
>
https://codereview.appspot.com/6852052/diff/14001/Documentation/notation/chan...
> Documentation/notation/changing-defaults.itely:1918: (The syntax used prior to
> Release 2.17.6 was
> On 2012/11/23 22:05:47, Graham Percival wrote:
> > I don't think we should be talking about deprecated syntax; otherwise we
could
> > end up with tons of side comments.  The documentation is large enough as it
> is. 
> > We should keep "used prior" material in Changes.
> 
> I agree in general, but the point is both forms of the
> syntax are still valid and so should be documented.

I'm with Graham on this.  The extension manual may talk about the equivalence of
symbol lists in Scheme and LilyPond, but the whole point of the exercise was to
remove a complication.

> Furthermore it's only /likely/ to become deprecated;
> it hasn't yet been deprecated.  When it does this 
> paragraph can go.  It also contrasts with \tweak -
> its syntax /has/ changed.

But the difference is not by design but by necessity (\tweak is not implemented
in the parser), and it is only a rather new form of \tweak that has changed
incompatibly.

[Trevor Daniels, 2012-11-25 11:47:59]

On 2012/11/24 06:22:43, dak wrote:
> On 2012/11/23 23:51:13, Trevor Daniels wrote:
> >
>
https://codereview.appspot.com/6852052/diff/14001/Documentation/notation/chan...
> > File Documentation/notation/changing-defaults.itely (right):
> > 
> >
>
https://codereview.appspot.com/6852052/diff/14001/Documentation/notation/chan...
> > Documentation/notation/changing-defaults.itely:1918: (The syntax used prior
to
> > Release 2.17.6 was
> > On 2012/11/23 22:05:47, Graham Percival wrote:
> > > I don't think we should be talking about deprecated syntax; otherwise we
> could
> > > end up with tons of side comments.  The documentation is large enough as
it
> > is. 
> > > We should keep "used prior" material in Changes.
> > 
> > I agree in general, but the point is both forms of the
> > syntax are still valid and so should be documented.
> 
> I'm with Graham on this.  The extension manual may talk about the equivalence
of
> symbol lists in Scheme and LilyPond, but the whole point of the exercise was
to
> remove a complication.

OK, I don't feel too strongly about this, and I'm
out-voted.  Revised patch-set on its way.

Trevor

[Graham Percival, 2012-11-26 05:56:26]

LGTM, can go on countdown or whatever.

[Trevor Daniels, 2012-11-27 09:34:07]

Pushed to staging as
232de3305dd5262822fd1e081ddd52581319f4ce
Closing