search

schemedoc / manpages

Unix manual pages for R6RS and R7RS
https://man.scheme.org
Other
16 stars 2 forks source link

Linkify all the things #5

Closed lassik closed 1 year ago

lassik commented 3 years ago

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.

weinholt commented 3 years ago

There is indeed .Xr in mdoc, but the pages are written with the man macros (see groff_man(7)). The mdoc package is way too specialized to UNIX and just gets in the way.

The existing tools that work with man pages should understand .BR raise (3scheme), I hope. Of course, most of the pages incorrectly contain things like .BR cons (3), but that can be fixed.

lassik commented 3 years ago

Right. Can you try installing mandoc (it's a small, fast program available from apt-get and others) and making a test page to see if you can get its HTML converter to recognize a link written some way? The command I use to convert to HTML is mandoc -T html -O 'man=../%S/%N/' example.3scheme >example.html. The man= causes it to make links using the given URL template.

If you know of another man->html converter that can linkify man macros, that would do fine as well. mandoc is nice in that it's fast and trivial to install.

lassik commented 3 years ago

The current mandoc output is <b>raise</b>(3scheme), <b>assert</b>(7scheme), <b>guard</b>(7scheme). I guess we could parse the HTML into SXML and match (b "<ascii>") "(<digit><alnum>*)" in Scheme.

lassik commented 3 years ago

Can you try installing mandoc

Nevermind, I read man_html.c and mandoc can't linkify cross-references in man macros.

lassik commented 1 year ago

man2html and unroff can make page-to-page links.