Add man page

[harrisi]

The manpage is basically just the output of nvm --help. A few things were added/modified to be more "manpage-like".

The modification to install.sh isn't great, so that probably needs to be changed.

This was handwritten so there might be some inconsistencies.

[harrisi]

Since it's been over a month, I hope this isn't inappropriate to ask again. I'm partial to having manpages be a manual process since their purpose is for human consumption. Just as manual API documentation isn't ideal, hand-written manpages should be handwritten. It seems like the main contributors disagree, but I'd like to find a happy medium. Perhaps a git commit hook that monitors any changes to the inputs and outputs of specific functions, or changes to the --help flag? That way it's at least much more likely for contributions to keep the --help flag and the man page constantly compatible.

I'd like to make it clear that my intent is to make it easier for developers to learn about how to use the tool. I'm very much a fan of man, and this is something I would've loved to have after downloading this tool. So any way to make man readers and contributors to this tool happy is ideal.

Side note: thanks for the great tool!

[ljharb]

I generally agree that documentation should be handwritten - that's why i hand-write nvm --help.

However, I never use manpages myself (because so few tools have actually useful manpages on the CLI in my experience; googling is much easier), so I'm unlikely to maintain the manpages - and since I'm the sole maintainer, that means that they'll likely go out of date a lot.

If you don't think it's possible to have a manpage autogenerated from nvm --help output, I'd at least need some sort of CI check that prevents them from going out of sync.

[ljharb]

@harrisi i think that if we can update the MANPATH to point to something inside $NVM_DIR, and if we can add a test that fails when nvm --help doesn't match the manpage, this will be ready to go. Any chance you're still interested in completing the PR?

[harrisi]

@ljharb Just saw this, sorry!

Sure, I'll look into this again. Rather busy in the near future, but this sounds fun.

[ljharb]

Thanks! Either way, please make sure the branch and the fork don't get deleted; if you decide to give up on it, I'll try to finish it myself.

[harrisi]

@ljharb hey, just wanted to give an update - didn't forget about this, just life.

So I think the easiest thing to do would just be to use help2man. It's a little awkward because I can't for the life of me figure out a clean way to use it without wrapping nvm in a shell basically. What I ended up with is just something like this:

// file: nvm
#!/usr/bin/env node

require('child_process')
  .exec(`source $NVM_DIR/nvm.sh && nvm ${process.argv.splice(2).join(' ')}`,
    console.log)

and then running help2man like so:

# note that the usage of ./nvm is because help2man gets the name from this and I haven't figured out how to change it without modifying the .1 file directly
# also, not super happy with the --no-colors option. I'd rather output with colors since the user can choose whether or not to use colors, but I need to convert the ANSI escape sequences to troff colors
help2man -h "--no-colors --help" -N ./nvm > nvm.1

This could just be done in a GitHub Action, and the output is quite nice.

Shouldn't take too long to finish, but I'm not very familiar with GitHub Actions, and it's been awhile since I messed with man files. Mainly just wanted to check and see if this all sounds good!

[ljharb]

It’s definitely not an option to a) add a new file, or b) make nvm require node exists before working - nvm is how node gets first installed.

[harrisi]

Hmm, not sure I understand? a) the only file added will be the manpage, i.e. nvm.1, and b) okay, it can be done using anything, but I don't know why this matters? Is there any difference to running brew install node in an action as opposed to brew install shellcheck as is done in https://github.com/nvm-sh/nvm/blob/master/.github/workflows/shellcheck.yml#L31?

Maybe I'm confused, but can GitHub Actions not output a file?

EDIT:

And if that won't work, mimicking https://github.com/nvm-sh/nvm/blob/master/.github/workflows/toc.yml and making a help2man npm package that's a dev dependency seems like it'd be fine? Really it doesn't matter, whatever makes more sense to you. I was mostly just wondering if the output of help2man seemed reasonable to you.

[ljharb]

ah, maybe i misunderstood. You're talking about a CI task to generate content, without any runtime implications?

[harrisi]

This seems to look good - is there a way i can test it locally without having to actually install the manpage? like, man path/to/manpage or something?

Yup! man ./nvm.1. (note, the file, nvm.txt attached uses the .txt extension because github won't let me upload a .1 file. the extension doesn't matter, man ./nvm.txt works fine too.)

I didn't include the man page previously, but I'll attach the current output here. If you install help2man and run the script from above you can run it yourself. Note that this would just run as a GitHub Action.

nvm.txt

Also, if you don't want to download anything, to see a not-very-well-formatted version (generated using pandoc), https://fofgof.xyz/nvm.

Again, I still have to finish some stuff, I just wanted to check in, let you know I didn't abandon this, and make sure this approach would be reasonable. :)

[ljharb]

Thanks! I'll take a look.

Rather than actually running as a github action, i'd prefer it to work like the TOC does - to fail if the PR author forgot to run npm run man or something, and then they're forced to commit the results.

[ljharb]

The output looks pretty great! there's a bit more newlines between things than i'd like in a few cases, and the full justification looks weird. also, the options aren't properly indented (like, under nvm install [<version>], everything should be indented underneath that, until nvm uninstall <version>).

[harrisi]

Handling it like TOC sounds good to me! No problem.

Noted on the output inconsistencies. I agree, and I'll look into that. Thanks again! Will update soon.