Any comments on the following?
Since the Racket (PLT Scheme) version 1xx days, I have been doing
embedded documentation in reusable Racket (and Scheme) modules, and have
done a few iteration of tools for this. I have to redo my tools once
more, and am sick of my current `(doc ...)` and `@doc` format, and the
resulting dependency on McFly.
For the next iteration, I'm coming back around to my ancient
three-semicolon-Texinfo-based format, only using Scribble instead of
Texinfo (though Markdown was tempting). Like earlier, the programmer
would usually only edit only one file per package, and the extra files
like "info.rkt" and ".scrbl" would be generated automatically.
The questions I'm considering right now:
1. For encoded metadata, like the things traditionally found in
"info.rkt" -- as well as for license/legal information, known issues,
release history, and more detailed/flexible information about package
dependencies -- should it use three-semicolon pseudo-Scribble forms,
like in the example below, or should it do `(module+ info (define ...)
(define ...) ...)`, with most of the small metadata in a `module+` at
the top of the file, and probably the known issues and release history
at the end of the file? (A reason for the `info` submodule is that,
although my tool has to parse all the three-semicolon stuff anyway, the
info submodule is much better for other tools to get at the info,
including, perhaps, someday, everyone supporting lightweight
single-source-file modules for reusable Racket packages.)
2. Do we want to require the programmer to always repeat themselves
things like procedure names and type info, like for `make-sandwich` in
the example at the end of this file? If not, do we want to also support
something like make special pseudo-Scribble forms like `Procedure` that
will be converted to `defproc` and populated with info from the code,
like in `make-panini`? Or do we want to also support something like
Lisp docstrings, only in full Scribble, like in `make-wrap`?
Below is an example file. You can also see a screenshot of what it
looks like with some very simple editor support, to help visually
differentiate "code" from docs/metadata (without getting philosophical
any distinction), at:
"http://www.neilvandyke.org/temporary/20171110-racket-example.png"; (The
syntax coloring in that screenshot is for my old Texinfo format, which
happened to also have "@section"; more things would be colored with
proper support for whatever the new format.)
#lang racket/base
;;; @Package{pasture}
;;; @Subtitle{Parallel Copying On Write}
;;; @Version{1.0}
;;; @Authors{John Smith}
;;; @Licenses{LGPLv3}
;;; @LegalNotices{
;;; Pasture is Copyright 2025, Smithco, LLC, All rights reserved.
;;; This program is Free Software; you can redistribute it and/or
;;; modify it under the terms of the GNU Lesser General Public License
;;; as published by the Free Software Foundation; either version 3 of
;;; the License, or (at your option) any later version. This program
;;; is distributed in the hope that it will be useful, but without any
;;; warranty; without even the implied warranty of merchantability or
;;; fitness for a particular purpose. See http://www.gnu.org/licenses/
;;; for details.}
(require (for-syntax racket/base)
foo
bar)
;;; @section{Introduction}
;;;
;;; The Pasture package for Racket supports multiple COWs in parallel.
;;;
;;; It also involves sandwiches.
;;; @section{Sandwiches}
;;;
;;; A sandwich is a food typically consisting of vegetables, sliced
;;; cheese or meat, placed on or between slices of bread, or more
;;; generally any dish wherein two or more pieces of bread serve as a
;;; container or wrapper for another food type. The sandwich began as a
;;; portable finger food in the Western world, though over time it has
;;; become prevalent worldwide.
;;; @defproc[(make-sandwich (ingredients (listof ingredient?)))
;;; sandwich?]{`
;;; Returns a sandwich given the right ingredients.
;;; }
(define/provide (make-sandwich ingredients)
(vector 'sandwich
(cons 'seitan ingredients)))
;;; @Procedure{
;;; Returns a panini given the right ingredients.
;;; }
(define/provide/contract make-panini
(-> (ingredients (listof ingredient?)) panini?)
(vector 'panini
(cons 'portabello ingredients)))
(define/p/c/d make-wrap
(-> (ingredients (listof ingredient?)) wrap?)
@doc{Returns a wrap, given the right ingredients.}
(vector 'wrap
(cons 'sprouts ingredients)))
;;; @section{Anti-Tipping}
;;; Once activated, Pasture provides the following anti-tipping
;;; countermeasures automatically:
;;;
;;; @itemize{
;;; ...
;;; }
...
;;; @KnownIssues{
;;;
;;; @Issue{Needs support for pies.}
;;;
;;; @Issue[]{}
;;; }
;;; @History{
;;;
;;; @Version["1.0" "2025-12-25"]{
;;;
;;; Added beeping.
;;;
;;; @para{Fixed @hyperlink["http://example.com/"]{blah blah}
;;; (Thanks to Mr. T for reporting.)}
;;;
;;; @Version["0.9" "2017-12-24"]{
;;;
;;; "Limited release, for feedback from A-Team.}}
--
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.
![http://www.neilvandyke.org/temporary/20171110-racket-example.png"](http://www.neilvandyke.org/temporary/20171110-racket-example.png"){kind=link}