My own corner of monopam
claude-skills/mdx: document Fmt-vs-Format/Printf preference
Several recent README-fix commits hit the 'pp_x is _ Fmt.t, not
Format.printf-compatible' footgun. Add a rule to the MDX skill
saying: use Fmt.pr/Fmt.epr/Fmt.str, not Format.printf or
Printf.printf, when consuming a library's pp_-style printer.
Lists the typecheck failure mode and gives prefer/avoid examples.
+27
+27
ocaml-claude-skills/plugins/monopam/skills/mdx/SKILL.md
+27
ocaml-claude-skills/plugins/monopam/skills/mdx/SKILL.md
···
282
282
The wrapper is a defence against execution-time effects, not a
283
283
style. Misusing it makes documentation longer and harder to copy.
284
284
285
+
### Use `Fmt`, not `Format`/`Printf`, for formatted output
286
+
287
+
The repo standardises on the
288
+
{{:https://erratique.ch/software/fmt}fmt} library: `Fmt.pr` /
289
+
`Fmt.epr` for stdout/stderr, `Fmt.str` for strings. The `pp` values
290
+
exposed by libraries here are typed `_ Fmt.t`, so they compose
291
+
directly with `%a` only when the consumer is a `Fmt`-style
292
+
formatter — `Format.printf "%a"` doesn't typecheck against the
293
+
abstract `Fmt.t` arrow without a `cmi` from the formatter library.
294
+
295
+
```ocaml
296
+
(** Prefer:
297
+
{[
298
+
Fmt.pr "%a@." Lib.pp_value v
299
+
Fmt.epr "failed: %a@." Lib.pp_error e
300
+
]} *)
301
+
302
+
(** Avoid:
303
+
{[
304
+
Format.printf "%a@." Lib.pp_value v
305
+
Printf.printf "failed: %s\n" msg (* ad-hoc, no %a, no @. *)
306
+
]} *)
307
+
```
308
+
309
+
Mixing `Printf` with `pp_*` values is the most common rough edge:
310
+
the example reads naturally if you stay inside `Fmt`.
311
+
285
312
### Use real codecs and prebuilt instances, not stubs
286
313
287
314
Stub `dec` and `enc` (`fun _ -> S.Named []`, `fun _ -> ""`) ship