# -*- text -*-
#
# Copyright (c) 2020      Intel, Inc.  All rights reserved.
# Copyright (c) 2020      IBM Corporation.  All rights reserved.
# Copyright (c) 2021-2026 Nanook Consulting  All rights reserved.
# $COPYRIGHT$
#
# Additional copyrights may follow
#
# $HEADER$
#
#
[output]
The "output" command line directive must be accompanied by a comma-
delimited list of case-insensitive options that control how output is
generated. The full directive need not be provided — only enough
characters are required to uniquely identify the directive. For
example, "MERGE" is sufficient to represent the "MERGE-STDERR-TO-
STDOUT" directive — while "TAG" can not be used to represent "TAG-
DETAILED" (though "TAG-D" would suffice).

Supported values include:

* "TAG" marks each output line with the "[job,rank]<stream>:" of the
  process that generated it

* "TAG-DETAILED" marks each output line with a detailed annotation
  containing "[namespace,rank][hostname:pid]<stream>:" of the process
  that generated it

* "TAG-FULLNAME" marks each output line with the
  "[namespace,rank]<stream>:" of the process that generated it

* "TAG-FULLNAME" marks each output line with the
  "[namespace,rank]<stream>:" of the process that generated it

* "TIMESTAMP" prefixes each output line with a "[datetime]<stream>:"
  stamp. Note that the timestamp will be the time when the line is
  output by the DVM and not the time when the source output it

* "XML" provides all output in a pseudo-XML format "MERGE-STDERR-TO-
  STDOUT" merges stderr into stdout

* "DIR=DIRNAME" redirects output from application processes into
  "DIRNAME/job/rank/std[out,err,diag]". The provided name will be
  converted to an absolute path

* "FILE=FILENAME" redirects output from application processes into
  "filename.rank." The provided name will be converted to an absolute
  path

Supported qualifiers include:

* "COPY" - when combined with the "FILE" option, directs that a copy of
  the output be sent to the stdout/err streams as well as the file

* "NOCOPY" - when combined with the "FILE" option, do not copy the output
  to the stdout/err streams (default)

* "RAW" - do not buffer the output into complete lines, but instead output
  it as it is received.

* "PATTERN" - when combined with the "FILE" option, the given name is a
  pattern you compose yourself instead of being annotated with the namespace
  and rank. These conversions are expanded in it:

    %%n  the job's namespace
    %%r  the process's rank
    %%R  the rank, zero-padded to the width of the job's largest rank
    %%h  the hostname of the node the process ran on
    %%%%  a literal "%%" character

  The stream suffix (".out" or ".err") is still appended, so stdout and
  stderr can never land on the same file. A pattern containing no "%%" at all
  is therefore simply a fixed name shared by every process in the job.

Note that directives and qualifiers are case-insensitive.

Every directive and qualifier above that asks a yes-or-no question -
everything except "DIR" and "FILE", which name a place to write - may also
be given an explicit truth value:

  --output tag        the directive is requested
  --output tag=1      the same, said explicitly
  --output tag=0      the directive is NOT requested

True may also be written "T", "Y", "TRUE", "YES" or "ENABLE", and false
"F", "N", "FALSE", "NO" or "DISABLE" - case-insensitively, and as whole
words ("TR" is not an abbreviation of "TRUE").

A value that is neither true nor false is refused rather than guessed at:
the truth test underneath reads anything it does not recognize as "false",
so "tag=maybe" would otherwise quietly turn tagging off.

"--output" describes the job, so on an MPMD command line it may be written
in any app context and applies to all of them. Two app contexts that ask
for opposite things are refused - there is no way to honor both.
#
[copy-nocopy]
Both the "copy" and "nocopy" qualifiers were given. This is a contradictory
set of directives. Please correct the input and try again.
#
[bad-pattern]
The output filename pattern contains an unrecognized conversion:

  Pattern:     %s
  Conversion:  %s

Supported conversions are:

  %%n  the job's namespace
  %%r  the process's rank
  %%R  the rank, zero-padded to the width of the job's largest rank
  %%h  the hostname of the node the process ran on
  %%%%  a literal "%%" character

Please correct the pattern and try again.
#
[pattern-needs-file]
The "pattern" qualifier was given to the "output" directive, but no
"file=<name>" directive was given for it to qualify. "pattern" says how to
name the output FILES, so it has no meaning on its own.

Please add a "file=<name>" directive, or drop the "pattern" qualifier.
#
[pattern-unsupported]
The "pattern" qualifier was given to the "output" directive, but the PMIx
library this PRRTE was built against cannot expand an output filename
pattern - PMIx opens the output files, so it is what has to do the
expansion.

Please rebuild PRRTE against a PMIx that provides the
PMIX_CAP_IOF_FILE_PATTERN capability, or drop the "pattern" qualifier.
