With Scribble-formatted API documentation, one thing I kinda miss from
Lisp-y manuals (such as those formatted by Texinfo, or CLtL2) is a
better cue that something is documenting, say, a procedure, rather than
syntax, rather than a parameter.
One way to do this with Scribble would be to subtly add a label to the
light blue background for definition syntax synopses. For example
(click the second thumbnail): http://imgur.com/a/xFTFn
Of course, with this particular format, the definition could obscure
this label, so unless you wanted to make the label a really big font
that was intended to be obscured (which doesn't really fit the look of
the manuals), it would complicate formatting.
Or you could put the label in the right margin, where footnotes go, but
I'd actually like to get rid of the right margin as a necessary thing
later, and turning footnotes into hover slide-outs when there isn't
enough horizontal room, so I'm not fond of putting anything new in the
margins that we'd want visible as cues.
Comments?
Neil V.
____________________
Racket Users list:
http://lists.racket-lang.org/users
