Mats Bengtsson wrote:
Paul Scott wrote:
1. The documentation and/or implementation of BarNumber direction is
incorrect: #RIGHT and #LEFT give the same result as #UP and #LEFT
respectively. The documentation error may have just been the result
of an unfinished cut-and-paste. As far as I am concerned there is no
need for #RIGHT, #LEFT or #CENTER values for the direction variable.
If others want bar numbers on any possible corner of a bar then maybe
a new variable should be introduced.
As I have already tried to explain, several different layout objects
have the "direction"
property and for some objects it means UP/DOWN for others it means
LEFT/RIGHT.
For example, in the following score, we move the arpeggios from the
default left
to right and the bar numbers from the default up to down.
I haven't needed to tweak an arpeggio yet but looking at the
documentation I consider the same "explanation" for direction under the
Program Reference for Arpeggio to be just as confusing. Please note
that an added problem is that the other entries in the program reference
for Arpeggio and BarNumber have some verbal information as to what the
variable does whereas direction only gives its (confusing) values
without saying what they mean.
\version "2.8.0"
\score{
\new Staff \relative c' {
\override Score.BarNumber #'break-visibility = #all-visible
\override Score.BarNumber #'direction = #DOWN
c1 |
<c e g>\arpeggio |
\override Arpeggio #'direction = #RIGHT
<c e g>\arpeggio |
}
}
Ideally, we should have different documentation texts for these two
situations.
Why not?? That should be easy enough! (see below)
However, for technical reasons, the documentation of a property is the
same for
all objects where the property appears. This in turn means that the
text has to cover
all the situations, i.e. it has to mention both up/down and
left/right. In this particular
case it's possibly a bit confusing but all the information is there.
However, for other
properties like "style", the current documentation text is
"This setting determines in what style a grob is typeset. Valid
choices depend on the @code{stencil} callback reading this property."
which doesn't really provide any useful information.
"style" at least has a verbal description of what it does. "direction"
does not.
So, what you really ask for is that we can have different versions of the
documentation for a property depending on what object it applies to.
If it's confusing yes. Especially in the case of BarNumber.
However, this would probably require a major modification to the current
functions that automatically compile the manual.
Since you say "probably" maybe you're not sure. I certainly have not
looked at how this documentation is produced (and maybe I will have to)
but since each Program Reference entry has a different set of properties
I don't see why it would be complicated to pick the up/down version of
direction to be included in the Program Reference for Arpeggio and
apparently BarNumber and any others that need it and the
left/center/right versions for the ones that need that. That only means
one more version of a few lines of text.
Also, it would lead to more
job to keep all these almost identical pieces of text up to date.
Not if a procedure as I just described is used.
Finally, for over 90%
of the properties, it makes perfectly sense to have the same
documentation
regardless of the layout object it applies to.
That means that 90% of the "code" won't have to be changed.
If it would lead to as much work as you say then at least a verbal
description of what direction means should be included as it is for
(most?) other properties.
Regards,
Paul
_______________________________________________
bug-lilypond mailing list
bug-lilypond@gnu.org
http://lists.gnu.org/mailman/listinfo/bug-lilypond
