[stepvhen]

> 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.

[dickeytk]

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.

[cyphar]

> do you think that man pages are more important than web or in-cli docs?

Yes.

* Web docs are a problem because I don't always have access to the internet when trying to do something on my computer, and usually there are so many kinds of web doc generators that you have to figure out how the information you want is laid out. Web docs are useful as a quick-start guide or a very lengthy reference guide -- but not for the common usecase of "is there a flag to do X?"

* In-CLI docs are a cheaper version of man pages. In most cases, the output is larger than the current terminal size so you end up piping to a pager (where you can search as well), and now you have a more terse version of a man page. Why not just have a man page?

Man pages are useful because they have a standard format and layout, provide both short and long-form information, and are universally understood by almost anyone who has used a Linux machine in the past. "foo --help" requires the program to know what that means (I once managed to bootloop a router by doing "some_mgmt_cmt --help" and it didn't support "--help" -- I always use man pages now). One of the first things I teach students I tutor (when they're learning how to use Linux) is how to read man pages. Because they are the most useful form of information on Linux, and it's quite sad that so many new tools decide that they aren't worth the effort -- because you're now causing a previously unified source of information (man pages) to be fractured for no obvious gain.

I still add support for "--help" for my projects (because it is handy, I will admit) but I always include manpages for those projects as well so that users can actually get proper explanations of what the program does.

> I'm genuinely curious as I've never had anyone request man pages in our CLI.

Honestly, I would consider not using a project if an alternative had man pages (though in this case it would be somewhat more out of principle -- and I would submit a bug report to bring it to the maintainers' attention).

[majewsky]

> I still add support for "--help" for my projects (because it is handy, I will admit)

Some applications (e.g. Git) make "--help" redirect to man. What do you think of that?

[falcolas]

Personally, I still pull up "man git-pull" or similar. I'm actively annoyed that I have to remember that the AWS CLI is different in this regard.

Not to mention that using "--help" for man pages requires I open up a separate window when I typically just want a quick reference to the most used flags.

Moving man pages to a different command is like coming up with an alternative icon to the hamburger menu for your regular UI. Sure, all the functionality is still there, but it requires a full stop and search to remember where to find it.

[majewsky]

I also prefer manpages over web searches for multiple reasons:

- works without internet: very important when you want to use a long train ride to write some code (I also have the entire rust-doc and all IETF RFCs on my disk for quick referencing)

- quick and reliable access to known items: `man ascii` is way quicker than finding an ASCII table on the web (probably on Wikipedia). And finding the syntax for an obscure bash feature is way easier when your search is confined to `man bash` rather than to the entire web.

- Don't know how to label this, but I like that the manpage is a complete documentation of one tool, unlike a disconnected set of Stack Overflow questions. That allows one to cursory read through the manpage to learn the scope of what that tool can accomplish.

[falcolas]

One more reason - the man pages will be specific to the version of your tool. My man pages on my mac will automatically pull up the BSD version of "ls", not the GNU version.

[enriquto]

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]

If the man pages are simply generated from the help output, why bother having them when you can just use `--help`?

[TeMPOraL]

Because the expectation on UNIX-like systems is that I can type `man foo` and get the manpage for `foo`.

It's good manners for a CLI app you want installed on someone's system to also integrate with the help infrastructure of that system.

[JdeBP]

The end result argues against using help2man and thinking that --help and the user manual should be the same thing, not against having a user manual at all. (-:

* https://news.ycombinator.com/item?id=18174025

[scbrg]

apropos

[kccqzy]

Well, man pages are the standard way to get documentation. Sometimes --help is detailed enough to be a replacement (in which case I can tolerate the lack of man pages), but usually not.

I don't really care about documentation on the web. In fact I'd rather you simply treat the man pages as the single source of truth and put the man pages on the web. Sort of like https://linux.die.net/man/

[voltagex_]

https://manpages.debian.org/ffmpeg (or whatever package) is good, too.

[scbrg]

I see no benefit whatsoever to web docs over man pages. man pages are immediately available, where you are (the CLI) without an internet connection or a web browser.

I expect the -h flag to give me a summary of the flags and arguments, to remind me of the particular name of the flag I'm missing. I most certainly don't want the whole documentation there, partly because the whole documentation is (presumably) large enough to scroll my history off screen.

So, yes, man pages are definitely more important than web or in-cli docs.

[Riverheart]

In my limited experience, manpages give you a wall of text when 9/10 times you just want a oneliner example of how to do something. Web resources generally address the lack of real world examples in manpages.

[scbrg]

Then you use your pager's search functionality and go to the EXAMPLES section. If there is no EXAMPLES section, that's not the fault of the format, but of the author. Presumably, the same author would be equally good (or bad) at providing examples no matter if the target format was a man page or a web page.

[ibotty]

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]

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]

man pages can include concise usage examples as well.

[thaumasiotes]

In terms of usability web docs are better. But having the docs on the web is not a good thing; there are many advantages to having them locally.

I'd be just as happy with bundled HTML documentation.

[norova]

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

[JdeBP]

It's an argument that Daniel J. Bernstein made when proposing slashdoc. So M. Dickey is not alone.

* https://cr.yp.to/slashdoc.html

I myself write doco in Docbook XML

* 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

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.

[dickeytk]

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.

[therealjumbo]

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

2. https://wiki.archlinux.org/index.php/proxy_settings

[dickeytk]

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]

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/h...