[racket] Scribble pain-point: itemlist

From: Danny Yoo (dyoo at hashcollision.org)
Date: Mon Jul 9 12:48:04 EDT 2012

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.

Posted on the users mailing list.