- now use findEtcEntry() instead to handle file or directory.

  Added findEtcEntries(), which provides provides a common code basis
  for findEtcDirs(), findEtcFiles() ...

- restrict to text between "^[Oo]ptions:" and "-help-full" to avoid
  potential issues when more text is introduced in the usage output.

- now needs local 'set' instead of 'setenv'

- fixed inconsistency in edit of ParaView_VERSION for csh version

- now consider options '-hostRoots', '-roots' to be advanced options
  that don't need to be in the cache

- The usage claimed '-output=', but was using '--output=' for the
  output file.  Rectify to use single dash as documented.

- provide default WM_DIR if not already set, to improve robustness if a
  reduced environment is used

- add etc/ to WM_PROJECT_SITE search. This makes the site directory
  structure consistent with the OpenFOAM structure.
  Eg,

      WM_PROJECT_SITE/etc/..
      WM_PROJECT_SITE/bin/..
      WM_PROJECT_SITE/platforms/..

- Don't set/export WM_OSTYPE.  The default is POSIX and is properly
  defaulted throughout, including in CMakeLists-OpenFOAM.txt (also for
  Catalyst)

- Use the OPENFOAM define (eg, 1806, 1812), which normally corresponds
  to a major release, to define an API level. This remains consistent
  within a release cycle and means that it is possible to manage
  several sub-versions and continue to have a consistent lookup.

  The current API value is updated automatically during the build
  and cached as meta data for later use, even when the wmake/ directory
  is missing or OpenFOAM has not yet be initialized.

  The version information reported on program start or with -help
  usage adjusted to reflect this. The build tag from git now also
  carries the date as being more meaningful to trace than a hash
  value.

- Update etc/bashrc and etc/cshrc to obtain the project directory
  directly instead of via its prefix directory. The value obtained
  corresponds to an absolute path, from which the prefix directory
  can be obtained.

  The combination of these changes removes the reliance on any
  particular directory naming convention.
  For example,

     With an 1812 version (API level):

     WM_PROJECT_VERSION=myVersion

     installed as /some/path/somewhere/openfoam-mySandbox

  This makes the -prefix, -foamInstall, -projectVersion, -version
  values of foamEtcFiles, and similar entries for foamConfigurePaths
  superfluous.

  WM_PROJECT_INST_DIR is no longer required or used

ENH: improve handling and discovery of ThirdParty

- improve the flexibility and reusability of ThirdParty packs to cover
  various standard use cases:

    1. Unpacking initial release tar files with two parallel directories
       - OpenFOAM-v1812/
       - ThirdParty-v1812/

    2. With an adjusted OpenFOAM directory name, for whatever reason
       - OpenFOAM-v1812-myCustom/
       - openfoam-1812-other-info/

    3. Operating with/without ThirdParty directory

  To handle these use cases, the following discovery is used.

  Note PROJECT = the OpenFOAM directory `$WM_PROJECT_DIR`
       PREFIX = the parent directory
       VERSION = `$WM_PROJECT_VERSION`
       API = `$WM_PROJECT_API`, as per `foamEtcFiles -show-api`

   0. PROJECT/ThirdParty
      - for single-directory installations

   1. PREFIX/ThirdParty-VERSION
      - this corresponds to the traditional approach

   2. PREFIX/ThirdParty-vAPI
      - allows for an updated value of VERSION (eg, v1812-myCustom)
        without requiring a renamed ThirdParty. The API value
        would still be '1812' and the original ThirdParty-v1812/
        would be found.

   3. PREFIX/ThirdParty-API
      - this is the same as the previous example, but using an unadorned
        API value. This also makes sense if the chosen version name also
        uses the unadorned API value in its naming
        (eg, 1812-patch190131, 1812.19W03)

   4. PREFIX/ThirdParty-common
      - permits maximum reuse for various versions, but only for
        experienced user who are aware of potential version
        incompatibilities

   Directory existence is checked as is the presence of an Allwmake file
   or a platforms/ directory. This reduces the potential of false positive
   matches and limits the selection to directories that are either
   with sources (has the Allwmake file), or pre-compiled binaries (has
   the platforms/ directory).

   If none of the explored directories are found to be suitable,
   it reverts to using a PROJECT/ThirdParty dummy location since
   this is within the project source tree and can be trusted to
   have no negative side-effects.

ENH: add csh support to foamConfigurePaths

- this removes the previously experienced inconsistence in config file
  contents.

REMOVED: foamExec

- was previously used when switching versions and before the
  bashrc/cshrc discovery logic was added. It is now obsolete.

- check if the first argument corresponds to an OpenFOAM value for
  'true' (as per Switch).
  True == 't', 'y', 'true', 'yes', 'on'. Everything else is not true.

- when the first argument is '-dict', it initializes the value
  with a query via foamDictionary.
  Eg,
       isTrue -dict mydict -entry parallel

   ==> value=$(foamDictionary mydict -entry parallel -value)
       isTrue $value

   a missing entry is silently treated as false.

ENH: add getNumberOfPatchFaces function in RunFunctions

- simple extraction of nFaces from boundary file for given patch/region

