Many people have been confused by what happens when you try to order rules in rulebooks with “The foo rule is listed before the bar rule in the check bazzing rulebook.” In particular, if you have two declarations (involving three rules), the rules may not wind up where you expect. See the example in this bug report.
Graham has submitted a new comment that explains what is going on:
Unpacking what he’s saying, I think this is what’s happening (and is supposed to happen, apparently):
First the compiler orders the rules in the rulebook by specificity order.
Then it goes through the rule-ordering declarations, in the order they appear in the source code.
If a rule is declared to be listed first, it gets moved to the front of the rulebook.
If a rule is declared to be listed last, it gets moved to the back of the rulebook.
If the foo rule is declared to be listed before the bar rule, then according to section 18.4 of the documenation, it is supposed to be placed before the bar rule in specificity order. But what happens if it winds up tied with another rule in specificity? Then it appears from the example listed in bug report 514 that it gets put last among the tied rules (so long as this keeps it before the bar rule). This can mean it gets moved later in the rulebook than it otherwise would be! That’s what happens in the first declaration Graham discusses, where the effect of listing the 1st rule before the 2nd rule is to move it after the 3rd rule.
Similarly if the foo rule is listed after the bar rule.
And the upshot is, if you declare “the foo rule is listed before the bar rule” and later declare something about the bar rule that moves it, the foo rule may not wind up before the bar rule. There isn’t any attempt to respect all the declarations at once. (This is at least somewhat in line with what is said in 18.4)
The confusion appears to arise from the way that “listed before” declarations handle rules that are tied with respect to specificity. I’m going to file a documentation bug on that to see what happens.
Oh, and Grahamologists may be interested to know that Graham is closing masses of bugs right now.