[Lilypond-auto] Issue 4105 in lilypond: Doc: Inconsistency when defining LilyPond commands that use variables - using '#' or not

[lilypond]

Status: Accepted
Owner: ----
Labels: Type-Documentation

New issue 4105 by address@hidden: Doc: Inconsistency when defining  
LilyPond commands that use variables - using '#' or not
https://code.google.com/p/lilypond/issues/detail?id=4105

From David K (conversation with James L)

Looking through the occurences of @var{value}, the current version has
address@hidden 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 address@hidden 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
@address@hidden@var{layout-property} = address@hidden
Documentation/learning/tweaks.itely:the @var{Context} context, to the
value @var{value}.
Documentation/learning/tweaks.itely:\tweak @var{layout-property}
address@hidden
Documentation/learning/tweaks.itely:\tweak
@address@hidden @var{value}
Documentation/notation/changing-defaults.itely:\override
@address@hidden #'@var{property} = address@hidden
Documentation/notation/changing-defaults.itely:for @var{name},
@var{property}, and @var{value}.  Here we only
Documentation/notation/changing-defaults.itely:\override
@address@hidden #'@var{property} #'@var{subproperty} =
address@hidden
Documentation/notation/changing-defaults.itely:\set
@address@hidden = address@hidden
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
address@hidden@address@hidden = address@hidden
Documentation/notation/changing-defaults.itely:\tweak
address@hidden@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.

--
You received this message because this project is configured to send all  
issue notifications to this address.
You may adjust your notification preferences at:
https://code.google.com/hosting/settings