add utility to print url with pointer to error message

doc/src/Developer_utils.rst

@@ -211,6 +211,9 @@ Convenience functions
 .. doxygenfunction:: logmesg(LAMMPS *lmp, const std::string &mesg)
    :project: progguide
 
+.. doxygenfunction:: errorurl
+   :project: progguide
+
 .. doxygenfunction:: flush_buffers(LAMMPS *lmp)
    :project: progguide
 

doc/src/Errors.rst

@@ -11,6 +11,7 @@ them.
    :maxdepth: 1
 
    Errors_common
+   Errors_details
    Errors_bugs
    Errors_debug
    Errors_messages

doc/src/Errors_details.rst

@@ -0,0 +1,27 @@
+Detailed discussion of errors and warnings
+==========================================
+
+Many errors or warnings are self-explanatory and thus straightforward to
+resolve.  However, there are also cases, where there is no single cause
+and explanation, where LAMMPS can only detect symptoms of an error but
+not the exact cause, or where the explanation needs to be more detailed than
+what can be fit into a message printed by the program.  The following are
+discussions of such cases.
+
+.. _err0001:
+
+Unknown identifier in data file
+-------------------------------
+
+This error happens when LAMMPS encounters a line of text in an unexpected format
+while reading a data file. This is most commonly cause by inconsistent header and
+section data.  The header section informs LAMMPS how many entries or lines are expected in the
+various sections (like Atoms, Masses, Pair Coeffs, *etc.*\ ) of the data file.
+If there is a mismatch, LAMMPS will either keep reading beyond the end of a section
+or stop reading before the section has ended.
+
+Such a mismatch can happen unexpectedly when the first line of the data
+is *not* a comment as required by the format.  That would result in
+LAMMPS expecting, for instance, 0 atoms because the "atoms" header line
+is treated as a comment.
+

src/read_data.cpp

@@ -744,9 +744,9 @@ void ReadData::command(int narg, char **arg)
             break;
           }
         if (i == nfix)
-          error->all(FLERR,"Unknown identifier in data file: {}",keyword);
+          error->all(FLERR,"Unknown identifier in data file: {}{}", keyword, utils::errorurl(1));
 
-      } else error->all(FLERR,"Unknown identifier in data file: {}",keyword);
+      } else error->all(FLERR,"Unknown identifier in data file: {}{}", keyword, utils::errorurl(1));
 
       parse_keyword(0);
     }

src/utils.cpp

@@ -22,8 +22,8 @@
 #include "memory.h"
 #include "modify.h"
 #include "text_file_reader.h"
-#include "update.h"
 #include "universe.h"
+#include "update.h"
 
 #include <cctype>
 #include <cerrno>
@@ -137,6 +137,13 @@ void utils::fmtargs_logmesg(LAMMPS *lmp, fmt::string_view format, fmt::format_ar
   }
 }
 
+std::string utils::errorurl(int errorcode)
+{
+  return fmt::format(
+      "\nFor more information please go to https://docs.lammps.org/Errors_details.html#err{:04d}",
+      errorcode);
+}
+
 void utils::flush_buffers(LAMMPS *lmp)
 {
   if (lmp->screen) fflush(lmp->screen);

src/utils.h

@@ -74,6 +74,18 @@ namespace utils {
 
   void logmesg(LAMMPS *lmp, const std::string &mesg);
 
+  /*! Return text redirecting the user to a specific paragraph in the manual
+   *
+   * The LAMMPS manual contains detailed detailed explanations for errors and
+   * warnings where a simple error message may not be sufficient.  These can
+   * be reached through URLs with a numeric code.  This function creates the
+   * corresponding text to be included into the error message that redirects
+   * the user to that URL.
+   *
+   *  \param errorcode   number pointing to a paragraph in the manual */
+
+  std::string errorurl(int errorcode);
+
   /*! Flush output buffers
    *
    *  This function calls fflush() on screen and logfile FILE pointers