5 ms·

> I would skip man pages are they just aren’t used that often anymore. I understand that man pages might represent a minority, but I cannot express enough how

> I would skip man pages are they just aren’t used that often anymore. I understand that man pages might represent a minority, but I cannot express enough how wonderful it is to get the full manual of a program without interfacing with the web. Not to mention how powerful that is, since most apps have short names that are difficult to search for, but how accessible that makes the application.

norova 8y ago
I agree that man pages are wonderful. This point in the article really irked me.
dickeytk 8y ago
The fact they don't run on windows means some subset of your users cannot even use them if they wanted to. Better to spend your time on something they can all read. I'm not saying they're not useful. If you've got plenty of time to write up docs, go ahead, but the reality is we only have so much time and I think we should spend our time writing in-CLI docs and web docs before we start man pages. Also, you don't need web access to use in-CLI docs either, and that works on all platforms. Having said this, I do plan on having man pages be an export type of the oclif docs (which is currently in-CLI and markdown). I intentionally made the output very similar to man pages already so it should be relatively easy to do.
- deleted 8y ago
  [deleted]
- therealjumbo 8y ago
  For man pages you could suggest writing markdown and using a build process to automatically generate man pages [1] in the event they aren't using oclif. EDIT: I think we've all been in areas without network access like on a plane and not having a man page in that scenario is very annoying. Also, you briefly say a few things about CLI apps using a remote API, you may want to add to that and say a few things about the proxy environment variables [2]. These are indispensible for corporate users. I think some early, early version of npm didn't respect the no_proxy environment variable, and for the http_proxy and https_proxy it required some arcane combination of: proxy in a flag, proxy in a config file, proxy environment variable set. It really should be an OR not an AND... Last but not least, another annoying thing was tools changing their config format or location. I think it was docker that changed their config file format and/or location like two or three times. Absolutely infuriating. 1. https://rtomayko.github.io/ronn/ronn.1.html https://rtomayko.github.io/ronn/ronn.1.html 2. https://wiki.archlinux.org/index.php/proxy_settings https://wiki.archlinux.org/index.php/proxy_settings
  - dickeytk 8y ago
    Oh believe me. I'm intimately familiar with proxies and CLI apps. I think that might be a good standalone article though as it only applies to CLIs that connect to APIs whereas this article is intended for all CLIs, period. (Minus that note about the user-agent I suppose). We get away without using any config files in the Heroku CLI which is certainly preferable. (Well, there is a config file, but I don't think anyone's using it and it's undocumented. I think all it can do is disable colors) Config is another topic that I do think would warrant its own article as well. I may not be the best author though as we've tried to avoid config. (Though it's a common enough problem I do want to solve generically as possible in oclif). As far as automatically building man pages, I still think that's a wasted effort. Nobody has ever asked for or even mentioned man pages in our CLI. Setting up a build process and distribution is considerable effort and maintenance burden. Of course if the users of your CLI want man pages then of course build them. In my experience though, that's not what users want. Though it's important to note that a CLI that interacts with a cloud service is pretty useless without internet. If no internet is the only compelling reason to support man pages, I'm still not convinced it's a better use of your time. The docs should already be available offline in the CLI itself.
- Phelinofist 8y ago
  Well, PowerShell has the Get-Help cmdlet that is somewhat similar to the *NIX man command. See https://docs.microsoft.com/de-de/powershell/developer/help/how-to-create-the-cmdlet-help-file https://docs.microsoft.com/de-de/powershell/developer/help/h...
dickeytk 8y ago
For people that like man pages (there appears to be lots of you) do you think that man pages are more important than web or in-cli docs? Or just that they should be written in addition to and not missed out on? My (current) position is that they're useful, but not worth the extra effort for most CLIs. It's a cost-benefit thing. I'm genuinely curious as I've never had anyone request man pages in our CLI.
- ibotty 8y ago
  I prefer a well-written man page to any other information. Git (and a few others) do open the man page when invoking `--help`. That's a way to avoid some overhead.
  - jwilk 8y ago
    I hate when programs do that. When I type "foo --help", I want concise help message for foo. If wanted foo man page, I would have typed "man foo".
    - ibotty 8y ago
      man pages can include concise usage examples as well.
- enriquto 8y ago
  I for one prefer actual manpages than online documentation. The web documentation is cumbersome to find, forces me to open a browser window, and I cannot copy-paste easily from inside my terminal. Notice that if you already have help, you can build the manpages automatically from them using "help2man". You could get manpages for all your tools by simply adding a line into your makefile!
  - dickeytk 8y ago
    If the man pages are simply generated from the help output, why bother having them when you can just use `--help`?
JdeBP 8y ago
It's an argument that Daniel J. Bernstein made when proposing slashdoc. So M. Dickey is not alone. * https://cr.yp.to/slashdoc.html https://cr.yp.to/slashdoc.html I myself write doco in Docbook XML * https://news.ycombinator.com/item?id=15779321 https://news.ycombinator.com/item?id=15779321 generate HTML from that that can be read directly xdg-open /usr/local/share/doc/nosh/machineenv.html or on the WWW * http://jdebp.eu./Softwares/nosh/guide/machineenv.html http://jdebp.eu./Softwares/nosh/guide/machineenv.html and generate roff for man pages from it as well man machineenv Whereas --help output is auto-generated from the option definitions given to the command-line parser, much like libpopt does.

