update docs

doc/src/Developer_notes.rst

@@ -268,12 +268,14 @@ There are multiple "signatures" that can be called:
   command would be the last line, but is unrelated to the error.
 
 - ``Error::all(FLERR, idx, "Error message")``: this is for argument
-  parsing where "idx" is the index of the argument for a LAMMPS command
+  parsing where "idx" is the index (starting at 0) of the argument for a
-  that is causing the failure (use -1 for the command itself). The
+  LAMMPS command that is causing the failure (use -1 for the command
-  output will then not only be the last input line, but also the command
+  itself).  The output may also include the last input line *before* and
-  and arguments *after* they have been pre-processed and split into
+  *after*, if they differ due to substituting variables.  A textual
-  individual arguments and a textual indicator pointing to the specific
+  indicator is pointing to the specific word that failed.  Using the
-  word that failed.
+  constant ``Error::NOPOINTER`` in place of the *idx* argument will
+  suppress the marker and then the behavior is like the *idx* argument
+  is not provided.
 
 FLERR is a macro containing the filename and line where the Error class
 is called and that information is appended to the error message.  This
@@ -285,6 +287,13 @@ the arguments are then handed for formatting to the `{fmt} library
 <https://fmt.dev>`_ (which is bundled with LAMMPS) and thus allow
 processing similar to the "format()" functionality in Python.
 
+.. note::
+
+   For commands like :doc:`fix ave/time <fix_ave_time>` that accept
+   wildcard arguments, the :cpp:func:`utils::expand_args` function
+   may be passed as an optional argument where the function will provide
+   a map to the original arguments from the expanded argument indices.
+
 For complex errors, that can have multiple causes and which cannot be
 explained in a single line, you can append to the error message, the
 string created by :cpp:func:`utils::errorurl`, which then provides a

doc/src/Run_output.rst

@@ -203,22 +203,35 @@ Two lines
 In addition to the single line output, also the last line of the input
 will be repeated.  If a command is spread over multiple lines in the
 input using the continuation character '&', then the error will print
-the entire concatenated line.  However, there is no further processing
+the entire concatenated line.  For readability all whitespace is
-of that line.  Example:
+compressed to single blanks.  Example:
 
 .. parsed-literal::
 
    ERROR: Unrecognized fix style 'printf' (src/modify.cpp:924)
-   Last input line: fix        0 all printf v_nevery 'Step: $(step) ${step}'
+   Last input line: fix 0 all printf v_nevery "Step: $(step) ${step}"
+
+Three lines
+^^^^^^^^^^^
+
+In addition to the two line output from above, a third line is added
+that uses caret character markers '^' to indicate which "word" in the
+input failed.  Example:
+
+.. parsed-literal::
+
+   ERROR: Illegal fix print nevery value -100; must be > 0 (src/fix_print.cpp:41)
+   Last input line: fix 0 all print -100 "Step: $(step) ${stepx}"
+                                    ^^^^
 
 Four lines
 ^^^^^^^^^^
 
-In addition to the two line output, the last command is printed a second
+The three line output is expanded to four lines, if the the input is
-time, but *after* all variables were substituted and the line separated
+modified through input pre-processing, e.g. when substituting
-into "words" as they are passed internally to the called command.  This line
+variables. Now the last command is printed once in the original form and
-is followed by a line with caret character markers '^' to indicate which
+a second time after substitutions are applied.  The caret character
-"word" in the parsed input is causing the failure.  Example:
+markers '^' are applied to the second version.  Example:
 
 .. parsed-literal::
 

src/utils.h

@@ -402,9 +402,9 @@ This functions adds the following case to :cpp:func:`utils::bounds() <LAMMPS_NS:
    *  caller. Otherwise arg and earg will point to the same address
    *  and no explicit de-allocation is needed by the caller.
    *
-   *  The *argmap* pointer may be used to return an array of integers
+   *  The *argmap* pointer to an int pointer may be used to accept an array
-   *  mapping the arguments after the expansion to their original index.
+   *  of integers mapping the arguments after the expansion to their original
-   *  If this pointer is NULL (the default) than this map is not created.
+   *  index.  If this pointer is NULL (the default) than this map is not created.
    *  Otherwise, it must be deallocated by the calling code.
    *
    * \param file    name of source file for error message
@@ -414,7 +414,7 @@ This functions adds the following case to :cpp:func:`utils::bounds() <LAMMPS_NS:
    * \param mode    select between global vectors(=0) and arrays (=1)
    * \param earg    new argument list with wildcards expanded
    * \param lmp     pointer to top-level LAMMPS class instance
-   * \param argmap  pointer integer list mapping the expanded indices to the input (optional)
+   * \param argmap  pointer to integer pointer for mapping expanded indices to input (optional)
    * \return      number of arguments in expanded list */
 
   int expand_args(const char *file, int line, int narg, char **arg, int mode, char **&earg,