To write portable Scheme code it is necessary to know the language itself and the variations that exist in its implementations. The manpage format makes it possible to include much more detail than is usual for the Scheme reports.
This project aims to be a collection of manpages for the programming language Scheme. The goal is to include all of R6RS and R7RS.
Just started (2020-04-18).
All of R6RS and R7RS-small, but it can be extended to R7RS-large. The
documents listed under STANDARDS can include SRFIs, but features
that exist only as SRFIs are not in scope.
The manpages should be packaged for distribution at some point, but
for now it is enough to clone the repository and set the MANPATH
environment variable. It could be something like this shell snippet,
if you're in the cloned repository:
export MANPATH=$PWD:$(manpath -g)Then you should be able to use man car, etc. It is also possible to
write man man3/car.3scm.
Take a manpage from templates/ and fill it in! Remove any sections
that you feel are not needed. Do as many as you like and submit a PR
through GitHub. You can open an issue if you want to show others that
you're working on something.
Please use errata-corrected versions of R6RS and R7RS as your references.
Not everything has a template yet and some do not have accurate synopses. Another way to help is to develop tools that work with the documents, e.g. checking their structure, searching for missed pages, etc.
Sometimes it's appropriate to group together several procedures in the
same page. See man3/cdr.3scm for an example of how to
link to another page.
The manpages are written directly in roff format. The history of roff goes back to the early 1960s and today most systems use GNU groff as their roff typesettter.
The manpages use the man macro package. An alternative would have been mdoc, which is more modern, but it is much more geared towards documenting C functions. The tbl and eqn pre-processors can also be used if you need to create a table or an equation.
GNU groff can output text for the terminal, HTML, PDF and some other obscure formats. Pandoc can convert the manpages to many other formats.
Using another format as the definitive one would easily introduce translation errors. The roff format is also easy to parse later if we want to do some automatic maintenance. Keep it simple!