Doc: LM - correct @example for Tweak Command

Doc: LM - correct @example for Tweak Command

Issue 4101

Corrected existing 'long form' example for Syntax Consistency

[dak, 2014-09-15 07:26:45]

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

https://codereview.appspot.com/140630043/diff/1/Documentation/learning/tweaks...
Documentation/learning/tweaks.itely:453: \tweak
@var{layoutObject}.@var{layout-property} #@var{value}
The Google issue pointed out that this should be "LayoutObject" to reflect the
proper case.  It is somewhat disconcerting that the Info page rendition (rather
than the HTML pages) will read LAYOUTOBJECT and LAYOUT-PROPERTY anyway, as
that's the way @var placeholders are formatted.  Still, I think that's probably
the best we can do.

You put in #@var{value} instead of @var{value}.  I think we are not overly
consistent regarding that, but it is worth mentioning that something like (see
Learning Manual in Tweaks)

\override TextSpanner.bound-details.left.text
    = \markup { \small \bold Slower }

(can also be used as a tweak) gets along perfectly fine without a # sign, so the
# is really an integral part of @var{value} and not part of the \tweak syntax.

[pkx166h, 2014-09-15 13:56:55]

On 2014/09/15 07:26:45, dak wrote:
>
https://codereview.appspot.com/140630043/diff/1/Documentation/learning/tweaks...
> File Documentation/learning/tweaks.itely (right):
> 
>
https://codereview.appspot.com/140630043/diff/1/Documentation/learning/tweaks...
> Documentation/learning/tweaks.itely:453: \tweak
> @var{layoutObject}.@var{layout-property} #@var{value}
> The Google issue pointed out that this should be "LayoutObject" to reflect the
> proper case.

Yes it did. I was careless. Good job for patch review eh? :)

> It is somewhat disconcerting that the Info page rendition (rather
> than the HTML pages) will read LAYOUTOBJECT and LAYOUT-PROPERTY anyway, as
> that's the way @var placeholders are formatted.  Still, I think that's
probably
> the best we can do.

Would using @code{} be better - I've never dug that deep to know the difference
in terms of that it looks the same in PDF output?

> 
> You put in #@var{value} instead of @var{value}.  I think we are not overly
> consistent regarding that, but it is worth mentioning that something like (see
> Learning Manual in Tweaks)

? This *is* Learning Manual in tweaks. If you look at the example above it is in
the TexInfo format of

--snip--
...So the simple form
of the @code{\tweak} command is

@example
\tweak @var{layout-property} #@var{value}
@end example

--snip--

So I just copied that. 

