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.

Reply via email to