Re: NR: Document \remove "Keep_alive_together_engraver" (issue 318580043 by address@hidden)

[David Kastrup]

Urs Liska <address@hidden> writes:

> Am 17.02.2017 um 09:21 schrieb David Kastrup:
>> Urs Liska <address@hidden> writes:
>>
>>> Am 17.02.2017 um 08:34 schrieb address@hidden:
>>>> Ok, I'll bite.  What kind of piano music is written like
>>>>
>>>> \score {
>>>>   \new PianoStaff <<
>>>>     \new Staff = "up" <<
>>>>       \structure
>>>>       \v.1
>>>>       \v.2
>>>>     >>
>>>>     \dyn.1
>>>>     \new Staff = "mid" <<
>>>>       \structure
>>>>       \v.3
>>>>       \v.4
>>>>     >>
>>>>     \dyn.2
>>>>     \new Staff = "lo" <<
>>>>       \structure
>>>>       \v.5
>>>>     >>
>>>>   >>
>>>> }
>>>>
>>>> Because that is the example underlying your report.
>>> Piano Music, at least starting with Liszt, all the way through into the
>>> 20th century and until today.
>>> The Ravel piece here requires five individual voices that are basically
>>> distributed among three staves (frequent staff changes included), but
>>> are printed partially on a three-stave PianoStaff and partially using
>>> only the standard two staves.
>>>
>>> I feel it's natural to use PianoStaff here and to tell it to french
>>> the middle system if empty.
>> PianoStaff is explicitly for the case where you want staves to be
>> frenched together.  Its name does not mean "Piano inside" but rather
>> "Use frenching conventions common in piano music".
>
> Then I'm tempted to file a bug report about PianoStaff being misnamed.

Well, you can write bass notes in a treble clef and vice versa and
tenors rarely use a tenor clef.

> What else should the name PianoStaff imply than "Piano inside"?

A staff for the conventions typical for piano.  Lyrics contexts are used
for more than lyrics, and the ChordNames context is unsuitable for the
chord placement conventions of accordion.

If you are writing a chant for choir, you are unlikely to use a
ChoirStaff.

> What you are describing may be what developers have thought when
> inventing the PianoStaff context, but for a user it is obvious that it
> refers to "piano".  Besides, "contexts explained" gives yet another
> explanation, namely GrandStaff with support for grouped instrument
> names.

Well, you might want to fix _that_ piece of documentation.  GrandStaff
and PianoStaff are totally equivalent in that regard.

I am not quite sure since when.

commit 8656e359d629aed6990bb8d8d3da8eac2d2c311e
Author: Reinhold Kainhofer <address@hidden>
Date:   Tue Jan 25 17:59:02 2011 +0100

    Add the Instrument_name_engraver also to all group contexts
    
    Also, make sure it is not inherited from the parent (in particular
    in nested staff groups).

looks like it might be related.

>> And you actually would still not want it to french out multiple staves
>> in an orchestral context: it should retain at least the two outer
>> voices.
>
> Then PianoStaff should have a (so-far-nonexistent)
> Remove_all_but_two_staves engraver by default .

I don't really think that we should let the context names overdetermine
the semantics in hard-to-understand, hard-to-explain and
hard-to-override manners.

Contexts are building blocks for a score.  We should document how to use
them to best advantage and how to use them as the basis for more complex
tasks.  But they are really not supposed to outsmart the user.

>> So one solution might be to remove the middle stave from the
>> Keep_alive_together_engraver's scope, with a proper setting of, uh,
>> VerticalAxisGroup.remove-layer ?
>>
>> I'm a bit fuzzy on our current state in that area.
>>
>>> What I think I'll write to the docs now is that you have the choice
>>> between resorting to GrandStaff (for the piano) or to remove the
>>> engraver.
>> There really is no point to removing an engraver when the sole purpose
>> of PianoStaff is to add it.  
>
> This is obviously a developer-centric way to see it. From any user's
> perspective the primary purpose of PianoStaff is to enclose piano
> music in it.

We cannot foresee and foreplan every use case that a user may want.  We
don't have an "OrganStaff" either: there is just too much variety in the
notation there and possibly desired Frenching.

For piano music, a two-staff container without independently frenched
voices is typical.  Non-bottom Contexts are _containers_ that always
start out empty and have to be filled by the user.  We don't have
control about what the user might want to fill in here.

If we wanted this control, we would need all of \PianoTrebleStaff,
\PianoBassStaff, \PianoOptionalStaff contexts and tell the user to fill
only those into a PianoStaff.  If we wanted to be obnoxious about it, we
would \denies every other staff context type.

There might be some incentive for a specific piano music style file to
do it in this manner.

But as core LilyPond functionality, it seems out of place.

>> Our documentation should focus more on keeping people on top of
>> LilyPond rather than teaching them how to stumble along when they
>> have no clue.  Because there are a whole lot of ways to do that and
>> if we wanted to document all of them...
>
> Well, so far no suitable way to create slightly extended (but common
> since about 1830) piano notation has been documented.

"common" is a strong word.  I have hundreds of piano scores in my
possession, and exactly zero of them have other than two staves.

> The obvious solution (\RemoveEmptyStaves) doesn't work, and the
> suggestion to use GrandStaff because PianoStaff is not actually meant
> for piano music is, well, strange.

PianoStaff is meant for the _usual_ conventions of piano music, like
ChoirStuff is meant for the _usual_ conventions of choir music.

If you have different requirements, they still make for a good starting
point.  But I don't think we are doing users a favor when we are trying
to hide from them what GrandStaff is good for.

-- 
David Kastrup