At Fri, 18 Dec 2015 17:27:21 -0800, Alexis King wrote: > > A related issue is that examples in the documentation sometimes > > fail in a way that indicates a bug. By having that failure be a > > documentation-build failure, instead of rendered as an error > > message in the documentation, we can avoid some errors in a > > release. Matthew will add a replacement for `examples` where forms > > that are intended to be rendered as errors must be explicitly > > marked as such, while other errors trigger a document failure. > > This, along with a fixed eval:check, is a wonderful change. Documentation > examples that also serve as an ad-hoc test suite is a pretty cool idea. I’m > very excited to be able to use these. > > There is a problem, though: I can’t use them without dropping support > for older Racket versions because these are entirely new forms. This > was something I was thinking about lately: having monolithic > “releases” makes it impossible to backport changes to older Racket > versions. For example, the new scribble/example(s) module seems like > something that would work with lots of Racket versions were it a > package, but since it’s part of the core, scribble-lib will be locked > to older versions on old releases. > > Am I wrong about this? Maybe it would work if I explicitly depend on a newer > scribble-lib version? I think I’m a little unclear about that.
Although the current "scribble-lib" does install in v6.3 (using `raco pkg update --catalog http://pkgs.racket-lang.org scribble-lib`), you probably don't want to create a package that can only be used in older versions by first upgrading a main-distribution package. One alternative is to create a "scribble-example-lib" package and register it at pkgs.racket-lang.org with different implementations for different Racket versions: as a copy of `scribble/example` for version 6.3 and earlier, and as a package that just implies "scribble-lib" for post-6.3 versions. As another alternative, we could move `scribble/example` out of "scribble-lib" and into a "scribble-example-lib" package (and either make "scribble-lib" imply the new package or adjust our handful of uses to depend on "scribble-example-lib"). Then, your package could require "scribble-example-lib", and we could make sure that "scribble-example-lib" works in older versions of Racket. The second alternative requires a little extra work. The `scribble/example` library is currently implemented in terms of an improved `scribble/eval`. So, the implementation has to be shuffled a little to put the new `scribble/eval` as some private library in "scribble-example-lib", and then `scribble/eval` in the new "scribble-lib" can re-export that other library (while `scribble/eval` for previous releases remains unimproved). Of course, "scribble-example-lib" would become a part of the main distribution in the next release, the same as "scribble-lib", since main-distribution documentation will rely on it. If `scribble/example` needs to be improved later, then we run into all the same problems again. Also, we'll have to deal with the extra "scribble-example-lib" layer forever. I lean toward the first alternative, since it means "scribble-example-lib" will mostly move out of the way after the next release. I don't have a strong objection to the second alternative, though. -- You received this message because you are subscribed to the Google Groups "Racket Developers" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/racket-dev/56755d9e.c900620a.ae81b.ffff96ccSMTPIN_ADDED_MISSING%40gmr-mx.google.com. For more options, visit https://groups.google.com/d/optout.
