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: ""; (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
;;;   for details.}

(require (for-syntax racket/base)

;;; @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[""]{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 
For more options, visit

Reply via email to