Document all outside-staff-priority values; neaten table

Follows on from a question on -user.  There aren't that many values of outside-staff-priority, so it seems easiest to list them all if we're going to list most.  The adjustments to the column widths get rid of unnecessary line wrapping.

Please review.

[PhilEHolmes, 2016-01-01 12:43:41]

Please review.

[Trevor Daniels, 2016-01-01 14:41:10]

I've no problem with extending the list, but see comment below.

https://codereview.appspot.com/280580043/diff/1/Documentation/learning/tweaks...
File Documentation/learning/tweaks.itely (right):

https://codereview.appspot.com/280580043/diff/1/Documentation/learning/tweaks...
Documentation/learning/tweaks.itely:2296: table above, and reduce it to a value
lower than that of a
I would prefer to leave the reference to the IR in place, as the main thrust of
this chapter is to give people the confidence to use it.  It will need to be
used to find the correct context anyway - this was intended as part of the
learning process.  Also, although it seems unlikely that more outside-staff
grobs will be introduced now, it is prudent not to suggest the list is complete
as that implies a commitment to maintain it complete.

[PhilEHolmes, 2016-01-01 15:09:12]

Updates following Trevor's suggestions

[simon.albrecht, 2016-01-01 15:19:20]

On 01.01.2016 13:43, PhilEHolmes@googlemail.com wrote:
> Reviewers: ,
>
> Message:
> Please review.
>
> Description:
> Follows on from a question on -user.  There aren't that many values of
> outside-staff-priority, so it seems easiest to list them all if we're
> going to list most.  The adjustments to the column widths get rid of
> unnecessary line wrapping.
>
> Please review.
>
> Please review this at https://codereview.appspot.com/280580043/

I’m replying on the list, since this doesn’t refer to the particular code.
I’ve been wondering before if this should be referenced in the NR; I 
tend to look in the NR and have a hard time until I remember that this 
table was in the LM, and where.
Perhaps we could insert something like

A complete listing of outside-staff-priorities may be found in
@rlearning{The outside-staff-priority property}.

in Documentation/notation/spacing.itely, after line 2643.

Yours, Simon

[c_sorensen, 2016-01-01 16:14:49]

On 1/1/16 5:43 AM, "lilypond-devel-bounces+c_sorensen=byu.edu@gnu.org on
behalf of PhilEHolmes@googlemail.com"
<lilypond-devel-bounces+c_sorensen=byu.edu@gnu.org on behalf of
PhilEHolmes@googlemail.com> wrote:

>Reviewers: ,
>
>Message:
>Please review.
>
>Description:
>Follows on from a question on -user.  There aren't that many values of
>outside-staff-priority, so it seems easiest to list them all if we're
>going to list most.  The adjustments to the column widths get rid of
>unnecessary line wrapping.

After much tutoring from Graham, I believe this is the wrong thing to do,
for two reasons.

1) An exhaustive table that is manually, not automatically, generated is a
maintainability nightmare.
2) If an exhaustive table exists, it belongs in the NR, not the LM.

I believe the proper way to respond to the issue is the following:

Definitely right now:
A) In the LM, clarify the sentence on looking up OttavaBracket as follows:
"All we need to do is look up the outside-staff-priority of a TextSpanner
in the IR, and then set the outside-staff-priority of the OttavaBracket to
a slightly smaller value."

Optionally, based on some advanced texinfo magic:
B) Create an appendix in the NR that automatically finds all default
values of outside-staff-priority and creates a table.
C) Refer to this automatically-created table in the LM.

In my opinion, absent the automatically-created table, the right thing is
to strengthen the ability of the user to find the outside-staff-priority
of the relevant objects, not to create a potentially wrong table.

Thanks,

Carl

[PhilEHolmes, 2016-01-01 16:20:16]

With Simon's suggestion

[email_philholmes.net, 2016-01-01 16:26:27]

----- Original Message ----- 
From: "Carl Sorensen" <c_sorensen@byu.edu>
To: <PhilEHolmes@googlemail.com>; <lilypond-devel@gnu.org>; 
<reply@codereview-hr.appspotmail.com>
Sent: Friday, January 01, 2016 4:14 PM
Subject: Re: Document all outside-staff-priority values; neaten table (issue 
280580043 by PhilEHolmes@googlemail.com)




