ENH: more succinct output from command-line errors.

- unknown options or missing option values now emit a shorter message
  without the entire usage. This makes it easier to identify the errors
  and is better aligned with the behaviour of GNU system tools.

  ====
     $ simpleFoam -case
     Using: OpenFOAM-plus (see www.OpenFOAM.com)
     Build: plus-01234

     Error: option '-case' requires an argument

     See 'simpleFoam -help' for usage
  ====

- provide for reduced (-help) and full (-help-full) usage information.
  In many cases the reduced usage provided sufficient and easier
  to find the information.

- make -srcDoc an alias for -doc-source

- no warnings about option aliases for future dates.

bin/findEmptyMake

@@ -48,7 +48,7 @@ USAGE
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -*)

bin/foamCheckJobs

@@ -180,12 +180,10 @@ releaseLock () {
 #
 #-------------------------------------------------------------------------------
 
+case "$1" in (-h | -help*) usage ;; esac
+
 if [ $# -eq 1 ]
 then
-    if [ "$1" = "-h" -o "$1" = "-help" ]
-    then
-        usage
-    fi
     STATEFILE="$1"
 elif [ $# -eq 0 ]
 then

bin/foamCleanPath

@@ -68,7 +68,7 @@ unset optDebug optStrip
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -debug)

bin/foamCleanPolyMesh

@@ -54,7 +54,7 @@ unset caseDir regionName
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -case)

bin/foamCloneCase

@@ -56,7 +56,7 @@ TIME_OPTION="head -1"
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -l | -latestTime)

bin/foamCopySettings

@@ -63,7 +63,7 @@ USAGE
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -*)

bin/foamCreateVideo

@@ -70,7 +70,7 @@ START_NUMBER=''
 while [ "$#" -gt 0 ]
 do
    case "$1" in
-   -h | -help)
+   -h | -help*)
       usage
       ;;
    -d | -directory)

bin/foamEndJob

@@ -71,7 +71,7 @@ unset clearOpt stopOpt
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -case)

bin/foamEtcFile

@@ -196,7 +196,7 @@ unset optAll optList optShell optVersion
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -a | -all)

bin/foamExec

@@ -82,7 +82,7 @@ unset etcOpts
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -mode=*)

bin/foamJob

@@ -117,7 +117,7 @@ unset parallelOpt screenOpt waitOpt
 while [ "$#" -gt 0 ]
 do
    case "$1" in
-   -h | -help)
+   -h | -help*)
       usage
       ;;
    -case)

bin/foamLog

@@ -109,7 +109,7 @@ unset optList optQuiet localDB
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         printHelp
         exit 0
         ;;

bin/foamMonitor

@@ -87,7 +87,7 @@ GNUPLOT=$(which gnuplot)
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -i | -idle)

bin/foamNewApp

@@ -50,7 +50,7 @@ USAGE
 }
 
 case "$1" in
-(-h | -help)
+(-h | -help*)
     usage
     ;;
 -*)

bin/foamNewBC

@@ -70,7 +70,7 @@ cap() {
 [ "$#" -gt 1 ] || usage
 
 case "$1" in
-(-h | -help)
+(-h | -help*)
     usage
     ;;
 (-f | -fixedValue | fixedValue)

bin/foamNewCase

@@ -62,7 +62,7 @@ unset appName caseName listOpt
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -app)

bin/foamNewFunctionObject

@@ -54,7 +54,7 @@ USAGE
 }
 
 case "$1" in
-(-h | -help)
+(-h | -help*)
     usage
     ;;
 -*)

bin/foamPack

@@ -52,7 +52,7 @@ unset outputDir nogit
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -nogit)

bin/foamPackBin

@@ -81,7 +81,7 @@ packExt=tgz
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -b | -bzip2)

bin/foamPackDoxygen

@@ -56,7 +56,7 @@ packExt=tgz
 while [ "$#" -gt 0 ]
 do
     case $1 in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -b | -bzip2)

bin/foamPackThirdParty

@@ -51,7 +51,7 @@ unset prefix outputDir nogit
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -nogit)

bin/foamPrintJobs

