From f66976876112ec1f5732ec1430f749b26b113462 Mon Sep 17 00:00:00 2001
From: "Mark A. Grondona" <mark.grondona@gmail.com>
Date: Tue, 6 Jun 2023 09:36:29 -0700
Subject: [PATCH] doc: document flux-batch(1) and flux-alloc(1) --conf option

Problem: The --conf option is undocumented.

Add documentation for this option to
man1/common/submit-other-options.rst.
---
 doc/man1/common/submit-other-options.rst | 26 ++++++++++++++++++++++++
 doc/test/spell.en.pws                    |  2 ++
 2 files changed, 28 insertions(+)

diff --git a/doc/man1/common/submit-other-options.rst b/doc/man1/common/submit-other-options.rst
index 1a7f89b200ee..cb91d6615e20 100644
--- a/doc/man1/common/submit-other-options.rst
+++ b/doc/man1/common/submit-other-options.rst
@@ -48,6 +48,32 @@ OTHER OPTIONS
    encode multiple files.  Note: As documented in RFC 14, the file names
    ``script`` and ``conf.json`` are both reserved.
 
+**--conf=FILE|KEY=VAL|STRING**
+   The ``--conf`` option allows configuration for a Flux instance started
+   via ``flux-batch(1)`` or ``flux-alloc(1)`` to be iteratively built on
+   the command line. On first use, a ``conf.json`` entry is added to the
+   internal jobspec file archive, and ``-c{{tmpdir}}/conf.json`` is added
+   to the flux broker command line. Each subsequent use of the ``--conf``
+   option updates this configuration.
+
+   The argument to ``--conf`` may be in one of several forms:
+
+   * A multiline string, e.g. from a batch directive. In this case the string
+     is parsed as JSON or TOML::
+
+      # flux: --conf="""
+      # flux: [resource]
+      # flux: exclude = "0"
+      # flux: """
+
+   * A string containing a ``=`` character, in which case the argument is
+     parsed as ``KEY=VAL``, where ``VAL`` is parsed as JSON, e.g.::
+
+      --conf=resource.exclude=\"0\"
+
+   * A string ending in ``.json`` or ``.toml``, in which case configuration
+     is loaded from a JSON or TOML file.
+
 **--begin-time=+FSD|DATETIME**
    Convenience option for setting a ``begin-time`` dependency for a job.
    The job is guaranteed to start after the specified date and time.
diff --git a/doc/test/spell.en.pws b/doc/test/spell.en.pws
index c6ad2088c830..68bfdde7975f 100644
--- a/doc/test/spell.en.pws
+++ b/doc/test/spell.en.pws
@@ -706,3 +706,5 @@ unbuffered
 statex
 pmix
 SIGUSR
+iteratively
+noverify