Rewrite manual page in mdoc(7)

[Alhadis]

This PR refactors docs/mold.1 to use mdoc(7) instead of man(7). Mdoc is a modern alternative to the historic man macro-set, which abstracts presentational details from higher-level markup.

Here's a before-and-after comparison to show you how the page will look when formatted for the terminal.

[rui314]

I'm pretty much noob when it comes to man pages. I just wrote this man page by copy-pasting macros from other manuals. So, I"m sure this is a dumb question, but what is the point of writing a man page with the mandoc style instead of the current style?

Semantic markup may be a good thing, but does this make a visible difference?

Is this compatible on all Unix-like platforms, i.e. all Linux distros, BSDs and macOS?

What about other projects? Do other project write their man pages in mandoc rather than the GNU-style these days?

[Alhadis]

Is this compatible on all Unix-like platforms, i.e. all Linux distros, BSDs and macOS?

Yes, and it has been for the past 3 decades. I know I said mdoc was "modern", but in the context of a 50-year old typesetting system, practically anything written post-1990 is "modern" in comparison (the original man(7) macros were written in the mid-70s).

So, I"m sure this is a dumb question, but what is the point of writing a man page with the mandoc style instead of the current style?

BSD's man(1) and apropos(1) implementations use semantically-tagged data to perform advanced lookup and indexing queries based on page content; e.g., searching for man pages that contain pathnames ending in .so that also reference an environment variable named LD_PRELOAD:

$ apropos 'Pa~\.so$' -a Ev=LD_PRELOAD

Unlike a conventional search, .so is guaranteed only to match strings marked up with .Pa. There's also the added benefits of improved hyperlinking: I can link directly to the definition of .Ev inside mdoc(7), for example.

None of these features are possible with purely presentational markup, which only concerns itself with the appearance of text (bold, underlined, indent, etc).

Semantic markup may be a good thing, but does this make a visible difference?

In the terminal, the improvements to formatting are marginal, but they spring to life when rendered in any other format (HTML, PDF, PostScript, etc). Compare:

Unstyled HTML output:

• Using mdoc(7)
• Using man(7)

What about other projects? Do other project write their man pages in mandoc rather than the GNU-style these days?

BSD-derived systems (OpenBSD, FreeBSD, NetBSD, DragonflyBSD, etc) all use mdoc(7) extensively, whereas GNU/Linux gravitate toward the older man(7) package. The reason for this is primarily historical: at the time mdoc was first written, the man macros were already firmly-entrenched in the Unix ecosystem. It was around this time that Linux appeared on the scene and really took off… authors continued to write man pages in the format they were most used to.

Today, the majority of manual pages that use man(7) are either

1. generated from sloppy conversion software (DocBook is an infamous example),
2. copy+pasted piecemeal from other man pages (as you did),
3. written by maintainers of official GNU projects¹
4. written by casual man page authors who learned through osmosis and/or points 1. or 2. above; these authors often feel little pressure or incentive to learn more about Roff than is necessary to maintain a basic manual page for a project.

Node.js used to be an example of case #‌4 until I modernised it for them (see nodejs/node#18559).

Footnotes

1. "For some reason, the FSF insists on using the legacy man(7) macros. I have no idea why" ↩

[rui314]

It looks like only 66 man pages among 3917 in my /usr/share/man/man1/ are written in the mdoc format, so it's definitely a minority. But I'm fine with mdoc because ld.lld's man page is also written in mdoc. I wrote part of it, but I wasn't aware of what that man page was written in.

I'll merge this commit.

One question: why is line continuation preferred over hard line break?

[Alhadis]

It looks like only 66 man pages among 3917 in my /usr/share/man/man1/ are written in the mdoc format, so it's definitely a minority.

Perhaps on your system, which I'm assuming is some flavour of GNU/Linux? On BSD-derived systems, mdoc is much more prevalent.

Moreover, you only scanned the contents of your /usr/share/man/man1/ directory. 😉 Of the 9 different /usr/share/man/man? directories, man1 — the section dedicated to userland commands — is the one most likely to contain a mixture of GNU and BSD-licensed programs (meaning the ratio between man/mdoc can vary widely).

One question: why is line continuation preferred over hard line break?

When a sentence ends in an appropriate punctuation character like . , ) ? !, the formatter can optimise the spacing of surrounding text, improving the readability of justified or filled paragraphs. A hard line-break is interpreted as the end of a sentence which is missing the terminating full-stop (or comma, question mark, etc).

This tends to be much more noticeable in PDF and PostScript output, but it's also relevant in terminal output as well (particularly when densely-packaged blocks of text are involved).