Re: New project: Scheme manpages
Lassi Kortela 19 Apr 2020 07:29 UTC
Thanks for the initiative. Very good. I like the layout of the manpages
- it's easy to comprehend at a glance. Also great to have all standards
on the same page (no pun intended).
My only concern is that it would be useful to have the same
documentation in other formats as well (Emacs info files, Scheme REPL,
HTML, etc.) To that end, it would be nice to be able to share most of
the prose among the formats. You propose using Pandoc or a similar
converter, but in my experience there tend to be little details in
formatting and layout where it's difficult to get a "native" look and
feel using a generic converter.
Would it be possible to write the source documentation as S-expressions
(which src/make-templates.scm already has some of)? Those could easily
use conditional expressions for any output-format-specific stuff. It
would also be easy to extract information programmatically from S-exprs.
For example, something along these lines:
(name "car, cdr"
"the car or cdr field of a pair (head and tail)")
(imports
(for "R6RS" (rnrs))
(for "R6RS" (rnrs base))
(for "R7RS" (scheme base)))
(synopsis
(car <pair>)
(cdr <pair>))
(description
(p "Returns the contents of the car or cdr field of a pair.")
(p "These procedures can also be used with lists, which in Scheme are"
"linked lists of pairs."
"The " (proc car) " procedure returns the head of a list."
"The " (proc cdr) " procedure returns the tail of a list."))
(return-values
"Returns the contents of the car or cdr field of " (var pair))
The details don't really matter, but I would root for the general approach.