order of engravers

[Graham Percival]

Talking about
http://code.google.com/p/lilypond/issues/detail?id=673
problem with order of \consists


On Tue, Apr 27, 2010 at 1:38 PM, Kieren MacMillan
<address@hidden> wrote:
> Reviewing the situation, I'm not sure I *need* to send a patch: the Learning 
> [!!] page
>
>    
> <http://lilypond.org/doc/v2.13/Documentation/learning/adding-and-removing-engravers#Adding-and-removing-engravers>
>
> has a link at the bottom to the Notation page
>
>    
> <http://lilypond.org/doc/v2.13/Documentation/notation/modifying-context-plug_002dins>
>
> which, in turn, has the clear and helpful note
>
> "Usually the order in which the engravers are specified does not matter, but 
> in a few special cases the order is important, for example where one engraver 
> writes a property and another reads it, or where one engraver creates a grob 
> and another must process it. The order in which the engravers are specified 
> is the order in which they are called to carry out their processing.
>
> The following orderings are important: the Bar_engraver must normally be 
> first, and the New_fingering_engraver must come before the 
> Script_column_engraver. There may be others with ordering dependencies."
>
> So what should we add to either page to make it clearer?

Don't change anything on the Learning page.

For the Notation page, there's four options:

1)  Add a sentence about default_bar_line_engraver and
timing_translator  (or whatever Werner was talking about on 673).  I
know we've already said "there order may matter; here's one example,
but there may be others", but we might as well list this case since it
came up.

2)  Do some trawling through the IR and/or code (as per Han-Wen's
comment 5 in the issue)  and try to discover all dependency chains of
engravers, then list all those in Notation.  If you go to this much
effort, we might as well make a separate section (well,
unnumberedsubsubsec) in the docs for these dependency chains.

3)  Do #1, but put it in a new unnumberedsubsubsec for better visibility.

4)  Pester some code people into adding "this context/engraver depends
on context/engravers foo band bar" into the code documentation, such
that this info will automatically get into the IR.  Oh, maybe modify
the IR-generation functions to read this new info.

umm, in doxygen terms, I'm thinking of something like
  \depends
but I don't know offhand how this might fit into the IR-generation stuff.


hmm... I'm thinking that we should do 3, then add 4 to the tracker.  4
could be a fantastic project for a Frog that was thinking about
improving the IR... it's a relatively small change, and frankly
relatively unimportant (so it doesn't matter if it doesn't get done
for 2 years), but OTOH it forces them to learn a lot about the
IR-generation routines.  If there's ever any serious effort to improve
the IR (and I know people have been talking about this for years),
then this makes a good "first hurdle" so we can see whether people are
willing to "walk the walk" instead of just talking.  :)


At this stage, I think the doc change is up to you, Kieren: you've
done at least 100 times as much IR-reading / tweaking as I have, so I
value your opinion on this stuff more than my own.  Decide whether you
want #1, 2, or 3 (after waiting for potential comments), then email
the new text to James.

James: we haven't talked about adding new unnumberedsubsubsec yet, but
this is a good time to do it since it's not urgent.


For #4, we'll wait for comments (or immediate offers of help, haha),
and then add it to the tracker as a postponed item.

Cheers,
- Graham