- was PREFIX/site, now PROJECT/site

  This avoids several issues when installing OpenFOAM in clusters
  without an intermediate OpenFOAM-specific installation prefix.

  The 'site' directory may have a reserved meaning in these situations
  and it is undesirable to 'leak' upwards into the parent directory to
  look for configuration files.

  Placing the default within the project directory avoids this.
  Alternative locations can be given via the WM_PROJECT_SITE variable.

- removed reliance on ParaView_INCLUDE_DIR variable for conveying the
  major.minor version information when compiling. This can be somewhat
  fragile and also adds variable that is an unnecessary when running
  (only used when compiling).

  Instead use `have_pvplugin_support` function in paraviewFunctions
  wmake script to determine the maj.min from the PV_PLUGIN_PATH
  since we have already defined the output path there with paraview
  maj.min numbering.

  Can now build with paraview from the operating system,
  provided that it has develop headers available.

      ParaView_VERSION=system

  In the etc/config.sh/paraview setup, the maj.min is taken from
  the corresponding `paraview --version` output and used when
  defining the PV_PLUGIN_PATH.

  During the build, the include path taken from `paraview-config`
  for a system installation, from the guess installation root
  of the paraview binary, or ParaView_DIR otherwise.

NB: using a system ParaView for building runTimePostProcessing is unsupported.

- these types of builds appear to have various library resolution issues
  (eg, libexpat not being loaded). Additionally, the build logic does
  not yet cover this type of use case.

- skip /, /bin, /usr/bin ... as potential filters.

- Added quoting to handle spaces in environment values in commit 50852b33
  (#1007, #1008). However, quoting is only needed for eval mode.

  In regular mode, quoting should not be part of the output, instead it
  should be done on the caller side.

- this would automatically change openfoam<digits> into maj.min.rel
  values, thus transforming openfoam1806 into a version "1.8.0.6" !

- provide edit for adjusting the ThirdParty and fallback site variables.
  This is useful when packaging into a single directory, and possibly
  without any ThirdParty dependencies.

- support '-prefix' (similar to auotconfig) as an alternative to
  '-foamInstall'. Use this prefix to set the prefix directly.
  Bypasses and disables the bash sourcing magic.

- Within strings it is preferable to use the "<etc>" instead.
  Most use cases for the old "~OpenFOAM" expansion have been obsoleted
  by the #includeEtc directive.

- file is to be sourced, non-executable.

- remove stray .keep file from tutorial case

- generalize output text wrapping, use for usage notes

- add -help-man option for generating manpage content for any OpenFOAM
  application or solver.

  bin/tools/foamCreateManpage as helper

- The changes in foamCleanPath introduced for issues (#1007, #1008)
  include quoted output of the cleaned environment variable.
  When used in foamCreateModuleInclude, the quotes make their way
  into the final environment. Avoid this by using the -sh-env
  eval format instead.

- add environment extraction of MANPATH changes

- more filtering in the sed stage to remove non-essential text.
  Terminate parsing on first appearance of -help-full option.

- have -help-full as the last entry in the list of options.
  This permits some optimizations when generating shell completions.

- simplifies things for legacyCompile

- foamCleanPath now only splits the environment variable on ':', which
  allows other directories with spaces or '(..)' etc to pass through
  without major issue.

- The filter arguments are split on whitespace, colons or semi-colons.

- With argList::noFunctionObjects() we use the logic added in
  4b933332 (issue #352)

  By removing the '-noFunctionObjects' option, we automatically
  suppress the creation of function-objects via Time (with argList
  as a parameter).
  There is generally no need in these cases for an additional

      runTime.functionObjects().off()  statement

  Use the argList::noFunctionObjects() for more direct configuration
  and reduce unnecessary clutter in the -help information.

  In previous versions, the -noFunctionObjects would have been redundant
  anyhow, so we can also just ignore it now instead.

- the backend script should not be accessible from the PATH.
  Using deprecated/ adds a level of documentation.

- since 1612, FOAM_INST_DIR and foamInstDir longer have any
  special meanings when sourcing the bashrc or cshrc files.
  Thus no need for special treatment in any of the dispatch wrappers.

  Retained FOAM_INST_DIR as (unexported) variable in etc/bashrc,
  just in case people are using patched versions of etc/bashrc
  as part of their installation.

ENH: relax prefix restrictions on foamCreateVideo (issue #904)

- shift the implicit '.' to be part of the default prefix. This allows
  things like "-image myimages_00" to work as might be expected.

- respect trailing '-', '.', '_' for the image prefix name.
  For example,

    -image press_   to accept press_*.png

- additional -mask width option (for avconv)

- The additional output generated by #calc directives in the
  controlDict or decomposeParDict causes issues for the RunFunctions
  extraction of 'application' and 'numberOfSubdomains'.

  Avoid by using -disableFunctionEntries, which also has the side-effect
  of disabling '#include'.

- Don't remove the constant/polyMesh directory if it contains a
  blockMeshDict or blockMeshDict.m4 file. Offer a reminder that
  system/ is the normal place for it.

- add additional control via a Foam::infoDetailLevel flag, which is
  supported by a 'DetailLevel' macro.  Eg,

      DetailLevel << "some information" << nl

- When infoDetailLevel is zero, the stdout for all Foam::system() calls
  are also redirected to stderr to prevent child output from
  appearing on the parent.

- close stdin before exec in system call.

- add support by using updated foamEtcFile from 1806, which also add
  the '-config' short-cut option.