man1: improve section cross-referencing

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

doc/man1/common/submit-environment.rst

@@ -8,7 +8,7 @@ give fine control over the requested environment submitted with the job.
 .. option:: --env=RULE
 
    Control how environment variables are exported with *RULE*. See
-   *ENV RULE SYNTAX* section below for more information. Rules are
+   the `ENV RULES`_ section below for more information. Rules are
    applied in the order in which they are used on the command line.
    This option may be specified multiple times.
 

doc/man1/common/submit-other-options.rst

@@ -27,7 +27,7 @@ OTHER OPTIONS
    Set shell option. Keys may include periods to denote hierarchy.
    VAL is optional and may be valid JSON (bare values, objects, or arrays),
    otherwise VAL is interpreted as a string. If VAL is not set, then the
-   default value is 1. See SHELL OPTIONS below.
+   default value is 1. See `SHELL OPTIONS`_ below.
 
 .. option:: --setattr=KEY[=VAL]
 

doc/man1/flux-config.rst

@@ -37,7 +37,7 @@ string values, which are printed without quotes to simplify their use in shell
 scripts.
 
 :program:`flux config builtin` prints compiled-in Flux configuration values.
-See BUILTIN VALUES below for a list of builtin
+See `BUILTIN VALUES`_ below for a list of builtin
 configuration key names.  This command is available to all users.
 
 .. note::

doc/man1/flux-exec.rst

@@ -61,7 +61,7 @@ OPTIONS
 .. option:: -r, --rank=NODESET
 
    Target specific ranks in *NODESET*. Default is to target "all" ranks.
-   See NODESET FORMAT below for more information.
+   See `NODESET FORMAT`_ below for more information.
 
 .. option:: -v, --verbose
 

doc/man1/flux-jobs.rst

@@ -70,18 +70,18 @@ OPTIONS
 .. option:: -f, --filter=STATE|RESULT
 
    List jobs with specific job state or result. Multiple states or
-   results can be listed separated by comma. See JOB STATUS below for
+   results can be listed separated by comma. See `JOB STATUS`_ below for
    additional information. Defaults to *pending,running*.
 
 .. option:: -o, --format=NAME|FORMAT
 
    Specify a named output format *NAME* or a format string using Python's
-   format syntax. See OUTPUT FORMAT below for field names. Named formats
+   format syntax. See `OUTPUT FORMAT`_ below for field names. Named formats
    may be listed via :option:`--format=help`.  An alternate default format can
    be set via the FLUX_JOBS_FORMAT_DEFAULT environment variable.  Additional
    named formats may be registered with :program:`flux jobs` via configuration.
-   See the CONFIGURATION section for more details. A configuration snippet for
-   an existing named format may be generated with
+   See the `CONFIGURATION`_ section for more details. A configuration snippet
+   for an existing named format may be generated with
    :option:`--format=get-config=NAME`.
 
 .. option:: --json
@@ -173,6 +173,7 @@ OPTIONS
    threads is used, but by using the :option:`--threads`, a specific number
    of threads can be chosen.
 
+.. _flux_jobs_job_status:
 
 JOB STATUS
 ==========
@@ -195,6 +196,8 @@ FAILED, CANCELED, or TIMEOUT. Under the *status_abbrev* field name,
 these are abbreviated as D, S, R, C, CD, F, CA, and TO respectively.
 
 
+.. _flux_jobs_output_format:
+
 OUTPUT FORMAT
 =============
 
@@ -491,6 +494,8 @@ the state of the job or other context:
    will also be provided such as the exit ``returncode`` or
    cancellation message.
 
+.. _flux_jobs_configuration:
+
 CONFIGURATION
 =============
 

doc/man1/flux-pstree.rst

@@ -99,8 +99,8 @@ OPTIONS
 .. option:: -f, --filter=STATE|RESULT
 
    Include jobs with specific job state or result. Multiple states or
-   results can be listed separated by comma. See the JOB STATUS section
-   of the :man1:`flux-jobs` manual for more detail.
+   results can be listed separated by comma. See the :ref:`flux_jobs_job_status`
+   section of the :man1:`flux-jobs` manual for more detail.
 
 .. option:: -l, --long
 

doc/man1/flux-queue.rst

@@ -121,7 +121,7 @@ OPTIONS
 .. option:: -o, --format=FORMAT
 
    Specify output format in ``list`` using Python's string format syntax.
-   See OUTPUT FORMAT below for field names.
+   See `OUTPUT FORMAT`_ below for field names.
 
 
 OUTPUT FORMAT

doc/man1/flux-resource.rst

@@ -63,7 +63,7 @@ COMMANDS
    to include only those ranks or hosts that are present in *TARGETS*.
 
    The :option:`-o,--format=FORMAT` option may be used to customize the output
-   format (See OUTPUT FORMAT section below).
+   format (See `OUTPUT FORMAT`_ section below).
 
    The :option:`-n,--no-header` option suppresses header from output,
 
@@ -120,7 +120,7 @@ COMMANDS
    filtered to include only those ranks or hosts that are present in *TARGETS*.
 
    The :option:`-o,--format=FORMAT` option customizes output formatting (See
-   the OUTPUT FORMAT section below for details).
+   the `OUTPUT FORMAT`_ section below for details).
 
    With :option:`-n,--no-header` the output header is suppressed.
 