On 1/1/16 5:43 AM, "lilypond-devel-bounces+c_sorensen=byu.edu@gnu.org on
behalf of PhilEHolmes@googlemail.com"
<lilypond-devel-bounces+c_sorensen=byu.edu@gnu.org on behalf of
PhilEHolmes@googlemail.com> wrote:

>Reviewers: ,
>
>Message:
>Please review.
>
>Description:
>Follows on from a question on -user.  There aren't that many values of
>outside-staff-priority, so it seems easiest to list them all if we're
>going to list most.  The adjustments to the column widths get rid of
>unnecessary line wrapping.

After much tutoring from Graham, I believe this is the wrong thing to do,
for two reasons.

1) An exhaustive table that is manually, not automatically, generated is a
maintainability nightmare.
2) If an exhaustive table exists, it belongs in the NR, not the LM.

I believe the proper way to respond to the issue is the following:

Definitely right now:
A) In the LM, clarify the sentence on looking up OttavaBracket as follows:
"All we need to do is look up the outside-staff-priority of a TextSpanner
in the IR, and then set the outside-staff-priority of the OttavaBracket to
a slightly smaller value."

Optionally, based on some advanced texinfo magic:
B) Create an appendix in the NR that automatically finds all default
values of outside-staff-priority and creates a table.
C) Refer to this automatically-created table in the LM.

In my opinion, absent the automatically-created table, the right thing is
to strengthen the ability of the user to find the outside-staff-priority
of the relevant objects, not to create a potentially wrong table.

Thanks,

Carl
==============================================

I've been careful not to claim it's an exhaustive list, and following 
Trevor's comment have put back the pointer to the IR for any that isn't in 
the list above.  I've also made it possible to find in the NR.

It may be that other mechanisms are possible, but it does seem that having a 
sorted ordered list of those that are currently available is better than 
having half a list of some of them and making everyone repeat what I had to 
do to get this list: plough through the IR?


--
Phil Holmes 

[thomasmorley651, 2016-01-01 17:00:22]

On 2016/01/01 16:14:49, c_sorensen wrote:
> 
> On 1/1/16 5:43 AM, mailto:"lilypond-devel-bounces+c_sorensen=byu.edu@gnu.org
on
> behalf of mailto:PhilEHolmes@googlemail.com"
> <mailto:lilypond-devel-bounces+c_sorensen=byu.edu@gnu.org on behalf of
> mailto:PhilEHolmes@googlemail.com> wrote:
> 
> >Reviewers: ,
> >
> >Message:
> >Please review.
> >
> >Description:
> >Follows on from a question on -user.  There aren't that many values of
> >outside-staff-priority, so it seems easiest to list them all if we're
> >going to list most.  The adjustments to the column widths get rid of
> >unnecessary line wrapping.
> 
> After much tutoring from Graham, I believe this is the wrong thing to do,
> for two reasons.
> 
> 1) An exhaustive table that is manually, not automatically, generated is a
> maintainability nightmare.

+1

> 2) If an exhaustive table exists, it belongs in the NR, not the LM.
> 

+1


> I believe the proper way to respond to the issue is the following:
> 
> Definitely right now:
> A) In the LM, clarify the sentence on looking up OttavaBracket as follows:
> "All we need to do is look up the outside-staff-priority of a TextSpanner
> in the IR, and then set the outside-staff-priority of the OttavaBracket to
> a slightly smaller value."

+1

> 
> Optionally, based on some advanced texinfo magic:
> B) Create an appendix in the NR that automatically finds all default
> values of outside-staff-priority and creates a table.

FWIW, from inside a .ly-file it could be done, displaying to terminal:

