[racket-dev] conditional scribble documents

From: Eli Barzilay (eli at barzilay.org)
Date: Fri May 4 18:30:43 EDT 2012

20 minutes ago, Danny Yoo wrote:
>     ... for example, why not set up files that set some parameter and then
>     run the program.  You said that you want a `++load my-module.rkt' --
>     why not change "my-module.rkt" -> "my-module.scrbl", and just render
>     it?
> I like this.  But I don't want the "configuration" scribble file to
> itself generate documentation, but only set up the
> parameterizations.  The documentation in
> http://docs.racket-lang.org/scribble/running.html makes it sound
> like it will generate documentation for each scribble file I feed
> into it.  Isn't that the case?

I'm talking about something like this:

  #lang racket/base
  (require "main.scrbl")
  (provide doc)

which you can run through scribble and get the usual output.  (And
then change the code to use `dynamic-require' so you can change the

> The environmental variable approach would work, too... and probably
> without needing significant hacking.  I can use getenv [...]

(Yeah, IMO this is just as good as command-line flags.)

> Either way, once I have something I can read, then I can use
> traverse-elements and then be in good shape, I think.

I think that in most cases you won't need that -- and it will also
save you on the additional configuration file.  Another point that
makes it easy is that scribble ignores void values, so something like
the below works in the way you'd want, which you can run with

  STUDENT=yes scribble --pdf my-file.scrbl

#lang scribble/manual

   (require scribble/decode)
   (define student? (getenv "STUDENT"))
   (define-syntax-rule @for-student[text ...]
     (when student? @splice{@list[text ...]})))

@title{Some Title (@(if student? "student" "teacher") edition)}

  @section{About the student edition}
  This version of the manual is formatted for students}


Blah blah blah.

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

Posted on the dev mailing list.