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.
____________________
Racket Users list:
http://lists.racket-lang.org/users