Would something like @var{#value} be better? As far as the output goes it would
just put the '#' sign in the @var monospaced font.

> 
> \override TextSpanner.bound-details.left.text
>     = \markup { \small \bold Slower }
> 
> (can also be used as a tweak) gets along perfectly fine without a # sign, so
the
> # is really an integral part of @var{value} and not part of the \tweak syntax.

Yes I see (just about) but isn't that the same as using

'\tweak layout-object.layout-property value'

as also indicated in thee tracker by the submitter?

Thanks

[dak, 2014-09-15 15:04:40]

On 2014/09/15 13:56:55, J_lowe wrote:
> On 2014/09/15 07:26:45, dak wrote:
> >
>
https://codereview.appspot.com/140630043/diff/1/Documentation/learning/tweaks...
> > File Documentation/learning/tweaks.itely (right):
> > 
> >
>
https://codereview.appspot.com/140630043/diff/1/Documentation/learning/tweaks...
> > Documentation/learning/tweaks.itely:453: \tweak
> > @var{layoutObject}.@var{layout-property} #@var{value}
> 
> > It is somewhat disconcerting that the Info page rendition (rather
> > than the HTML pages) will read LAYOUTOBJECT and LAYOUT-PROPERTY anyway, as
> > that's the way @var placeholders are formatted.  Still, I think that's
probably
> > the best we can do.
> 
> Would using @code{} be better - I've never dug that deep to know the
difference
> in terms of that it looks the same in PDF output?

No, @code would insinuate that this is to be used verbatim.  I think
that HTML and PDF will be pretty ok here.  It's just the info backend
that no longer reflects the Camel-and-whatever-casing.  But that does
not make the rendering wrong, just less suggestive regarding what the
result will likely look like.

> > You put in #@var{value} instead of @var{value}.  I think we are not overly
> > consistent regarding that, but it is worth mentioning that something like
(see
> > Learning Manual in Tweaks)
> 
> ? This *is* Learning Manual in tweaks.

Yes, but different place.

> If you look at the example above it is in
> the TexInfo format of
> 
> --snip--
> ...So the simple form
> of the @code{\tweak} command is
> 
> @example
> \tweak @var{layout-property} #@var{value}
> @end example
> 
> --snip--
> 
> So I just copied that.

Looking through the occurences of @var{value}, the current version has
#@var{value} twice and @var{value} once.  In my book, this should be
@var{value} everywhere but possibly accompanied by some real examples
that would then usually show a # as part of value.

I have to admit that putting #@var{value} would make this correspond
to the other instances.  It's just that I don't see that as correct.

If I do a grep for @var{value} on the Documentation and remove the
translations, I arrive at

Documentation/learning/tweaks.itely:\override
@var{Context}.@var{LayoutObject}.@var{layout-property} = #@var{value}
Documentation/learning/tweaks.itely:the @var{Context} context, to the value
@var{value}.
Documentation/learning/tweaks.itely:\tweak @var{layout-property} #@var{value}
Documentation/learning/tweaks.itely:\tweak
@var{layout-object}.@var{layout-property} @var{value}
Documentation/notation/changing-defaults.itely:\override
@var{context}.@var{name} #'@var{property} = #@var{value}
Documentation/notation/changing-defaults.itely:for @var{name}, @var{property},
and @var{value}.  Here we only
Documentation/notation/changing-defaults.itely:\override
@var{context}.@var{name} #'@var{property} #'@var{subproperty} = #@var{value}
Documentation/notation/changing-defaults.itely:\set @var{context}.@var{property}
= #@var{value}
Documentation/notation/changing-defaults.itely:@var{value} is a Scheme object,
which is why it must be preceded by
Documentation/notation/changing-defaults.itely:\override
[@var{context}.]@var{GrobName}.@var{property} = #@var{value}
Documentation/notation/changing-defaults.itely:\tweak
[@var{layout-object}.]@var{grob-property} @var{value}
Documentation/notation/changing-defaults.itely:follows @var{value} in the music
stream.
Documentation/usage/running.itely:This sets the equivalent internal Scheme
function to @var{value}.
Documentation/usage/running.itely:If a @var{value} is not supplied, then the
default value is used.  The

which, uh, points to @var{value} being quite in the minority, and the
text "@var{value} is a Scheme object, which is why it must be preceded
by" further muddifies the distinction between # being part of the
override/tweak syntax and part of the value.

Also Documentation/notation/changing-defaults.itely contains quite a
few old-syntax overrides.

I have to admit that putting @var{value} here alone will not help
consistency: this would need a more sweeping revision that replaces
"must be preceded by #" with "will usually be a Scheme value
introduced with # unless it is a LilyPond-native construct like a
markup".

Sigh.

> Would something like @var{#value} be better? As far as the output goes it
would
> just put the '#' sign in the @var monospaced font.

I think @var is not necessarily monospaced.  In some renditions it
might be slanted.

> > \override TextSpanner.bound-details.left.text
> >     = \markup { \small \bold Slower }
> > 
> > (can also be used as a tweak) gets along perfectly fine without a # sign, so
> the
> > # is really an integral part of @var{value} and not part of the \tweak
syntax.
> 
> Yes I see (just about) but isn't that the same as using
> 
> '\tweak layout-object.layout-property value'
> 
> as also indicated in thee tracker by the submitter?

You lost me here.

[pkx166h, 2014-09-16 07:15:45]

Typo

[pkx166h, 2014-09-16 07:24:33]

Created new issue for the general #@var{variable} vs @var{variable} discussion.

http://code.google.com/p/lilypond/issues/detail?id=4105

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

https://codereview.appspot.com/140630043/diff/1/Documentation/learning/tweaks...
Documentation/learning/tweaks.itely:453: \tweak
@var{layoutObject}.@var{layout-property} #@var{value}
On 2014/09/15 07:26:45, dak wrote:
> The Google issue pointed out that this should be "LayoutObject" to reflect the
> proper case.  

Done.

> It is somewhat disconcerting that the Info page rendition (rather
> than the HTML pages) will read LAYOUTOBJECT and LAYOUT-PROPERTY anyway, as
> that's the way @var placeholders are formatted.  Still, I think that's
probably
> the best we can do.
> 
> You put in #@var{value} instead of @var{value}.  I think we are not overly
> consistent regarding that, but it is worth mentioning that something like (see
> Learning Manual in Tweaks)
> 
> \override TextSpanner.bound-details.left.text
>     = \markup { \small \bold Slower }
> 
> (can also be used as a tweak) gets along perfectly fine without a # sign, so
the
> # is really an integral part of @var{value} and not part of the \tweak syntax.

As per Trevor's suggestion I'll make a new tracker for dealing with the
inconsistencies in the doc.

[pkx166h, 2014-09-20 03:37:28]

author	James Lowe <pkx166h@gmail.com>	
	Mon, 15 Sep 2014 05:46:21 +0000 (06:46 +0100)
committer	James Lowe <pkx166h@gmail.com>	
	Sat, 20 Sep 2014 03:34:39 +0000 (04:34 +0100)
commit	dabc2448e7d1b14008bd5cdb013b23d7ef98bdd9