Although this answer isn't as elegant as I'd like, it works.
Basically I think you're talking about conditional compilation. In C you'd use a macro for this. In Racket let's use a macro, too (a macro which is just as brain-dead simple as a C macro).
Also we need a macro because Scribble's include-section
is syntax (not a function) and must appear at the top-level. As a result, you can't use it inside of an if
or when
.
Given that:
define.rkt
#lang racket/base
(provide (all-defined-out))
;; Macros to conditionally include literal text.
;; Each of these should return `text`,
;; or (void) for nothing
(define-syntax-rule (when-alpha text)
text)
(define-syntax-rule (when-beta text)
(void))
;; Macros to conditionally include a .scrbl file
;; Each of these should return include-section,
;; or (void) for nothing
(require scribble/base) ;for include-section
(define-syntax-rule (when-alpha/include mod-path)
(include-section mod-path))
(define-syntax-rule (when-beta/include mod-path)
(void) #;(include-section mod-path))
Currently, this is set to show things for "alpha" but omit them for "beta". Unfortunately there's not a simple #t
or #f
to toggle. You need to edit the body of each one a bit more than that, as explained in the comments.
manual.scrbl example file conditionally including text and another file
#lang scribble/base
@(require "defines.rkt")
@title{Getting Started}
@when-alpha{@para{Text for alpha}}
@(when-beta/include "includee.scrbl")
includee.scrbl example file being conditionally included
#lang scribble/base
@title{BETA TEXT}
I am text for beta version.
What I don't love about this solution is that you have to create/change a pair of macros for each condition -- one for including literal text, and another for include-section
-ing a .scrbl file.