Re: Document all outside-staff-priority values; neaten table (issue 280580043 by address@hidden)

[pkx166h]

On 2016/01/01 16:14:49, c_sorensen wrote:

> On 1/1/16 5:43 AM,
mailto:"address@hidden on
> behalf of mailto:address@hidden";
> <mailto:address@hidden on behalf of
> mailto:address@hidden> 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

https://codereview.appspot.com/280580043/