schemedoc/manpages

Unix manual pages for R6RS and R7RS

manpages's Issues

Handle weird characters in page names

We have some Scheme procedures that contain a /, like call/cc, but / can't be used in filenames on Unix. So these pages are currently missing. We could use a convention like call_cc.

Distro packaging

A Nix package is in the works: https://repology.org/project/scheme-manpages/versions

Change from 3scheme to 3scm?

Some versions of the Unix man program (at least the version that ships with MacOS) do not recognize manual subsections longer than three characters.

The program thinks man 3sch exit refers to the page exit in a section starting with 3sch whereas if you type man 3scheme exit it thinks you are asking for two different manual pages, first 3scheme and then exit, both from any section of the manual.

For compatibility with these programs, should we change the subsection from 3scheme and 7scheme to 3scm and 7scm?

Publish under scheme.org

Should we publish HTML versions of the manpages under https://doc.scheme.org/? Mandoc or Pandoc could be a resonable converter.

Add implementation notes?

Should we add portability notes to the manpages about how different Scheme implementations handle those things? For example, string representation used in each implementation and things like that.

Sectionless URLs and disambiguation pages

The Common Lisp HyperSpec has disambiguation pages like this: http://www.lispworks.com/documentation/HyperSpec/Body/a_list.htm

Please select which reference to LIST you intended:

• Function
• System Class
• Glossary Entry

We could have URLs like https://man.scheme.org/values/ go to a disambiguation page like that.

Or we could do that the Unix man program does, and have a precedence order for sections. If a page name is found in multiple sections, and no section is specified, the page in the highest-precedence section is visited.

Linkify all the things

The current manpages link to each other like this:

.BR raise (3scheme),
.BR assert (7scheme),
.BR guard (7scheme)

Is there a purpose-built linking directive like the .Xr (cross-reference) in mdoc macros? If there is, the mandoc converter has good support for turning them into HTML links.

Sections and URL layout

The current manpage sections are 3scheme and 7scheme.

Does this mean our URLs should be
https://man.scheme.org/3scheme/values/
instead of
https://man.scheme.org/3/values/?

I.e. should 3 and 3scheme be treated as non-interchangeable?

Use unroff to generate HTML

I managed to resurrect unroff, which is a Scheme-scriptable troff parser. It runs using the version of Elk Scheme that ships in Debian (apt install elk) and produced pretty good results with little work.

I think we should ditch our patched copy of the C program man2html and patch unroff instead. It's faster and more fun, produces better output, and we'd be improving Scheme at the same time.