@@ -105,14 +105,11 @@ leftStr() {
 #
 #-------------------------------------------------------------------------------
 
+case "$1" in (-h | -help*) usage ;; esac
+
 if [ $# -eq 1 ]
 then
-    if [ "$1" = "-h" -o "$1" = "-help" ]
-    then
-        usage
-    else
     STATEFILE="$1"
-    fi
 elif [ $# -eq 0 ]
 then
     STATEFILE=${STATEFILE:-$DEFSTATEFILE}

bin/foamSearch

@@ -63,7 +63,7 @@ unset optCount
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -c | -count)

bin/foamSequenceVTKFiles

@@ -71,7 +71,7 @@ do
       DIR=$2
       shift 2
       ;;
-   -h | -help)
+   -h | -help*)
       usage
       ;;
    -o | -out)

bin/foamUpdateCaseFileHeader

@@ -57,7 +57,7 @@ USAGE
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -v | -version)

bin/mpirunDebug

@@ -75,7 +75,7 @@ while [ "$#" -gt 0 ]
 do
     # echo "$1" 1>&2
     case "$1" in
-    -help)
+    -help*)
         usage
         ;;
 

bin/paraFoam

@@ -91,7 +91,7 @@ unset regionName optTouch
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -block*)

bin/rmcore

@@ -29,18 +29,17 @@
 #     remove all core files
 #------------------------------------------------------------------------------
 
-# default is pwd
+case "$1" in
-if [ "$#" -eq 0 ]
+-h | -help*)
-then
-    set -- .
-elif [ "$1" = "-h" -o "$1" = "-help" ]
-then
     exec 1>&2
     echo "Usage: ${0##*/} [dir1] .. [dirN]"
     echo "    remove all core files"
     exit 1
-fi
+    ;;
+esac
 
+# Default is pwd
+[ "$#" -gt 0 ] || set -- .
 
 for i
 do

bin/rm~all

@@ -29,18 +29,17 @@
 #     remove all *~ files
 #------------------------------------------------------------------------------
 
-# default is pwd
+case "$1" in
-if [ "$#" -eq 0 ]
+-h | -help*)
-then
-    set -- .
-elif [ "$1" = "-h" -o "$1" = "-help" ]
-then
     exec 1>&2
     echo "Usage: ${0##*/} [dir1] .. [dirN]"
     echo "    remove all *~ files"
     exit 1
-fi
+    ;;
+esac
 
+# default is pwd
+[ "$#" -gt 0 ] || set -- .
 
 for i
 do

bin/tools/foamConfigurePaths

@@ -182,7 +182,7 @@ unset adjusted optMpi
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help | --help)
+    -h | -help* | --help*)
         usage
         ;;
     '')

bin/tools/foamCreateCompletionCache

@@ -77,7 +77,7 @@ unset outputFile
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -d | -dir)

bin/tools/foamCreateModuleInclude

@@ -73,7 +73,7 @@ do
     '')
         # Ignore empty args
         ;;
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -debug)

bin/tools/foamGrepExeTargets

@@ -81,7 +81,7 @@ done
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
 

doc/Doxygen/Allwmake

@@ -53,7 +53,7 @@ unset configName dirNames
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -config)

etc/codeTemplates/foamScript

@@ -28,5 +28,49 @@
 # Description
 #
 #------------------------------------------------------------------------------
+usage() {
+    exec 1>&2
+    while [ "$#" -ge 1 ]; do echo "$1"; shift; done
+    cat<<USAGE
+Usage: ${0##*/} [OPTION] args
+options:
+  -help             print the usage
+
+Notes
+
+USAGE
+    exit 1
+}
+
+# Report error and exit
+die()
+{
+    exec 1>&2
+    echo
+    echo "Error encountered:"
+    while [ "$#" -ge 1 ]; do echo "    $1"; shift; done
+    echo
+    echo "See '${0##*/} -help' for usage"
+    echo
+    exit 1
+}
+
+#-------------------------------------------------------------------------------
+
+# Parse options
+
+while [ "$#" -gt 0 ]
+do
+    case "$1" in
+    -h | -help*)
+        usage
+        ;;
+    *)
+        die "unknown option/argument: '$1'"
+        ;;
+    esac
+    shift
+done
+
 
 #------------------------------------------------------------------------------

