BREAKING CHANGE: remove `man` support

[lukekarrys]

man support is currently buggy/broken and adds an undue maintenance burden for the usage imo. See a list of current/prior issues.

npm/cli#2914
npm/cli#4276
npm/cli#4611
npm/cli#780
npm/cli#3478
npm/cli#4026

Is npm 9 a good time to drop man pages altogether?

[ljharb]

man pages are pretty nice, and --help output is currently woefully unhelpful. For example, just yesterday I tried npm search --help and it told me to look at npm help search (which are manpages) which actually has the info i needed.

[lukekarrys]

Thanks for the feedback, I opened this issue to gather other perspectives too. I would also like to see the output from --help increased to be more like the gh cli which includes the full documentation page for each command and subcommand, but that's not directly related to this.

I wasn't thinking of fully dropping npm help as a command, just the expectation that we support anything outside of our internal calls to man. I don't have a lot of experience with supporting man pages so it's possible I'm describing something highly unidiomatic.

Another issue I found with the help command is that viewer=browser doesn't seem to search the same way. eg npm help npmrc opens the man page for npmrc but npm help npmrc viewer=browser opens a list of top hits for npmrc.

The last thing I'll add is that we are currently depending on an unsupported package that fails npm audit for generating our man pages. We only run this on trusted input but it is still annoying to be unable to get npm audit passing.

[d0sboots]

As the drive-by author of a patch for one of those bugs, I totally get your desire to kill that part of the codebase. :)

As someone with a system package-manager installed npm (dunno how common that is, but my impression is it's less common), I wouldn't overly mind if man npm-install didn't work, as long as npm help install still looked/functioned mostly the same. You'd probably still want to ship a man page for npm itself, but that's a different matter (and it doesn't have to be dynamically accessible from npm help.)

[trysten]

A few first impressions:
Are we talking about dropping the man-formatting or just the symlinks? As far as I can tell, the man formatting is fine and has no issues (aside from the untrusted package issue mentioned above
Could we give a more detailed description of the "undue maintenance burden"? It seems to me that the bugs are either resolved or unrelated to man generally, aside from the symlinking being broken.

I plan on fixing the symlinks soon, unless there's something big I'm missing.