RE: include multiple utility modules vs one larger one

> The compiler we're using produces "warnings" about circular 
> references which we took to mean they were inefficient, bad 
> or otherwise to be avoided.

Circular imports and includes are fatal errors. The compiler has no business
giving you a warning, it should reject the code as incorrect.

You never need circular imports and includes, because a module doesn't have
to import/include everything it is dependent on. 

This doesn't just mean that the import/include graph should be acyclic, it
also means it should be a tree rather than a lattice. A lattice structure
isn't intrinsically an error, but it can cause errors (especially in the
case of include) because it generates multiple objects (e.g. functions) with
the same name; and it can also cause inefficiencies due to having multiple
copies of the same code (typically template rules).

If you want maximum flexibility to use a module in different stylesheet
configurations, it's probably best if it doesn't import/include anything,
but merely documents its dependencies. It's then the job of the top level
stylesheet module to include/import enough to ensure that all the
dependencies are satisfied. 

I think it's unlikely that performance should ever be a deciding factor, or
even an influencing factor, in determining how you modularise your code.
It's not impossible - a few years ago I encoutered a stylesheet that
performed pathologically badly in Saxon because it contained thousands of
unused global variable declarations (problem long since fixed). But you'll
only find such issues by making measurements, not by theorising about them.

Michael Kay
http://www.saxonica.com/