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/ _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
