Neil,

If I understand the implication: how is turbo-racket practically different
from scribble/lp2? —Just that the code is not put in the document?

Deren

On Sat, Jan 27, 2018 at 7:26 AM, Neil Van Dyke <n...@neilvandyke.org> wrote:

> 1. Do we foresee using srcdoc for new work in the future, and is it
> suitable as part of a backend for other in-source documentation?
>
> 2. What do people think of writing reusable modules approximately like the
> example below?  Is that something you'd want to do?
>
> (The basic idea is that you usually have one source file per module, which
> is self-contained, with polished and up-to-date documentation and unit
> tests and such, and is generally written and maintained as if it is reused
> or could be reused as its own package at any time. All this, in a fairly
> "lightweight" form, although we acknowledge that the below example is a big
> bureucratic load for two one-line procedures, but maybe it is practical for
> most real-world modules.)
>
> (For this example, I used capitalized names, to avoid confusing with
> familiar names, but some other names that weren't capitalized might also
> work.  Note that some forms are dual-purpose; for example, `Proc` turns
> into something like a Scribble `defproc` and a Racket code `define`,
> `provide`, and a contract somewhere.  Note that I'm intentionally putting
> `KnownIssues` and `History` into the source file, in a lightweight and
> self-contained kind of way, but those forms could be optional, for
> people/projects that prefer to use separate issue-tracking and release
> notes.  Also note that, if `Package` weren't present here, you could
> imagine this module being part of a multi-module package, including
> documentation that is incorporated by reference into a bigger document,
> but, by default, we want to encourage lightweight reusable modules.}
>
> ---- BEGIN ----
>
> #lang turbo-racket
>
> @Package[
>     @Name{foo}
>     @Version{1.1}
>     @Web{http://www.example.com/foo/}
>     @Authors{Jane Doe}
>     @Legal{Copyright 2025 Jane Doe. You may blah blah blah
>            blah blah blah.}]
>
> (Require (bunny :version "1.2+")
>          (puppy :url "https://git.example.com/release/2.0/puppy.rkt";
>                 :sha256 "347ab429830..."))
>
> @Section{Introduction}
>
> @Doc{This package provides a @racket{foo} and @racket{bar},
>      for all your fooing and anti-fooing needs.}
>
> @Doc{For example, you could do:
>
>      ...
>
>      and it would totally work, dude.}
>
> @Section{Main Interface}
>
> @Doc{The interface is just two procedures.}
>
> (Proc (foo (x real?) (y real))
>              real?
>   @Doc{This returns a foo of @var{x} and @var{y}.
>        It's really quite neat.}
>   (* x y x y x y))
>
> (Tests (test (foo 1 2) 666)
>        (test (foo 3 4) 42))
>
> (Proc (bar (x real?) (y real))
>              real?
>   @Doc{We don't know why anyone would want to do this,
>        but the customer is always right.}
>   (+ x y x y x y))
>
> (Tests (test (bar 0 0) 0)
>        (test (bar 1999 1999) 0))
>
> @Section{Conveniences}
>
> ...
>
> @Section{Quantum Theory}
>
> @Doc{Perhaps a discussion is in order.
>
>      ...}
>
> @KnownIssues[
>
>     @item{Not everyone yet fooifies.}
>
>     @item{Fix intermittent explosions.}]}
>
> @History[
>
>     @Release["1.1" "2025-12-25"]{
>         @itemize[
>             @item{Reversed behavior of @racket{foo} and @racket{bar}.}
>             @item{Documented explosion issue.}]}
>
>     @Release["1.0" "2025-12-24"]{
>         This was a good initial release.  We got out there,
>         and gave 110%.}]}
>
> ---- END ----
>
> --
> 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.
>

-- 
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