[racket] scribble formatting tweak?

[Neil Van Dyke]

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

[Asumu Takikawa]

On 2012-06-12 22:02:26 -0400, Neil Van Dyke wrote:
> 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

I really like this idea. +1.

> Of course, with this particular format, the definition could obscure
> this label

Maybe you could sacrifice some vertical space and put the label on its
own line either at the top or bottom of the box to avoid overlap.

Cheers,
Asumu

[Matthias Felleisen]

On Jun 12, 2012, at 11:58 PM, Asumu Takikawa wrote:

> On 2012-06-12 22:02:26 -0400, Neil Van Dyke wrote:
>> 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
>
> I really like this idea. +1.

+2

>
>> Of course, with this particular format, the definition could obscure
>> this label
>
> Maybe you could sacrifice some vertical space and put the label on its
> own line either at the top or bottom of the box to avoid overlap.

I think an occasional obscruification is just fine. People know where to look, and they will be able to read. An alternative is to make the label as large as the blue box itself.

[Eli Barzilay]

Two days ago, Neil Van Dyke wrote:
> 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

+1, and I'd like it if it were darker than the background instead of
the nearly invisible white.

> 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.

If it's subtle enough, it could be put below the text with no big
damage, IMO.

> 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.

+1 to this too. (I usually like to zoom the text so it fills the
screen, so the right margin is invisible anyway.)

--
((lambda (x) (x x)) (lambda (x) (x x))) Eli Barzilay:
http://barzilay.org/ Maze is Life!

[Matthew Flatt]

I've pushed this change to the git repo.