etc/codeTemplates/source/foamNewSource

@@ -64,7 +64,7 @@ fi
 [ "$#" -gt 1 ] || usage
 
 case "$1" in
-(-h | -help)
+(-h | -help*)
     usage
     ;;
 (C|H)

etc/codeTemplates/template/foamNewTemplate

@@ -65,7 +65,7 @@ fi
 
 
 case "$1" in
-(-h | -help)
+(-h | -help*)
     usage
     ;;
 (C|H)

etc/config.sh/bash_completion

@@ -92,9 +92,9 @@ foamAddCompletion()
 # - arg2 = current word
 # - arg3 = previous word
 #
-# The respective options are generated on-the-fly from the application's -help
+# The respective options are generated on-the-fly from the application's
-# output and cached to the _of_complete_cache_ global associative array with
+# -help-full output and cached to the _of_complete_cache_ global associative
-# entries formatted as "argOpts.. | boolOpts ..".
+# array with entries formatted as "argOpts.. | boolOpts ..".
 # The '|' character separates options with and without arguments.
 #
 unset -f _of_complete_ 2>/dev/null
@@ -106,7 +106,7 @@ _of_complete_()
     local choices
 
     case ${prev} in
-    -help|-doc|-srcDoc)
+    -help|-help-full|-doc|-doc-source)
         # These options are usage - we can stop now.
         COMPREPLY=()
         return 0
@@ -130,10 +130,10 @@ _of_complete_()
         # All options
         choices="${_of_complete_cache_[$appName]}"
 
-        # Not in cache, obtain by parsing application -help
+        # Not in cache, obtain by parsing application -help-full
         if [ -z "$choices" ]
         then
-            local helpText=$($appName -help 2>/dev/null | sed -ne '/^  *-/p')
+            local helpText=$($appName -help-full 2>/dev/null | sed -ne '/^  *-/p')
 
             if [ -n "$helpText" ]
             then

src/OpenFOAM/global/argList/argList.C

@@ -85,20 +85,20 @@ Foam::argList::initValidTables::initValidTables()
     argList::addBoolOption
     (
         "noFunctionObjects",
-        "do not execute functionObjects"
+        "do not execute function objects"
     );
 
     argList::addOption
     (
         "fileHandler",
         "handler",
-        "override the fileHandler"
+        "override the file handler type"
     );
 
     // Some standard option aliases (with or without version warnings)
 //     argList::addOptionCompat
 //     (
-//         "noFunctionObjects", {"no-function-objects", 0 }
+//         "noFunctionObjects", {"no-function-objects", 0}
 //     );
 
     Pstream::addValidParOptions(validParOptions);
@@ -152,8 +152,22 @@ static void printHostsSubscription(const UList<string>& slaveProcs)
     Info<< ")" << nl;
 }
 
+
+// Print information about version, build, arch
+static void printBuildInfo(const bool full=true)
+{
+    Info<<"Using: OpenFOAM-" << Foam::FOAMversion
+        << " (see www.OpenFOAM.com)" << nl
+        << "Build: " << Foam::FOAMbuild << nl;
+
+    if (full)
+    {
+        Info << "Arch:  " << Foam::FOAMbuildArch << nl;
+    }
 }
 
+} // End namespace Foam
+
 
 // * * * * * * * * * * * * * Static Member Functions * * * * * * * * * * * * //
 