#(for-each
  (lambda (x) (format #t "\n~30a~4,' d" (car x) (cdr x)))
  (append-map
    (lambda (e)
       (if (assoc-get 'outside-staff-priority (cdr e))
           (list 
             (cons (car e) (assoc-get 'outside-staff-priority (cdr e))))
           '()))
    all-grob-descriptions))

> C) Refer to this automatically-created table in the LM.
> 
> In my opinion, absent the automatically-created table, the right thing is
> to strengthen the ability of the user to find the outside-staff-priority
> of the relevant objects, not to create a potentially wrong table.
> 
> Thanks,
> 
> Carl
> 
>

[pkx166h, 2016-01-06 16:22:20]

On 2016/01/01 16:14:49, c_sorensen wrote:
> 
> On 1/1/16 5:43 AM, mailto:"lilypond-devel-bounces+c_sorensen=byu.edu@gnu.org
on
> behalf of mailto:PhilEHolmes@googlemail.com"
> <mailto:lilypond-devel-bounces+c_sorensen=byu.edu@gnu.org on behalf of
> mailto:PhilEHolmes@googlemail.com> wrote:
> 
> >Reviewers: ,
> >
> >Message:
> >Please review.
> >
> >Description:
> >Follows on from a question on -user.  There aren't that many values of
> >outside-staff-priority, so it seems easiest to list them all if we're
> >going to list most.  The adjustments to the column widths get rid of
> >unnecessary line wrapping.
> 
> After much tutoring from Graham, I believe this is the wrong thing to do,
> for two reasons.
> 
> 1) An exhaustive table that is manually, not automatically, generated is a
> maintainability nightmare.
> 2) If an exhaustive table exists, it belongs in the NR, not the LM.
> 
> I believe the proper way to respond to the issue is the following:
> 
> Definitely right now:
> A) In the LM, clarify the sentence on looking up OttavaBracket as follows:
> "All we need to do is look up the outside-staff-priority of a TextSpanner
> in the IR, and then set the outside-staff-priority of the OttavaBracket to
> a slightly smaller value."
> 
> Optionally, based on some advanced texinfo magic:
> B) Create an appendix in the NR that automatically finds all default
> values of outside-staff-priority and creates a table.
> C) Refer to this automatically-created table in the LM.
> 
> In my opinion, absent the automatically-created table, the right thing is
> to strengthen the ability of the user to find the outside-staff-priority
> of the relevant objects, not to create a potentially wrong table.
> 
> Thanks,
> 
> Carl
> 
> 

Carl I have created

https://sourceforge.net/p/testlilyissues/issues/4723/

for your request.

At this time we have pushed this change as this is 'better than nothing' than
waiting for someone who has the scripting skill needed to generate this
'automatic documentation' in the NR to update the table.

This isn't the first time that we have taken the 'manual' approach in the NR for
'lists of things/functions/commands'. I have created manual tables for a few of
the exhaustive lists in the NR Appendices. It is a maintenance headache but at
least it can be maintained by those that cannot 'code'.

I hope this is OK?

James

[pkx166h, 2016-01-06 16:22:40]

author	Phil Holmes <mail@philholmes.net>	
	Wed, 6 Jan 2016 16:09:50 +0000 (16:09 +0000)
committer	James Lowe <pkx166h@gmail.com>	
	Wed, 6 Jan 2016 16:10:31 +0000 (16:10 +0000)
commit	38bf956cd15ed3aa1cd296705f95bdbe56345e72

[c_sorensen, 2016-01-07 21:00:20]

On 1/6/16 9:22 AM, "pkx166h@gmail.com" <pkx166h@gmail.com> wrote:

>
>At this time we have pushed this change as this is 'better than nothing'
>than waiting for someone who has the scripting skill needed to generate
>this 'automatic documentation' in the NR to update the table.
>
>This isn't the first time that we have taken the 'manual' approach in
>the NR for 'lists of things/functions/commands'. I have created manual
>tables for a few of the exhaustive lists in the NR Appendices. It is a
>maintenance headache but at least it can be maintained by those that
>cannot 'code'.
>
>I hope this is OK?

It is not my preference, but I don't get to make the rules.  If the
community is fine with it, it is better than nothing.

In my opinion, it is not better than nothing, because it helps users avoid
knowing the never-wrong method of finding the outside-staff-priority.  But
it is certainly easier for users, as long as the list is maintained.

I am less concerned about the manual tables in the NR for items that have
the exhaustive list in the NR appendices, because we can always easily
point the user to the exhaustive list.

I guess what this means is I need to figure out how to automatically
generate the exhaustive list and add it to the NR.  If I am concerned
enough about it, I'll do that.

Thanks,

Carl