Sitelet https://web.archive.org/web/20200910105258/https://github.com/nvm-sh/nvm/pull/1779

nvm-sh / nvm

Sponsor

Sponsor nvm-sh/nvm
Watch 895
Star 44k
Fork 4.3k

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

Add man page #1779

Open

harrisi wants to merge 1 commit into nvm-sh:master from harrisi:man-pages

+159 −1

harrisi commented Apr 9, 2018

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.


        Add man page

12d6749

uberhacker reviewed

  
      @@ -293,6 +293,10 @@ nvm_check_global_modules() {
    
          fi

        }

        nvm_install_manpage() {

            ln -s $PWD/nvm.1 /usr/local/share/man/man1/nvm.1

uberhacker Apr 9, 2018

Contributor

Will this need sudo? I'm not sure /usr/local/share/man... will be writable by the current user unless root.

harrisi Apr 9, 2018 •

edited

Author

In my test it works fine. It's the same path as all brew-installed applications use for manpages, it seems.

If there's a better path to use let me know! :)

ljharb Apr 10, 2018

Member

Since nvm is explicitly not supported when using brew, and using brew with it is deprecated, we definitely shouldn't be using what brew uses.

I think it's highly likely this will need sudo, which is a problem.

harrisi Apr 10, 2018

Author

I think mentioning brew was misleading. That path doesn't have anything to do with brew. That's actually one of the directories that man will search in for both a fresh install of macOS 10.13.3 and Ubuntu 16.04. The others are /usr/share/man (both), /usr/X11/man (macOS 10.13.3), and /usr/local/man (Ubuntu 16.04). So, ideally, /usr/local/share/man or /usr/share/man can be used since those both work on macOS and Ubuntu (I believe it should be the case for most/all Linux versions as well).

ljharb Apr 10, 2018

Member

In that case, the only remaining issue is that it's a path that requires sudo. Is there any way to modify the MANPATH so it can locate the file from something inside NVM_DIR?

harrisi Apr 10, 2018

Author

Actually, yes, I believe so. You can just set MANPATH to whatever and prepend or append a : to it, and man will add the other locations (listed above).

I'll add that tomorrow, depending on what you decide in the other ongoing comment.

ljharb requested changes

  
      @@ -0,0 +1,152 @@
    
        .TH "NVM" "1" "March 2018" "NVM" "nvm"

ljharb Apr 10, 2018

Member

Is there any way to generate this programmatically, so that it doesn't inevitably drift from the nvm --help output? I'd rather not have the manpage at all then risk having one that's incorrect.

harrisi Apr 10, 2018

Author

Hm, I'm not sure what you mean exactly. I'm not sure if you mean that line in particular or the entirety of the manpage. The date is expected to only be updated when the manpage is update, and can be removed entirely realistically. It was originally there for version control but that's not very useful anymore, especially since this is a git repository.

If you mean programmatically generate the entire manpage, then sure it's possible, but would require more work. I also don't know if it's desired, but that's not up to me.

ljharb Apr 10, 2018

Member

Sorry for being unclear; I'm referring to the entirety of the manpage.

I alter the content of nvm --help relatively frequently (hopefully improvements) and I think that without automatic enforcement (ensuring that the manpage matches) and a script to synchronize the content (see npm run doctoc for an example) that it'd be too easy to drift.

In summary, if you're willing to do the work to automatically generate the entire manpage and provide a reproducible script for that, that'd be awesome.

harrisi Apr 10, 2018

Author

I might, but I'd like to think about this a bit more. In my opinion, user-facing documents shouldn't be autogenerated. I could just do a pretty straightforward translation of the nvm --help output, but I think something is lost in that. Alternatively, something could just check to see if any commit changes the output of nvm --help, and if so, not allow a merge without updating the manpage. That seems a little bit aggressive, but also keeps things more in check (hopefully).

If you have any other suggestions, let me know.

Author

harrisi commented May 14, 2018

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!

Member

ljharb commented May 14, 2018

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 force-pushed the nvm-sh:master branch from 00ecf52 to 8e1e5df

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

You can’t perform that action at this time.