Clearify use of break-align-orders in NR A.17 Layout properties

Clearify use of break-align-orders in NR A.17 Layout properties

Issue 3939

It should be sufficient to refer to
'Separating key cancellations from key signature changes' from
Documentation/snippets to show how to get different settings for end-of-line,
middle of line, and start-of-line

[thomasmorley651, 2014-06-01 23:05:11]

Please review

[thomasmorley651, 2014-06-02 21:47:59]

Better referencing

[Carl, 2014-06-02 23:23:23]

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.

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.

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

[Carl, 2014-06-02 23:36:15]

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

Another (probably clearer and easier) alternative would be to bring the snippet
that demonstrates the desired property usage into the Notation reference as a
Selected Snippet at an appropriate location, probably in section 1.1.3 (which
already references the Pitches section of snippets, which contains the
referenced snippet.

[thomasmorley651, 2014-06-03 22:14:39]

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

[Trevor Daniels, 2014-06-05 09:36:24]

On 2014/06/03 22:14:39, thomasmorley651 wrote:
> 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.
> 
> 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?

First, there is no difficulty in using overrides in the NR,
but the strong preference is to do this in an included snippet
from the LSR rather than as an inline snippet.

I suggest adding a new subsubsubsection to 
NR 1.6.2 Modifying single staves
which could be entitled "Modifying prefatory matter".

Then you could simply reference the snippet 
"Separating key cancellations from key signature changes
from there.

That's the minimum.  The snippet could be introduced with more
inline words or the snippet itself could be elaborated, or even 
new snippets created to illustrate the issue further.

Trevor

[Trevor Daniels, 2014-06-05 09:42:54]

On 2014/06/05 09:36:24, Trevor Daniels wrote:

> I suggest adding a new subsubsubsection to 
> NR 1.6.2 Modifying single staves
> which could be entitled "Modifying prefatory matter".

Correction: I should have said "subsubsubheading".

Trevor

[Carl, 2014-06-08 01:11:12]

On 2014/06/05 09:42:54, Trevor Daniels wrote:
> On 2014/06/05 09:36:24, Trevor Daniels wrote:
> 
> > I suggest adding a new subsubsubsection to 
> > NR 1.6.2 Modifying single staves
> > which could be entitled "Modifying prefatory matter".
> 
> Correction: I should have said "subsubsubheading".
> 
> Trevor

I think that it would be better to add a new subsubsection

NR 1.6.4 Prefatory matter

Really, IMO the current problem is that there is no place that discusses these
items.

Pitches discusses key signatures, which is why I suggested it.  It also
discusses clefs.  Span bars are discussed in Bars NR 1.2.5.  Time signatures are
discussed in NR 1.2.3 Displaying Rhythms.  

WIth all of the individual items defined in different places, putting
break-align-orders in these places is not the right thing to do.

Changing break-align-orders could be done for a StaffGroup, IIUC, so I don't
think it belongs in 1.6.2.

Since none of these places works, I think it needs its own subsubsection in
Staff Notation.

Thanks,

Carl

[Trevor Daniels, 2014-06-08 09:59:23]

On 2014/06/08 01:11:12, Carl wrote:
> On 2014/06/05 09:42:54, Trevor Daniels wrote:
> > On 2014/06/05 09:36:24, Trevor Daniels wrote:
> > 
> > > I suggest adding a new subsubsubsection to 
> > > NR 1.6.2 Modifying single staves
> > > which could be entitled "Modifying prefatory matter".
> > 
> > Correction: I should have said "subsubsubheading".
> 
> I think that it would be better to add a new subsubsection
> 
> NR 1.6.4 Prefatory matter

I've no objection to this, but the rather more general
heading you suggest means it would require rather more
work than just pointing to an LSR snippet I think.  At the
very least we'd need to explain what prefatory matter is.

Trevor