present: document shebang and txtar for .play

oxzi · oxzi · commit 10dcaf4242d5 · 2025-08-13T13:30:03.000+02:00
The "play" command for present does not only support Go code, which was
implicitly documented, but also generic scripts identified by a shebang
or txtar-encoded input - enabling Go modules.

The locally used implementation for "play" resides in
./playground/socket/socket.go. Mostly undocumented, this code first
checks the input for a shebang and, if present, executes input with the
shebang interpreter. This code also allows txtar-encoded input, which
can be used to "play" Go modules, including external dependencies.

Documenting the actual behavior helps users to understand and use the
software better. Personally, I initially wanted to patch Go module
support in present, just to find out everything is already there - just
undocumented.
diff --git a/present/doc.go b/present/doc.go
@@ -287,6 +287,24 @@ on the displayed source so the program can be run from the browser.
 Although only the selected text is shown, all the source is included
 in the HTML output so it can be presented to the compiler.
 
+By default, "play" compiles and executes Go code. But it is also
+possible to execute generic scripts if they start with a shebang.
+
+When the Go code imports packages, they are expected to be present in
+the GOPATH.
+
+However, Go modules are also possible for each "play" instruction if the
+input is txtar-encoded. See
+
+	https://pkg.go.dev/golang.org/x/tools/txtar
+
+for a format description. The txtar input must contain a valid go.mod
+and go.sum file. A minimal Go module project of main.go, go.mod and
+go.sum can be txtar'ed like the following in a POSIX Shell:
+
+	$ cp main.go demo.txtar
+	$ for f in go.{mod,sum}; do echo "-- $f --"; cat "$f"; done >> demo.txtar
+
 link:
 
 Create a hyperlink. The syntax is 1 or 2 space-separated arguments.