@@ -415,9 +429,20 @@ Foam::word Foam::argList::optionCompat(const word& optionName)
         {
             const auto& iter = *canonical;
 
-            if (iter.second)
+            // Emit warning if there is versioning (non-zero) and it is not
+            // tagged as future change (ie, ThisVersion > version).
+
+            if
+            (
+                iter.second
+             &&
+                (
+                    (OPENFOAM_PLUS > 1700)  // Guard against bad #define value
+                  ? (OPENFOAM_PLUS > iter.second)
+                  : true
+                )
+            )
             {
-                // Emit warning, but only if version (non-zero) was provided
                 std::cerr
                     << "--> FOAM IOWarning :" << nl
                     << "    Found [v" << iter.second << "] '"
@@ -614,6 +639,9 @@ Foam::argList::argList
     regroupArgv(argc, argv);
     argListStr_ += args_[0];
 
+    // Set executable name immediately - useful when emitting errors.
+    executable_ = fileName(args_[0]).name();
+
     // Check arguments and options, argv[0] was already handled
     int nArgs = 1;
     HashTable<string>::const_iterator optIter;
@@ -649,11 +677,15 @@ Foam::argList::argList
                 ++argi;
                 if (argi >= args_.size())
                 {
-                    FatalError
+                    printBuildInfo(false);
-                        <<"Option '-" << optionName
+
-                        << "' requires an argument" << endl;
+                    Info<<nl
-                    printUsage();
+                        <<"Error: option '-" << optionName
-                    FatalError.exit();
+                        << "' requires an argument" << nl << nl
+                        << "See '" << executable_ << " -help' for usage"
+                        << nl << nl;
+
+                    Pstream::exit(1); // works for serial and parallel
                 }
 
                 argListStr_ += ' ';
@@ -681,9 +713,6 @@ Foam::argList::argList
 
     args_.setSize(nArgs);
 
-    // Set executable name
-    executable_ = fileName(args_[0]).name();
-
     parse(checkArgs, checkOpts, initialise);
 }
 
@@ -719,14 +748,20 @@ void Foam::argList::parse
 {
     // Help/documentation options:
     //   -help        print the usage
+    //   -help-full   print the full usage
     //   -doc         display application documentation in browser
-    //   -srcDoc  display source code in browser
+    //   -doc-source  display source code in browser
     {
         bool quickExit = false;
 
-        if (options_.found("help"))
+        if (options_.found("help-full"))
         {
-            printUsage();
+            printUsage(true);
+            quickExit = true;
+        }
+        else if (options_.found("help"))
+        {
+            printUsage(false);
             quickExit = true;
         }
 
@@ -736,7 +771,11 @@ void Foam::argList::parse
             displayDoc(false);
             quickExit = true;
         }
-        else if (options_.found("srcDoc"))
+        else if
+        (
+            options_.found("doc-source")
+         || options_.found("srcDoc")  // Compat 1706
+        )
         {
             displayDoc(true);
             quickExit = true;
@@ -748,12 +787,14 @@ void Foam::argList::parse
         }
     }
 
-    // Print the usage message and exit if the number of arguments is incorrect
+    // Print the collected error messages and exit if check fails
     if (!check(checkArgs, checkOpts))
     {
-        FatalError.exit();
+        printBuildInfo(false);
-    }
+        FatalError.write(Info, false);
 
+        Pstream::exit(1); // works for serial and parallel
+    }
 
     if (initialise)
     {
@@ -1297,7 +1338,7 @@ void Foam::argList::printNotes() const
 }
 
 
-void Foam::argList::printUsage() const
+void Foam::argList::printUsage(bool full) const
 {
     Info<< "\nUsage: " << executable_ << " [OPTIONS]";
 
@@ -1328,6 +1369,19 @@ void Foam::argList::printUsage() const
     const wordList opts = validOptions.sortedToc();
     for (const word& optionName : opts)
     {
+        if (!full)
+        {
+            // Adhoc filtering of some options to suppress
+            if
+            (
+                optionName.startsWith("list")
+             && optionName != "list"
+            )
+            {
+                continue;
+            }
+        }
+
         Info<< "  -" << optionName;
         label len = optionName.size() + 3;  // Length includes leading '  -'
 
@@ -1352,24 +1406,23 @@ void Foam::argList::printUsage() const
         }
     }
 
-    // Place srcDoc/doc/help options at the end
+    // Place documentation/help options at the end
-    Info<< "  -srcDoc";
-    printOptionUsage(9, "display source code in browser" );
-
     Info<< "  -doc";
     printOptionUsage(6, "display application documentation in browser");
 
+    Info<< "  -doc-source";
+    printOptionUsage(13, "display source code in browser" );
+
     Info<< "  -help";
-    printOptionUsage(7, "print the usage");
+    printOptionUsage(7, "print usage information and exit");
+    Info<< "  -help-full";
+    printOptionUsage(12, "print full usage information and exit");
 
     printNotes();
 
