`makewhatis` on macOS fails to process Lix man pages #515

New issue

Open

opened 2024-09-10 23:35:26 +00:00 by rbt · 2 comments

rbt commented

2024-09-10 23:35:26 +00:00

Owner

The Lix man pages look like this:

.SH
Name

They need to look like this:

.SH Name

Way more details than you want

So the Fish shell's default completions for man uses a wrapper around apropos to get the names of available man pages. This wrapper uses /usr/libexec/makewhatis to build a cache of the available man pages and their descriptions.

On macOS, /usr/libexec/makewhatis is a completely different program than the makewhatis binary you get from building Nixpkgs' mandoc, although they probably have a common lineage. You can check the macOS makewhatis.c source code here.

Man page excerpts

On macOS:

SYNOPSIS
makewhatis [-a] [-i column] [-n name] [-o file] [-v] [-L] [directories ...]
HISTORY
The makewhatis command appeared in FreeBSD 2.1.

AUTHORS
The makewhatis program was originally written in Perl and was contributed by Wolfram Schneider. The current version of makewhatis was rewritten in C by John Rochester.

From Nixpkgs:

SYNOPSIS
makewhatis [-aDnpQ] [-T utf8] [-C file]
makewhatis [-aDnpQ] [-T utf8] dir ...
makewhatis [-DnpQ] [-T utf8] -d dir [file ...]
makewhatis [-Dnp] [-T utf8] -u dir [file ...]
makewhatis [-DQ] -t file ...
HISTORY
A makewhatis utility first appeared in 2BSD. It was rewritten in perl(1) for OpenBSD 2.7 and in C for OpenBSD 5.6.
The dir argument first appeared in NetBSD 1.0; the options -dpt in OpenBSD 2.7; the option -u in OpenBSD 3.4; and the options -aCDnQT in OpenBSD 5.6.

AUTHORS
Bill Joy wrote the original BSD makewhatis in February 1979, Marc Espie started the Perl version in 2000, and the current version of makewhatis was written by Kristaps Dzonsons kristaps@bsd.lv and Ingo Schwarze schwarze@openbsd.org.

Anyways, when you run this program on macOS, it chokes on the Lix man pages, and apparently if it can't parse a description it doesn't bother writing any indication that the command exists at all:

$ /usr/libexec/makewhatis -v -o /tmp/whatis outputs/out/share/man | head
man directory outputs/out/share/man
  outputs/out/share/man/man5
        reading outputs/out/share/man/man5/nix.conf.5
        ignoring junk description ""
        reading outputs/out/share/man/man5/nix-profiles.5
        ignoring junk description ""

Long story short it turns out that makewhatis needs .SH Name on one line.

The Lix man pages look like this: ``` .SH Name ``` They need to look like this: ``` .SH Name ``` # Way more details than you want So the Fish shell's [default completions for `man`](https://github.com/fish-shell/fish-shell/blob/a979b6341d7fc4c466b3992f25da3209e0808aaa/share/functions/__fish_complete_man.fish#L34) uses [a wrapper around `apropos`](https://github.com/fish-shell/fish-shell/blob/a979b6341d7fc4c466b3992f25da3209e0808aaa/share/functions/__fish_apropos.fish) to get the names of available man pages. [This wrapper uses `/usr/libexec/makewhatis`](https://github.com/fish-shell/fish-shell/blob/a979b6341d7fc4c466b3992f25da3209e0808aaa/share/functions/__fish_apropos.fish#L43) to build a cache of the available `man` pages and their descriptions. On macOS, `/usr/libexec/makewhatis` is a completely different program than the `makewhatis` binary you get from building Nixpkgs' `mandoc`, although they probably have a common lineage. You can check [the macOS `makewhatis.c` source code here.](https://opensource.apple.com/source/doc_cmds/doc_cmds-53.100.1/makewhatis/makewhatis.c.auto.html) <details> <summary>Man page excerpts</summary> On macOS: > **SYNOPSIS** > ``` > makewhatis [-a] [-i column] [-n name] [-o file] [-v] [-L] [directories ...] > ``` > > **HISTORY** > The makewhatis command appeared in FreeBSD 2.1. > > **AUTHORS** > The `makewhatis` program was originally written in Perl and was contributed by Wolfram Schneider. The current version of `makewhatis` was rewritten in C by John Rochester. From Nixpkgs: > **SYNOPSIS** > ``` > makewhatis [-aDnpQ] [-T utf8] [-C file] > makewhatis [-aDnpQ] [-T utf8] dir ... > makewhatis [-DnpQ] [-T utf8] -d dir [file ...] > makewhatis [-Dnp] [-T utf8] -u dir [file ...] > makewhatis [-DQ] -t file ... > ``` > > **HISTORY** > A `makewhatis` utility first appeared in 2BSD. It was rewritten in `perl(1)` for OpenBSD 2.7 and in C for OpenBSD 5.6. > The `dir` argument first appeared in NetBSD 1.0; the options `-dpt` in OpenBSD 2.7; the option `-u` in OpenBSD 3.4; and the options `-aCDnQT` in OpenBSD 5.6. > > **AUTHORS** > Bill Joy wrote the original BSD `makewhatis` in February 1979, Marc Espie started the Perl version in 2000, and the current version of makewhatis was written by Kristaps Dzonsons <kristaps@bsd.lv> and Ingo Schwarze <schwarze@openbsd.org>. </details> Anyways, when you run this program on macOS, it chokes on the Lix man pages, and apparently if it can't parse a description it doesn't bother writing any indication that the command exists at all: ``` $ /usr/libexec/makewhatis -v -o /tmp/whatis outputs/out/share/man | head man directory outputs/out/share/man outputs/out/share/man/man5 reading outputs/out/share/man/man5/nix.conf.5 ignoring junk description "" reading outputs/out/share/man/man5/nix-profiles.5 ignoring junk description "" ``` Long story short it turns out that `makewhatis` _needs_ `.SH Name` on one line. Related: https://github.com/fish-shell/fish-shell/pull/10713