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

[thomasmorley65]

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.
Furthermore,
> 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
document-context-mods.scm)
and
3 occurences of @ruser (not included the ones from
document-translation.scm)
and
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
> break-align-orders.

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
all.
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
pitches.
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.
Suggestions?


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

> I am not in favor of this patch.

> Thanks,

> Carl

Thanks for review, I highly apreciate your thoughts



https://codereview.appspot.com/96650050/