[racket] Scribble pain-point: itemlist

I've finally taken a look at this, and I agree that `itemlist' should
be more flexible.

If I remember correctly, the reason for `item' was to group a list of
blocks into a single flow. There's no specific constructor for a "flow"
--- it's just a list of blocks --- and I thought a list of blocks for
each item would be confusing.

I see that you are, in fact, treating a list as a list of blocks and
converting it to an item. That clashes somewhat with the convention in
Scribble to treat a list as splicing. Meanwhile, you're relying on
`splice's for splicing --- and distinguishing lists from splices was
the original intent of `splice', but we've moved toward lists for
splicing, anyway.

So, in `itemlist' from `scribble/base', I think it's probably better to
treat a list as splicing and to continue relying on `item' wrappers for
multi-block flows. At the same time, a single block can be coerced to
an `item', which is probably even more convenient for avoiding the
`item'-`list' combination wrappers.

At Tue, 17 Jul 2012 16:22:59 -0400, Danny Yoo wrote:
> >    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.
> 
> 
> Followup: in my own project, I'm replacing the implementation of
> itemlist with a custom one that is easier to work with.
> 
> 
> I guess that the motivation for @item is to mimic LaTeX's "\item".
> However, since we're dealing with real functions that can consume
> multiple values, each item is already conceptually distinct as an
> argument to itemlist.
> 
> @item makes the @itemlist construct  difficult to work with.  So I'm
> doing something like this now in my customized Scribble language, and
> am happier for it:
> 
> ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
> 
> (provide [rename-out [itemlist/splicing itemlist] [fake-item item]])
> 
> ;; itemlist/splicing is like itemlist, but also cooperates with the
> ;; splice form to absorb arguments.  We also treat each item
> ;; automatically with an @item if it's missing.
> (define (itemlist/splicing #:style [style #f] . items)
>   (define spliced-items
>     (reverse
>      (let loop ([items items]
>                 [acc '()])
>        (foldl (lambda (i acc)
>                 (cond
>                  [(splice? i)
>                   (loop (splice-run i) acc)]
>                  [(item? i)
>                   (cons i acc)]
>                  [else
>                   (cons (item i) acc)]))
>               acc
>               items))))
>   (apply itemlist spliced-items #:style style))
> 
> 
> ;; fake-item: (listof any) -> (listof any)
> ;; We try to make itemlist more pleasant to work with.
> Itemlist/splicing automatically
> ;; wraps items around every argument, so there's no need to call item
> explicitly.
> ;; We provide a fake definition for fake-item that just returns the identity.
> (define (fake-item . args)
>   args)
> ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
> ____________________
>   Racket Users list:
>   http://lists.racket-lang.org/users