Problem: the extra click to get to the actual man1 pages
from readthedocs is annoying.

Since most man page users already know what they want to look up,
flatten out the section 1 index with commands in lexicographical order.

Problem: flux-alloc(1) mentions flux-proxy(1) without linking.

Add the :man1:`flux-proxy` linkage.

Problem: flux-mini has been deprecated for some time, but
still has a man page we have to maintain.

Drop the man page.

Problem: flux-bulksubmit.rst includes its content from
common/submit-bulksubmit.rst because it was shared with flux-mini.rst
but flux-mini(1) is no more.

Move that content into flux-bulksubmit.rst.

Problem: flux-batch.rst includes content from
common/submit-submission-directives.rst because it was shared with
flux-mini.rst but flux-mini(1) is no more.

Move that content into flux-batch.rst.

Problem: flux-watch(1) lists its title as "flux-jobs".

Fix title.

Problem: the EXIT STATUS section of the job submission commands
reference flux-run(1) but have a typo in the role causing it
to render improperly.

Fix typo.

Problem: command line options do not stand out in the HTML rendering
and do not have HTML tags for cross referencing.

Use the 'option' directive[1], which causes options to stand out and
also opens the door to cross referencing of options.

Note we have some man pages like flux-kvs(1) that describe options
in a compressed paragraph form rather than breaking them out in a
list.  Those pages were left alone by this commit.

[1]https://www.sphinx-doc.org/en/master/usage/domains/standard.html

Problem: the HTML cross-reference tags that are automatically
generated for declared options point to a path that is relative
to the document basename name rather than the command or sub-command
name, which could be ambiguous.

For example, consider the flux job attach "-l, --label-io" option.
The auto-generated tag is "flux-job.html#cmdoption-l"

As noted in [1], the 'program' directive notifies Sphinx that all
following option directives document options for the named program.
After declaring the program to be "flux job attach", the tag becomes:
"flux-job.html#cmdoption-flux-job-attach-l".

References to the option with the program name in it like
:option:`flux job attach -l` or :option:`flux job attach --label-io`
become hyperlinks to the option description within the page containing
the program.

Note that a program directive remains in effect when included text is
processed.  This means that options declared in common/*.rst are properly
tagged when included from other pages.  For example, the "-N, --nodes=N"
option in flux-batch(1) is "flux-batch.html#cmdoption-flux-batch-N",
while in flux-run(1) it is "flux-run.html#cmdoption-flux-run-N".

[1]https://www.sphinx-doc.org/en/master/usage/domains/standard.html

Problem: when referring to options, we usually just quote them
as a literal string, which is ugly in the HTML rendering
and does not allow sphinx to cross-reference references to
descriptions.

Use the :option: directive to tie option references to their
description in the HTML.  This also improves the HTML rendering.

The cross references are particularly helpful in the job submission
command options, where there are many options and some need to refer
to others.

It should be OK to use the :option: directive with any option string
since, at a minimum, it helps unify their presentation.  However Sphinx
only cross-references certain option string formats.  Consider this
example:

.. program:: flux run

.. option:: -o, --option=OPTS

The following are cross-referenced:

:option:`-o`
:option:`--option`
:option:`flux run --option`

The following are not cross-referenced by sphinx 3.4.3, but the
documentation implies the first two should work in sphinx 5.3:

:option:`--option=OPTS`
:option:`--option=pty.interactive`
:option:`-o, --option`

In this commit, all of the above are deemed acceptable markup,
athough in some cases the last format was converted to the long
option alone when it wasn't the only documentation of the short
option.

This commit only addresses option formatting, although some lines
were re-broken in the .rst files to avoid going over 79 columns.

Note: this commit is not a complete conversion of all option
strings across section 1. It only touches some of the more widely
used and/or easy to convert pages.

Problem: program names are not consistently formatted.

Use :program: to format program names.  This is purely a formatting
role and does not generate any cross-reference data.

Use :option: to format a program name with options, to cross-reference
to the option description.

https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html

Problem: man pages contain several "See section ..." references
but the HTML does not link there.

Improve section cross-referencing.  Sections within a document
can be referenced with `SECTION NAME`_ and outside of a document
can be referenced via :ref: as described here

https://www.sphinx-doc.org/en/master/usage/referencing.html