Mike Fischer writes: > So it should be possible to automatically replace these with real links? > I'm not sure what would happen if the man(7) format files where > modified (on the fly) to include .Xr syntax. But at the very least the > mandoc(1) -T html command could be (optionally?) modified to change > these to real links?
Attempting to infer semantic information (links) from a manpage written in an inherently non-semantic format like man(7) has poor prospects. A typical example is yacc(1); when the page is not written in mdoc(7) (as is often the case on other systems), HTML conversions of the page often create false links to LR(1) and LALR(1). Maybe the specific regex in your mail won't pick those up, but it's just as likely that you'll try to broaden the regex more and more to pick up other cross-references that were written in some other pattern. If you're interested specifically in improving markup quality of OpenBSD manuals not written in mdoc(7), then there are better targets. For example, many X11 manpages are now written in DocBook and converted to poor-quality man(7). They could be converted to better quality mdoc(7), if docbook2mdoc (a mandoc subproject, available in packages) were improved. That would improve their appearance on man.openbsd.org as well as their usefulness with mandoc's semantic search capabilities. > I have implemented this on a private web page for showing local man > pages of the OpenBSD system and it seems to work fine. mandoc -Thtml is in very (very) wide use. I think the change you described is likely to result in worse markup in some cases. It would be better to encourage developers to put more effort into creating high-quality documentation as we do in OpenBSD. And one part of that involves picking the right file format to write the documentation in. -- Anthony J. Bentley
