Man page proof of concept

[clumens]

This isn't a mergeable PR. I would want to break it out into various commits, but I don't want to do a lot of work on it if this isn't a direction we want to go. I've not gone through and made sure this man page strictly follows the groff_man_style(7) outline, but that is something I would want to do before merging this.

The basic idea here is that we use the current help2man generated man pages as the basis for hand-written man pages. Each one gets added to doc/man/. Once it's done, all the *.inc files can go away, as can tools/fix-manpages and a lot of man/man.mk.

I think it would be easiest to evaluate this by looking at it in man, instead of the raw file. Of course look at that too, but there's not a ton going on in there.

Pros:

• Less stuff happening in the build process.
• We can write more prosaic, less terse documentation for command tools (it doesn't have to cram into the --help output).
• We can simplify --help output (does it really need examples?)
• This documentation can replace what's in the tools section of Pacemaker Administration.
• We can write additional man pages to describe certain things and refer to them throughout other man pages (for instance, a single place that describes all environment variables).
• Fix things help2man gets wrong. For instance, it turns this in cibadmin --help-all:

  -o, --scope=value             Limit scope of operation to specific section of CIB
                                Valid values: configuration, nodes, resources, constraints, crm_config, rsc_defaults,
                                              op_defaults, acls, fencing-topology, tags, alerts, status
                                If both --scope/-o and --xpath/-a are specified, the last one to appear takes effect

into this:

       -o, --scope=value
              Limit scope of operation to specific section of CIB Valid values: configuration, nodes, resources, constraints, crm_config, rsc_defaults,

       op_defaults, acls, fencing-topology, tags, alerts, status
              If both --scope/-o and --xpath/-a are specified, the last one to appear takes effect

Cons:

• When we update the code, we have to remember to update both the help output and the man pages.
• If we write additional man pages, we then have to keep them up-to-date with our existing documentation.
• groff is kind of terrible.