have proper manpages for bitcoin*(1) #10805

Currently, the manpages of bitcoind, bitcoin-cli, bitcoin-tx and bitcoin-qt are generated in doc/man via help2man from the binaries's respective -help. I propose to write proper manpages, get rid of the help2man dependency, remove the textual help() from the binaries, and have what a cmdline UNIX utility is suposed to have: the manpage, the one place where the utility is documented.

I am willing to do the work. As an example of what I have in mind, I am creating this PR with bitcoin-cli.1 (which is the shortest :-).

Please let me know if there is any interest in this.

I think the real issue here is less ability to write a manpage once, and more whether it will be maintained. Without the generation being automated based on things that do get maintained, we've seen man pages and stuff like this go out of date and be forgotten about for a release or two :/.

Maintaining the manpage, IMHO, is an integral part of maintaining the utility itself. The help2man-generated "manpages" are of abysmall quality and it seems to be an assumption that nobody will read them anyway: it's all in the --help anyway, by definition. That's precisely what I want to change: maintain the manpage as a part of the software; make it the place where the utility is documented, as expected on a UNIX system.

The travis integration build has failed. Looking at the detailed log, I don't see how the fails is connected to the proposed change at all (being a change in a manage).

Looks like it is related to the man page change "make[1]: *** No rule to make target bitcoin-cli.1', needed by distdir'. Stop.", configure wants to build the man page itself.

New manpage does look better, but I don't think it's so much better that it's worth maintaining two different copies of documentation for every command line option. (Which would turn into 3 different copies with bitcoind.1 and bitcoin-qt.1 because they share most options.) @janstary, I'm wondering what specific restrictions help2man has that prevent you from making your documentation improvements? And if help2man doesn't do something important that you want it to do, maybe we could replace it with another script?

@ryanofsky That's a misunderstanding - in what I propose there's no "two different copies of documentation" - the manpage is the one and only place. As is ls(1) and any other manpage.

Re help2man: there is no way to "make my documentation improvements" because there is no place to write documentation if the manages are just regenerated from --help. A real manpage is a piece of free-form prose, describing the utility in all detail; that's not something you put into a help() printf. Which is precisely what I want to change: have a proper manpage - the one and only place where the thing is documented. As expected.

How do you learn the details of ls(1)? Exactly.

@TheBlueMatt Yes. This is the first step, trying to find out if there's interest in this. I need and will track down all the pieces in the build procedure.

(Notice how absurdly simplier it is already. "./configure wants to build the manpage itself". What?!)

Heh, maybe ls is a bad example...on my system the man ls and ls --help output are identical +/- copyright/author one-liners. I think @ryanofsky's question was more of a "OK, so lets write a script which pulls from --help and then adds some additional prose to generate the manpage, that way we dont have a bunch of stuff that goes out of date cause no one remembers to update the manpage".

Currently, the user learns about the basic usage of e.g. bitcoin-cli(1) not by running man bitcoin-cli, as one would expect, but by seeing the output of bitcoin-cli's function AppInitRPC() whose puropse is, quote

//
// This function returns either one of EXIT_ codes when it's expected to stop the process or
// CONTINUE_EXECUTION when it's expected to continue further.
//

No. This is not documentation. Have a proper manpage.

(Repeat: I am willing to do it.)

A real manpage is a piece of free-form prose, describing the utility in all detail; that's not something you put into a help() printf

I don't understand why you can't put prose in a printf. I like your prose, I think it would be welcome in a printf, and C++11 supports multiline ("raw") strings that can contain as much text as you want to write. I guess your preferred solution to the problem of manpages duplicating source documentation is to remove the documentation from the source code. I think that would be reasonable as long as there's some kind of tool that can take the manpage and generate -help strings or whatever documentation we might need for platforms like windows where manpages are not the "one and only place" for documentation to exist.

Also, I don't know if you proposed a solution for deduping the options documentation between the bitcoind.1 and bitcoin-qt.1 manpages, because we don't want to have to maintain two copies of that either. Maybe you could add a new bitcoind.conf manpage that the other two manpages would reference.

NACK to this. I prefer the current state.

Why move the manpages to src/? doc seems a better place.

Also we had manually written man pages, but no one was updating them, so we went with the automatically generated approach. This was less than a version ago. See #8608.

The old debian manpages were removed here: b194872 - both due to license issues, and due to not being maintained.

We're not going to change this again now. Sorry.

Apparently, there is no interest it this, in fact an oposition, so I'm closing it.

Yes, sorry for that.

In the abstract I agree that specifically written man-pages are better than auto-generated ones, if kept up to date. But in the context of this project it doesn't seem to be realistic. It's been tried before and failed.

That's what I find hard to believe. Where I come from, the manpage is a source file like any other part of the software; e.g. changing a function means chainging the header and changing the manpage describing that function. Not here, apparently.

Not here, apparently.

No, not here. Unix documentation is only a small part of the focus.