Create Score context before starting iteration.

Create Score context before starting iteration.

This means Score-level translators can rely on being created at the beginning
of iteration, rather than in the middle of a timestep. This prevents bugs like
issue 2392 and makes maintaining translators easier.

Revert commit 6b9921f0e2b8c73ebb3063109562d97fba898dab (the previous
fix for issue 2392), since it's no longer needed.

Add comments explaining how iteration works.

[Devon Schudy, 2013-12-21 21:03:44]

Add test case. Mention ly_interpret_music_expression and create_children. Add
dubious start_translation_timestep call.

[Devon Schudy, 2013-12-21 21:47:34]

Clean up test case.

[Devon Schudy, 2013-12-23 00:35:33]

Document iteration in CG too. Fix error in Score context doc.

[dak, 2013-12-25 19:41:26]

https://codereview.appspot.com/44860045/diff/60001/Documentation/contributor/...
File Documentation/contributor/programming-work.itexi (right):

https://codereview.appspot.com/44860045/diff/60001/Documentation/contributor/...
Documentation/contributor/programming-work.itexi:43: event a moment (a time) and
a context, which is the environment in which the
No, events are not assigned a time.  And neither are they assigned a context.

Iteration interprets music expressions through "iterators".  Most of the effects
are subsequently produced through "stream events".  Events are "broadcast" by
iterators in a particular context at a given global time.  This broadcast is
received by event listeners, usually in the form of "translators" (in the
printed output, "engravers") in the context or any parent context.  The
translators are responsible for initiating further processing.

https://codereview.appspot.com/44860045/diff/60001/Documentation/contributor/...
Documentation/contributor/programming-work.itexi:1578: @item @code{ok ()}
returns whether there are any events left to send.
I think that ok () is only relevant when the iterator is of the run_always kind.
 If it isn't, pending_mom () gives the next time of call.

Don't consider this authoritive: that's more or less what I tried figuring out
from the code and remember right now without actually cross-checking.

But it might help you get a better idea of what to write here actually after
checking the code again.

https://codereview.appspot.com/44860045/diff/60001/input/regression/initial-c...
File input/regression/initial-contexts.ly (right):

https://codereview.appspot.com/44860045/diff/60001/input/regression/initial-c...
input/regression/initial-contexts.ly:10: %%and iteration can't skip time without
it.
This comment is a bit of a non-sequitur: time is kept in the Global context, so
it could get skipped.  I am not actually sure how SkipEvent even works.

https://codereview.appspot.com/44860045/diff/60001/lily/global-context.cc
File lily/global-context.cc (right):

https://codereview.appspot.com/44860045/diff/60001/lily/global-context.cc#new...
lily/global-context.cc:135: //Maybe they should be called directly rather than
through events.
If you called them directly, the EventListener framework used for quoting and
part combining would stop working.

https://codereview.appspot.com/44860045/diff/60001/lily/global-context.cc#new...
lily/global-context.cc:148: find_create_context (default_child_, "", SCM_EOL);
This precludes \new Score \with ..., quite a no-no.

https://codereview.appspot.com/44860045/diff/60001/lily/translator-group.cc
File lily/translator-group.cc (right):

https://codereview.appspot.com/44860045/diff/60001/lily/translator-group.cc#n...
lily/translator-group.cc:232: if (!new_context->now_mom
().main_part_.is_infinity ())
Don't understand that condition.

https://codereview.appspot.com/44860045/diff/60001/lily/translator-group.cc#n...
lily/translator-group.cc:235: DOWN);
Isn't that sufficient to have the Score context created in time?  Without
requiring the other fixes?

https://codereview.appspot.com/44860045/diff/60001/ly/engraver-init.ly
File ly/engraver-init.ly (right):

https://codereview.appspot.com/44860045/diff/60001/ly/engraver-init.ly#newcod...
ly/engraver-init.ly:527: @code{\\score} or @code{\\layout} block) is processed."
If a Score context would be created automatically when an output definition is
processed, one _could_ not create it explicitly afterwards.  These two sentences
are contradictory.

[Devon Schudy, 2014-01-03 19:07:55]

David Kastrup wrote:
>
https://codereview.appspot.com/44860045/diff/60001/input/regression/initial-c...
> input/regression/initial-contexts.ly:10: %%and iteration can't skip time
> without it.
> This comment is a bit of a non-sequitur: time is kept in the Global
> context, so it could get skipped.

Hmm, \skip successfully skips time, but doesn't update
measurePosition, because Timing_translator doesn't exist yet, so the
barlines are in the wrong places.

>  I am not actually sure how SkipEvent even works.

Apparently it (and SkipMusic) just works by having a nonzero length.

>
https://codereview.appspot.com/44860045/diff/60001/lily/global-context.cc#new...
> lily/global-context.cc:148: find_create_context (default_child_, "",
> SCM_EOL);
> This precludes \new Score \with ..., quite a no-no.

\new Score creates the context in construct_children, so that still
works. Something like { \skip 4 \new Score ... } would fail, though.
Should that work?

[on calling start_translation_timestep for new translators]
> Isn't that sufficient to have the Score context created in time?
> Without requiring the other fixes?

It doesn't create it in time, but it does start the Score translators
properly when they're created late — but it still doesn't start
Score_performer correctly, because it's a Translator_group, not a
translator. However, the only Translator_group per_timestep
initialization is creating Score_performer::audio_column_, so if
Audio_column goes away, there's nothing left to do there.

[dak, 2014-01-03 19:49:28]

On 2014/01/03 19:07:55, Devon Schudy wrote:
> David Kastrup wrote:
> >
>
https://codereview.appspot.com/44860045/diff/60001/input/regression/initial-c...
> > input/regression/initial-contexts.ly:10: %%and iteration can't skip time
> > without it.
> > This comment is a bit of a non-sequitur: time is kept in the Global
> > context, so it could get skipped.
> 
> Hmm, \skip successfully skips time, but doesn't update
> measurePosition, because Timing_translator doesn't exist yet, so the
> barlines are in the wrong places.

Ugh.  Ok, that's bad.

>
https://codereview.appspot.com/44860045/diff/60001/lily/global-context.cc#new...
> > lily/global-context.cc:148: find_create_context (default_child_, "",
> > SCM_EOL);
> > This precludes \new Score \with ..., quite a no-no.
> 
> \new Score creates the context in construct_children, so that still
> works.

That sounds shaky enough to warrant a good explanation in comments.

> Something like { \skip 4 \new Score ... } would fail, though.
> Should that work?

Excellent question.  Could be used for putting some delay into the MIDI before
the score starts.  But whether that _should_ work in that manner?  No idea. 
What when the Timing_translator is moved to Staff level?  It would seem like
nothing makes sense but having MeasurePosition start at \new Staff when a staff
is started after other staves.  In analogy to that, "should that work" might
indeed warrant a tentative "yes", starting with a measurePosition of 0.

> [on calling start_translation_timestep for new translators]
> > Isn't that sufficient to have the Score context created in time?
> > Without requiring the other fixes?
> 
> It doesn't create it in time, but it does start the Score translators
> properly when they're created late — but it still doesn't start
> Score_performer correctly, because it's a Translator_group, not a
> translator. However, the only Translator_group per_timestep
> initialization is creating Score_performer::audio_column_, so if
> Audio_column goes away, there's nothing left to do there.

This is really headache material.