doc: audit man page cross references

[garlick]

Once the macro for conveniently adding manual page cross-references in #3999 is merged, we may want to audit the SEE ALSO sections of our man pages. Cross references appear to be hit and miss.

Also, some SEE ALSO references are web references. Should we move those to RESOURCES and reserve SEE ALSO for man page cross-references?

While we're at it, we should consider updating the github organization link in RESOURCES since we have other, better documentation resources now. Maybe just change it to https://flux-framework.org/, which is the most "meta" reference we have.

[chu11]

i like the idea that RESOURCES should just point to web addresses, while SEE ALSO just points to other manpages.

[chu11]

while i'm at it, the web addresses are listed inconsistently. I think I would prefer just doing a format like:

foobar: http://www.foobar.com

where as we sometimes do:

`libev home page <http://software.schmorp.de/pkg/libev.html>`__

While this gets you a pretty link in read the docs, the manpage gets you this relatively useless:

       libev home page

just the name for the URL and nothing else. But doing Foobar: www.foobar.com kinda format, you get this on read the docs and the manpages:

Github: http://github.com/flux-framework

[grondo]

I'm definitely not a sphinx/reStructuredText expert, but maybe with intersphinx and specific domains, we can do a little better than either of the approaches above. The manpage domainrefs plugin I just added might help here, for example see how mitogen uses it to add other general web refs in their conf.py:

https://github.com/mitogen-hq/mitogen/blob/master/docs/conf.py

[chu11]

closed via #4007