#4993 Doc: Please document the alternativeRestores context property, including its default setting

http://codereview.appspot.com/323450043

Reported by Holland Hopson:

Please document the alternativeRestores context property, including its default setting. The default settings can lead to apparent bar-check failures when there are time signature changes in an \alternative block.

The default is alternativeRestores = #'(measurePosition measureLength lastChord).

:::TeX
\version "2.19.49"

music =
{
  \repeat volta 2 {
    c1
  }
  \alternative {
    {
      \time 3/4
      d2. |
      \time 4/4
      c1 |
    }
    { d1 | }
  }
}
<<
  \relative c'' \music
  \relative c' \music
>>

[Trevor Daniels]

The alternativeRestores context property is documented in the IR. What I think is rather needed is a warning Note in the NR in the section dealing with alternative repeats like this:

Note: If there are two or more alternatives it is assumed that they all begin with the same time signature. If this is not the case, be sure to place an appropriate time command at the start of each alternative in which the starting time signature differs from that in the first alternative.

I'll prepare a patch along these lines.

[Trevor Daniels]

Doc: Issue 4993 Different time signatures in alternative repeats

Add warning to NR about alternatives starting with
different time signatures.

http://codereview.appspot.com/323450043

[David Kastrup]

This appears to be actually a bug (and embarrassingly, the regtest is also afflicted): the settings in alternativeRestores are recorded after the first alternative already had a chance to change them. I'll take a look at how this may be fixed: we had a similar conundrum with grace timings where it was tricky to distinguish \override ... \grace {...} from \grace {\override ... ...}. Getting this done reliably might require a similar mechanism here.

[Anonymous]

Passes make, make check and a full make doc.

[Trevor Daniels]

Set to "needs work" while David K is investigating the feasibility of a proper solution.