Dear Neil,
I can’t respond to point 1; I don’t have sufficient knowledge of the options.
However, I would very much like to endorse the idea behind point 2.
Kind regards,
Tim
> On 27 Jan 2018, at 12:26, 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.
Tim Jervis
http://timjervis.com/ <http://timjervis.com/>
--
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.
