We're hitting a particular pain-point in Scribble with regards to the itemlist function. I'm documenting this experience to inform any future Scribble designs.
We're running into two pain points with itemlist: 1. The contract checking for itemlist does not give precise location on an item that violates the item? contract. Our itemlists tend to be long, document-spanning monstrosities. Under this situation, the contract source reporting is useless: it highlights the whole document. We end up resorting to manually binary searching the document whenever we hit this class of error. 2. The item structure itself does not lend itself well to immediate styling, nor does it really serve any role other than gathering pre-flow together. But there are already mechanisms in the language for bundling pre-flow content together, such as para, nested, etc. If itemlist were to be generalized to consume these structures, it would be much more pleasant to work with. I'm focusing on itemlist quite a bit, but I have similar concerns with other Scribble constructs that consume lists or a large number of arguments. For point 1, one possibility would be to record source location and make it available for the runtime and the contract system. Most of the interesting Scribble errors happen at runtime, and the lack of precise location really hurts since the contract checks can't currently pinpoint the locations of runtime values such as list elements. #%datum and constructors such as (list ...) for scribble-based languages might be customized so that these values remember their source location. That way, the contract system has the opportunity to report useful locations. ____________________ Racket Users list: http://lists.racket-lang.org/users