norova 8y ago

I agree that man pages are wonderful. This point in the article really irked me.

dickeytk 8y ago

The fact they don't run on windows means some subset of your users cannot even use them if they wanted to. Better to spend your time on something they can all read. I'm not saying they're not useful. If you've got plenty of time to write up docs, go ahead, but the reality is we only have so much time and I think we should spend our time writing in-CLI docs and web docs before we start man pages. Also, you don't need web access to use in-CLI docs either, and that works on all platforms. Having said this, I do plan on having man pages be an export type of the oclif docs (which is currently in-CLI and markdown). I intentionally made the output very similar to man pages already so it should be relatively easy to do.

deleted 8y ago
[deleted]
therealjumbo 8y ago
For man pages you could suggest writing markdown and using a build process to automatically generate man pages [1] in the event they aren't using oclif. EDIT: I think we've all been in areas without network access like on a plane and not having a man page in that scenario is very annoying. Also, you briefly say a few things about CLI apps using a remote API, you may want to add to that and say a few things about the proxy environment variables [2]. These are indispensible for corporate users. I think some early, early version of npm didn't respect the no_proxy environment variable, and for the http_proxy and https_proxy it required some arcane combination of: proxy in a flag, proxy in a config file, proxy environment variable set. It really should be an OR not an AND... Last but not least, another annoying thing was tools changing their config format or location. I think it was docker that changed their config file format and/or location like two or three times. Absolutely infuriating. 1. https://rtomayko.github.io/ronn/ronn.1.html https://rtomayko.github.io/ronn/ronn.1.html 2. https://wiki.archlinux.org/index.php/proxy_settings https://wiki.archlinux.org/index.php/proxy_settings
- dickeytk 8y ago
  Oh believe me. I'm intimately familiar with proxies and CLI apps. I think that might be a good standalone article though as it only applies to CLIs that connect to APIs whereas this article is intended for all CLIs, period. (Minus that note about the user-agent I suppose). We get away without using any config files in the Heroku CLI which is certainly preferable. (Well, there is a config file, but I don't think anyone's using it and it's undocumented. I think all it can do is disable colors) Config is another topic that I do think would warrant its own article as well. I may not be the best author though as we've tried to avoid config. (Though it's a common enough problem I do want to solve generically as possible in oclif). As far as automatically building man pages, I still think that's a wasted effort. Nobody has ever asked for or even mentioned man pages in our CLI. Setting up a build process and distribution is considerable effort and maintenance burden. Of course if the users of your CLI want man pages then of course build them. In my experience though, that's not what users want. Though it's important to note that a CLI that interacts with a cloud service is pretty useless without internet. If no internet is the only compelling reason to support man pages, I'm still not convinced it's a better use of your time. The docs should already be available offline in the CLI itself.
Phelinofist 8y ago
Well, PowerShell has the Get-Help cmdlet that is somewhat similar to the *NIX man command. See https://docs.microsoft.com/de-de/powershell/developer/help/how-to-create-the-cmdlet-help-file https://docs.microsoft.com/de-de/powershell/developer/help/h...

dickeytk 8y ago

For people that like man pages (there appears to be lots of you) do you think that man pages are more important than web or in-cli docs? Or just that they should be written in addition to and not missed out on? My (current) position is that they're useful, but not worth the extra effort for most CLIs. It's a cost-benefit thing. I'm genuinely curious as I've never had anyone request man pages in our CLI.

ibotty 8y ago
I prefer a well-written man page to any other information. Git (and a few others) do open the man page when invoking `--help`. That's a way to avoid some overhead.
- jwilk 8y ago
  I hate when programs do that. When I type "foo --help", I want concise help message for foo. If wanted foo man page, I would have typed "man foo".
  - ibotty 8y ago
    man pages can include concise usage examples as well.
enriquto 8y ago
I for one prefer actual manpages than online documentation. The web documentation is cumbersome to find, forces me to open a browser window, and I cannot copy-paste easily from inside my terminal. Notice that if you already have help, you can build the manpages automatically from them using "help2man". You could get manpages for all your tools by simply adding a line into your makefile!
- dickeytk 8y ago
  If the man pages are simply generated from the help output, why bother having them when you can just use `--help`?

JdeBP 8y ago

It's an argument that Daniel J. Bernstein made when proposing slashdoc. So M. Dickey is not alone. * https://cr.yp.to/slashdoc.html https://cr.yp.to/slashdoc.html I myself write doco in Docbook XML * https://news.ycombinator.com/item?id=15779321 https://news.ycombinator.com/item?id=15779321 generate HTML from that that can be read directly xdg-open /usr/local/share/doc/nosh/machineenv.html or on the WWW * http://jdebp.eu./Softwares/nosh/guide/machineenv.html http://jdebp.eu./Softwares/nosh/guide/machineenv.html and generate roff for man pages from it as well man machineenv Whereas --help output is auto-generated from the option definitions given to the command-line parser, much like libpopt does.