TLDR: man pages support links, but man page readers neither display nor allow allow following them.
Frequent criticisms of man pages are “they don’t have links to each other” and “they don’t re-flow if I make the window narrower”. These are perfectly valid complains, but the reality is that man page do support these features: it’s the programs that we use to read man pages that don’t implement them.
The format
Man pages are stored in the mdoc(7) format and in the legacy man(7) format1. The actual format for these files isn’t the easiest to read in the world, but it’s definitely not worse than XML or JSON. mdoc has purely semantic markup. A portion of an mdoc man page looks something like the following2:
.Sh NAME
.Nm openrc
.Nd stops and starts services for the specified runlevel
.Sh SYNOPSIS
In this case .Sh, .Nm and .Nd are macros which mark the following text as
“section header”, “document name” and “document description” respectively. If
you try to manually read or edit these files you’ll need the to consult the
macro overview.
References (“links”)
Two macros are of particular interest:
.Xr: “Cross reference”: link to another manual page..Sx: Reference to another section in the same manual page.
Both of these can be rendered as links. In fact, when mdoc(7) pages are
converted into HTML, both of these macros are converted into actual links. Both
of the above linked manual pages include examples of this. The .Sh (section
header) macro renders as an anchor, so links can point to it directly.
Ironically, the documentation for mdoc(7) renders links when displayed as HTML on a browser, but not when displayed in a terminal via the man(1) command.
Conclusion
We need better man page readers. Ones that let us follow references as links.
Currently man(1) formats a man pages and pipes it to less(1). We can’t easily add supports for links here: we need a pager which understands man pages natively.
While we’re at it, we could also re-flow text when the terminal window is made narrower.
When I say legacy here, I really mean it. Documentation for man(7) indicates that it was used from 1979 to 1989, and mdoc(7) first appeared in the early 1990s, in 4.4BSD. ↩︎
This sample was copy-pasted from OpenRC’s man pages. See the repository for a full example and licence details. ↩︎