doc: document per-resource options in flux-mini(1)

Problem: The per-resource options are not documented in the
flux-mini(1) manpage.

Reorganize the man page description of job options into "common",
"per task" and "per resource" sections as they now appear in the
--help output. Add entries for all the per-resource options.

Author: grondo

doc/man1/flux-mini.rst

@@ -64,8 +64,34 @@ JOB PARAMETERS
 These commands accept only the simplest parameters for expressing
 the size of the parallel program and the geometry of its task slots:
 
-The **run** and **submit** commands take the following options to specify
-the size of the job request:
+Common resource options
+-----------------------
+
+All subcommands take the following common resource allocation options:
+
+**-N, --nodes=N**
+   Set the number of nodes to assign to the job. Tasks will be distributed
+   evenly across the allocated nodes, unless the per-resource options
+   (noted below) are used with *submit*, *run*, or *bulksubmit*. It is
+   an error to request more nodes than there are tasks. If unspecified,
+   the number of nodes will be chosen by the scheduler.
+
+**--exclusive**
+   Indicate to the scheduler that nodes should be exclusively allocated to
+   this job. It is an error to specify this option without also using
+   *-N, --nodes*. If *--nodes* is specified without *--nslots* or *--ntasks*,
+   then this option will be enabled by default and the number of tasks
+   or slots will be set to the number of requested nodes.
+
+
+Per-task options
+----------------
+
+The **run**, **submit** and **bulksubmit** commands take two sets
+of mutually exclusive options to specify the size of the job request.
+The most common form uses the total number of tasks to run along with
+the amount of resources required per task to specify the resources for
+the entire job:
 
 **-n, --ntasks=N**
    Set the number of tasks to launch (default 1).
@@ -76,6 +102,29 @@ the size of the job request:
 **-g, --gpus-per-task=N**
    Set the number of GPU devices to assign to each task (default none).
 
+Per-resource options
+--------------------
+
+The second set of options allows an amount of resources to be specified
+with the number of tasks per core or node set on the command line. It is
+an error to specify any of these options when using any per-task option
+listed above:
+
+**--cores=N**
+   Set the total number of cores.
+
+**--tasks-per-node=N**
+   Set the number of tasks per node to run.
+
+**--tasks-per-core=N**
+   Force a number of tasks per core.
+
+**--gpus-per-node=N**
+   With -N, --nodes, request a specific number of GPUs per node.
+
+Batch job options
+-----------------
+
 The **batch** and **alloc** commands do not launch tasks directly, and
 therefore job parameters are specified in terms of resource slot size
 and number of slots. A resource slot can be thought of as the minimal
@@ -90,22 +139,12 @@ resources required for a virtual task. The default slot size is 1 core.
 **-g, --gpus-per-slot=N**
    Set the number of GPU devices to assign to each slot (default none).
 
+Additional job options
+----------------------
+
 The **run**, **submit**, **batch**, and **alloc** commands also take
 following additional job parameters:
 
-**-N, --nodes=N**
-   Set the number of nodes to assign to the job. Tasks will be distributed
-   evenly across the allocated nodes. It is an error to request more nodes
-   than there are tasks. If unspecified, the number of nodes will be chosen
-   by the scheduler.
-
-**--exclusive**
-   Indicate to the scheduler that nodes should be exclusively allocated to
-   this job. It is an error to specify this option without also using
-   *-N, --nodes*. If *--nodes* is specified without *--nslots* or *--ntasks*,
-   then this option will be enabled by default and the number of tasks
-   or slots will be set to the number of requested nodes.
-
 **-t, --time-limit=FSD**
    Set a time limit for the job in Flux standard duration (RFC 23).
    FSD is a floating point number with a single character units suffix