@@ -175,13 +175,15 @@ OUTPUT FORMAT
 The :option:`--format` option can be used to specify an output format using
 Python's string format syntax or a defined format by name. For a list of
 built-in and configured formats use :option:`-o help`.  An alternate default
+<<<<<<< HEAD
 format can be set via the FLUX_RESOURCE_STATUS_FORMAT_DEFAULT,
 FLUX_RESOURCE_DRAIN_FORMAT_DEFAULT, and FLUX_RESOURCE_LIST_FORMAT_DEFAULT
 environment variables (for :program:`flux resource status`,
 :program:`flux resource drain`, and :program:`flux resource list`
 respectively).  A configuration snippet for an existing named format may be
 generated with :option:`--format=get-config=NAME`.  See :man1:`flux-jobs`
-*OUTPUT FORMAT* section for a detailed description of this syntax.
+:ref:`flux_jobs_output_format` section for a detailed description of this
+syntax.
 
 Resources are combined into a single line of output when possible depending on
 the supplied output format.  Resource counts are not included in the
@@ -280,8 +282,8 @@ the following config file could be used::
   description = "My flux resource list format"
   format = "{state} {nodelist}"
 
-See :man1:`flux-jobs` *CONFIGURATION* section for more information about the
-order of precedence for loading these config files.
+See :man1:`flux-jobs` :ref:`flux_jobs_configuration` section for more
+information about the order of precedence for loading these config files.
 
 RESOURCE INVENTORY
 ==================

doc/man1/flux-shell.rst

@@ -25,13 +25,13 @@ The design of the Flux job shell allows customization through a set of
 builtin and runtime loadable shell plugins. These plugins are used to
 handle standard I/O redirection, PMI, CPU and GPU affinity, debugger
 support and more. Details of the :program:`flux shell` plugin capabilities and
-design can be found in the PLUGINS section below.
+design can be found in the `PLUGINS`_ section below.
 
 :program:`flux shell` also supports configuration via a Lua-based configuration
 file, called the shell ``initrc``, from which shell plugins may be loaded
 or shell options and data examined or set. The :program:`flux shell` initrc may
 even extend the shell itself via simple shell plugins developed directly
-in Lua. See the SHELL INITRC section below for details of the ``initrc``
+in Lua. See the `SHELL INITRC`_ section below for details of the ``initrc``
 format and features.
 
 OPTIONS
@@ -66,7 +66,7 @@ execution of the job:
    typically ``<userid>-shell-<jobid>``
  * load the system default ``initrc.lua``
    (``$sysconfdir/flux/shell/initrc.lua``), unless overridden by
-   configuration (See JOBSPEC OPTIONS and INITRC sections below)
+   configuration (See `JOBSPEC OPTIONS`_ and `SHELL INITRC`_ sections below)
  * call ``shell.init`` plugin callbacks
  * change working directory to the cwd of the job
  * enter a barrier to ensure shell initialization is complete on all shells
@@ -117,7 +117,7 @@ These callbacks are defined by "topic strings" to which plugins can
    the shell option is set before the builtin attempts to read them.
 
 Simple plugins may also be developed directly in the shell ``initrc.lua``
-file itself (see INITRC section, ``plugin.register()`` below)
+file itself (see `SHELL INITRC`_ section, ``plugin.register()`` below)
 
 By default, :program:`flux shell` supports the following plugin callback
 topics:
@@ -207,7 +207,7 @@ Options supported by :program:`flux shell` proper include:
 **initrc**\ =\ *FILE*
   Load :program:`flux shell` initrc.lua file from *FILE* instead of the default
   initrc path. For details of the job shell initrc.lua file format,
-  see the INITRC section below.
+  see the `SHELL INITRC`_ section below.
 
 Job shell plugins may also support configuration via shell options in
 the jobspec. For specific information about runtime-loaded plugins,

doc/man1/flux-start.rst

@@ -36,7 +36,7 @@ OPTIONS
 .. option:: -v, --verbose=[LEVEL]
 
    This option may be specified multiple times, or with a value, to
-   set a verbosity level.  See VERBOSITY LEVELS below.
+   set a verbosity level.  See `VERBOSITY LEVELS`_ below.
 
 .. option:: -X, --noexec
 

doc/man1/flux-top.rst

@@ -86,7 +86,7 @@ The summary pane shows the following information:
 
 - The amount of time until the job's expiration time, in Flux Standard Duration
   format.  If the expiration time is unknown, the infinity symbol is
-  displayed (see CAVEATS below).
+  displayed (see `CAVEATS`_ below).
 
 - The nodes bargraph, which shows the fraction of used and down/excluded nodes
   vs total nodes.  The graph of used nodes is colored yellow and extends from

doc/man1/flux-update.rst

@@ -29,7 +29,7 @@ would request an update of ``attributes.system.myattr`` to the string value
 ``"value"``.
 
 The :program:`flux update` command may also support other convenient key
-aliases.  Key aliases are listed in the SPECIAL KEYS section below.
+aliases.  Key aliases are listed in the `SPECIAL KEYS`_ section below.
 
 Updates will be sent to the job manager update service, which checks that
 the current user is permitted to apply all updates, and that all updates