-    Info<< nl
+    Info<< nl;
-        <<"Using: OpenFOAM-" << Foam::FOAMversion
+    printBuildInfo();
-        << " (see www.OpenFOAM.com)" << nl
+    Info<< endl;
-        << "Build: " << Foam::FOAMbuild << nl
-        << "Arch:  " << Foam::FOAMbuildArch << nl
-        << endl;
 }
 
 
@@ -1456,8 +1509,8 @@ bool Foam::argList::check(bool checkArgs, bool checkOpts) const
         if (checkArgs && nargs != validArgs.size())
         {
             FatalError
-                << "Wrong number of arguments, expected " << validArgs.size()
+                << "Expected " << validArgs.size()
-                << " found " << nargs << endl;
+                << " arguments but found " << nargs << endl;
             ok = false;
         }
 
@@ -1481,7 +1534,10 @@ bool Foam::argList::check(bool checkArgs, bool checkOpts) const
 
         if (!ok)
         {
-            printUsage();
+            FatalError
+                << nl
+                << "See '" << executable_ << " -help' for usage"
+                << nl << nl;
         }
     }
 

src/OpenFOAM/global/argList/argList.H

@@ -445,7 +445,7 @@ public:
             void printNotes() const;
 
             //- Print usage
-            void printUsage() const;
+            void printUsage(bool full=true) const;
 
             //- Display documentation in browser
             //  Optionally display the application source code

wmake/scripts/AllwmakeParseArguments

@@ -71,7 +71,7 @@ do
     shift
 
     case "$arg" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -fromWmake)

wmake/scripts/wcleanBuild

@@ -93,7 +93,7 @@ USAGE
 # Find -help anywhere
 for i
 do
-    case "$i" in (-h | -help) usage ;; esac
+    case "$i" in (-h | -help*) usage ;; esac
 done
 
 #------------------------------------------------------------------------------

wmake/wclean

@@ -78,7 +78,7 @@ MakeDir=Make
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -a | -all | all)

wmake/wcleanLnIncludeAll

@@ -49,10 +49,7 @@ USAGE
 }
 
 # Simple help
-if [ "$1" = "-h" -o "$1" = "-help" ]
+case "$1" in (-h | -help*) usage ;; esac
-then
-    usage
-fi
 
 #------------------------------------------------------------------------------
 # Default is the current directory

wmake/wdep

@@ -62,7 +62,7 @@ USAGE
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -*)

wmake/wmake

@@ -126,7 +126,7 @@ while [ "$#" -gt 0 ]
 do
     case "$1" in
         # Print help
-        -h | -help)
+        -h | -help*)
             usage
             ;;
         -s | -silent)

wmake/wmakeCheckPwd

@@ -76,7 +76,7 @@ error()
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -q | -quiet)

wmake/wmakeCollect

@@ -74,7 +74,7 @@ unset cleanup
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -kill | -clean)

wmake/wmakeFilesAndOptions

@@ -56,7 +56,7 @@ USAGE
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)   # Provide immediate help
+    -h | -help*)   # Provide immediate help
         usage
         ;;
     *)

wmake/wmakeLnInclude

@@ -78,7 +78,7 @@ unset update silentOpt
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-        -h | -help)   # Provide immediate help
+        -h | -help*)   # Provide immediate help
             usage
             ;;
         -u | -update)

wmake/wmakeLnIncludeAll

@@ -67,7 +67,7 @@ unset wmLnOpt
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-        -h | -help)
+        -h | -help*)
             usage
             ;;
         -u | -update)

wmake/wmakePrintBuild

@@ -81,7 +81,7 @@ unset checkOnly update package version optPlus optShort
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     -c | -check)

wmake/wrmdep

@@ -104,7 +104,7 @@ while [ "$#" -gt 0 ]
 do
     case "$1" in
     # Print help
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     # All platforms

wmake/wrmo

@@ -67,7 +67,7 @@ unset platform
 while [ "$#" -gt 0 ]
 do
     case "$1" in
-    -h | -help)
+    -h | -help*)
         usage
         ;;
     # All platforms