Jack Firth wrote on 11/10/2017 11:32 PM:
I have to redo my tools once more, and am sick of my current `(doc
...)` and `@doc` format, *and the resulting dependency on McFly.*
Could you elaborate on your experience with this?
A snippet of an example of embedded-docs source file for
"http://www.neilvandyke.org/racket/roomba/"; is at the bottom of this
file. See the dependency on `mcfly`, which simply provides a dummy
`doc` form so that the Racket compiler ignores everything in `doc`.
(I later added support for `at-exp` `@doc` syntax, which makes the
documentation easier to type and look at than in that painful-looking
example, and also visually differentiates it from code.)
The result works OK, but I have to write a new tool for other reasons,
with no time to do so, and I'd like to simplify this.
For a module with embedded docs I'd want to treat them the same as
tests: in a special submodule which results in "build-time"
dependencies instead of runtime dependencies.
Yes, I'm sympathetic to something like that.
I've thought of having `doc` transform to `(module+ doc`, and having
that then `provide` the data in some easily-computer-accessible form, as
well as generate the contemporary Scribble manuals.
One reason I've been shying away from that is that it's not only more
work (I don't really have time to write more tools, which distract from
my actual work), but then it looks like it wants to be a core Racket
thing, on something for which compromise would have to be found among
people from different schools of thought and goals (like a standards
effort; again, no time for this). And I'm still subconsciously always
figuring out the nuances to support the full-lifecycle story for my
industry practitioner's book, which is for people with needs and
thinking somewhat different than that of core Racket developers. So,
going with another quick-to-implement approach that lets me hit all the
nuances I can, without creating big core Racket work for everyone, and
seems the most likely way that I'll ever get all the nuances I want.
I suppose I could do this in a tractably quick&dirty way, without a big
production, if I'm willing to keep a dependency on another package --
either for a `#lang` variant of `racket/base`, or maybe a `require` from
`racket/base` and suboptimal syntax. But that's more work, people won't
like that dependency (I've had people fork my packages to remove the
dependency before), and using `racket/base` seems most friendly for
sharing reusable open source modules.
Which is why I'm currently leaning towards the presentable and
uncomplicated three-semicolon approach.
#lang racket/base
;; Copyright Neil Van Dyke. See file "info.rkt".
(require (for-syntax racket/base
syntax/parse)
racket/match
racket/system
mcfly)
(module+ test
(require overeasy))
(doc (require scribble/bnf
"roomba-doc-utils.rkt"))
(doc (section "Introduction")
(para "This package implements a "
(hyperlink "http://docs.racket-lang.org/";
"Racket")
" interface for controlling many "
(tech "models")
" of the "
(hyperlink "http://en.wikipedia.org/wiki/Roomba";
"iRobot Roomba")
" robot vacuum cleaner, and the "
(hyperlink "http://www.irobot.com/create";
"iRobot Create")
--
You received this message because you are subscribed to the Google Groups "Racket
Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
