[racket] scribble racketinput and racketresult

From: Neil Van Dyke (neil at neilvandyke.org)
Date: Tue May 8 10:45:18 EDT 2012

In Scribble'd docs, what is the right, conventional way to show that 
expression A produces value(s) B, but without using Scribble's 
"interaction" form?

The closest I've gotten is this:

(racketinput (+ 1 2)
   #,(racketresult 3))

The problem with this is that the result is inset by the "> " prompt, 
which it is not in existing Scribble manuals that use the 
"scribble/eval" bindings.

I don't want to always use "scribble/eval", for a few reasons: (1) 
sometimes I need to document evaluation results that cannot be evaluated 
at documentation rendering time; (2) sometimes I want to put italicized 
placeholders in the output, such as for things that can vary from run to 
run; (3) I sometimes use the embedded documentation source in the Racket 
source code as reminders of what the code is supposed to do, without 
having to render documentation and look at it; and (4) I am horrified by 
the possibility of pretty documentation authoritatively showing an 
expression evaluating to something other than what I had intended.  
Regarding #4, that could be mitigated in some cases by having the 
"scribble/eval" stuff double as regression tests, but that's not 
possible in all cases.

Neil V.


Posted on the users mailing list.