Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

BREAKING CHANGE: remove man support #481

Open
lukekarrys opened this issue Apr 10, 2022 · 4 comments
Open

BREAKING CHANGE: remove man support #481

lukekarrys opened this issue Apr 10, 2022 · 4 comments
Labels

Comments

@lukekarrys
Copy link
Contributor

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
Copy link

ljharb commented Apr 10, 2022

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
Copy link
Contributor Author

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
Copy link

d0sboots commented May 1, 2022

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
Copy link

trysten commented Apr 12, 2023

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

4 participants