[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Clearify use of break-align-orders in NR A.17 Layout properties (iss

From: thomasmorley65
Subject: Re: Clearify use of break-align-orders in NR A.17 Layout properties (issue 96650050)
Date: Tue, 03 Jun 2014 22:14:39 +0000

On 2014/06/02 23:23:23, Carl wrote:
On 2014/06/02 21:47:59, thomasmorley651 wrote:
> Better referencing

I think that this is a wrong approach.  The list of properties in the
.scm file
is not the appropriate place to teach the use of the properties.
in my opinion there should be no links from the code to the
documentation.  The
links should always go from the documentation to the code.

I did some grepping through the scm-files and found
15 occurences of @rinternals (not included the ones from
3 occurences of @ruser (not included the ones from
2 instances in define-grob-properties.scm where an example is given,
both more or less related to BreakAlignment.

The appropriate way for a user to come to understand this (if they
haven't found
the snippet) is to find the appendix, then search the manual for

I'm not sure I understand what we expect from an average user here.
Apart from A.17 Layout properties there is only one occurence of
BreakAlignment in the NR, but without explaing why it is nessacary at
I doubt the user has the chance to figure that he has to override
BreakAlignment.break-align-orders, if he wants to change the order of
the items.

More, I have to confess that I was not aware of 'Separating key
cancellations from key signature changes' before I did some git grep.

The whole point of this patch is linking the user to some usable
example-code without explaining the characteristics of (make-vector ...)

If it is not acceptable to link from the description in
define-grob-properties.scm, then we _should_ link and/or explain it in
the NR.
Though, where? I think doing it in section '1.1.3 Pitches' is not
appropriate, I feel BreakAlignment has only a loose relationship to
Maybe in '1.6 Staff notation', though, I'm not convinced either.
And our general policy is not to use overrides in NR.
Or in section '5. Changing defaults' as an example-code?

I'm a bit helpless.

Trying to maintain bidirectional linkage between the code and the
is a recipe for bitrot, I believe.

I am not in favor of this patch.



Thanks for review, I highly apreciate your thoughts

reply via email to

[Prev in Thread] Current Thread [Next in Thread]