- 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

- 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.

- check Istream in readBool in operator>> variant (#1033)

- simplifies things for legacyCompile

- this helps for many cases outlined in issue #1007, but can also be
  useful when simply using symlinks for shorter or reorganized
  directory structures.

- with the 'cwd' optimization switch it is possible to select the
  preferred behaviour for the cwd() function.

  A value of 0 causes cwd() to return the physical directory,
  which is what getcwd() and `pwd -P` return.
  Until now, this was always the standard behaviour.

  With a value of 1, cwd() instead returns the logical directory,
  which what $PWD contains and `pwd -L` returns.
  If any of the sanity checks fail (eg, PWD points to something other
  than ".", etc), a warning is emitted and the physical cwd() is
  returned instead.

  Apart from the optical difference in the output, this additional
  control helps workaround file systems with whitespace or other
  characters in the directory that normally cause OpenFOAM to balk.
  Using a cleaner symlink elsewhere should skirt this issue.

  Eg,
      cd $HOME
      ln -s "/mounted volume/user/workdir"  workdir
      cd workdir
      # start working with OpenFOAM

- 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.

- use the dictionary 'get' methods instead of readScalar for
  additional checking

     Unchecked:  readScalar(dict.lookup("key"));
     Checked:    dict.get<scalar>("key");

- In templated classes that also inherit from a dictionary, an additional
  'template' keyword will be required. Eg,

     this->coeffsDict().template get<scalar>("key");

  For this common use case, the predefined getXXX shortcuts may be
  useful. Eg,

     this->coeffsDict().getScalar("key");

- this also removes the '-newTimes' option cruft from appearing
  everywhere. reconstructPar and redistributePar are unaffected by this
  since they define their own -newTimes option independently.

Previously the coordinate system functionality was split between
coordinateSystem and coordinateRotation. The coordinateRotation stored
the rotation tensor and handled all tensor transformations.

The functionality has now been revised and consolidated into the
coordinateSystem classes. The sole purpose of coordinateRotation
is now just to provide a selectable mechanism of how to define the
rotation tensor (eg, axis-angle, euler angles, local axes) for user
input, but after providing the appropriate rotation tensor it has
no further influence on the transformations.

--

The coordinateSystem class now contains an origin and a base rotation
tensor directly and various transformation methods.

  - The origin represents the "shift" for a local coordinate system.

  - The base rotation tensor represents the "tilt" or orientation
    of the local coordinate system in general (eg, for mapping
    positions), but may require position-dependent tensors when
    transforming vectors and tensors.

For some coordinate systems (currently the cylindrical coordinate system),
the rotation tensor required for rotating a vector or tensor is
position-dependent.

The new coordinateSystem and its derivates (cartesian, cylindrical,
indirect) now provide a uniform() method to define if the rotation
tensor is position dependent/independent.

The coordinateSystem transform and invTransform methods are now
available in two-parameter forms for obtaining position-dependent
rotation tensors. Eg,

      ... = cs.transform(globalPt, someVector);

In some cases it can be useful to use query uniform() to avoid
storage of redundant values.

      if (cs.uniform())
      {
          vector xx = cs.transform(someVector);
      }
      else
      {
          List<vector> xx = cs.transform(manyPoints, someVector);
      }

Support transform/invTransform for common data types:
   (scalar, vector, sphericalTensor, symmTensor, tensor).

====================
  Breaking Changes
====================

- These changes to coordinate systems and rotations may represent
  a breaking change for existing user coding.

- Relocating the rotation tensor into coordinateSystem itself means
  that the coordinate system 'R()' method now returns the rotation
  directly instead of the coordinateRotation. The method name 'R()'
  was chosen for consistency with other low-level entities (eg,
  quaternion).

  The following changes will be needed in coding:

      Old:  tensor rot = cs.R().R();
      New:  tensor rot = cs.R();

      Old:  cs.R().transform(...);
      New:  cs.transform(...);

  Accessing the runTime selectable coordinateRotation
  has moved to the rotation() method:

      Old:  Info<< "Rotation input: " << cs.R() << nl;
      New:  Info<< "Rotation input: " << cs.rotation() << nl;

- Naming consistency changes may also cause code to break.

      Old:  transformVector()
      New:  transformPrincipal()

  The old method name transformTensor() now simply becomes transform().

====================
  New methods
====================

For operations requiring caching of the coordinate rotations, the
'R()' method can be used with multiple input points:

       tensorField rots(cs.R(somePoints));

   and later

       Foam::transformList(rots, someVectors);

The rotation() method can also be used to change the rotation tensor
via a new coordinateRotation definition (issue #879).

The new methods transformPoint/invTransformPoint provide
transformations with an origin offset using Cartesian for both local
and global points. These can be used to determine the local position
based on the origin/rotation without interpreting it as a r-theta-z
value, for example.

================
  Input format
================

- Streamline dictionary input requirements

  * The default type is cartesian.
  * The default rotation type is the commonly used axes rotation
    specification (with e1/e2/3), which is assumed if the 'rotation'
    sub-dictionary does not exist.

    Example,

    Compact specification:

        coordinateSystem
        {
            origin  (0 0 0);
            e2      (0 1 0);
            e3      (0.5 0 0.866025);
        }

    Full specification (also accepts the longer 'coordinateRotation'
    sub-dictionary name):

        coordinateSystem
        {
            type    cartesian;
            origin  (0 0 0);

            rotation
            {
                type    axes;
                e2      (0 1 0);
                e3      (0.5 0 0.866025);
            }
        }

   This simplifies the input for many cases.

- Additional rotation specification 'none' (an identity rotation):

      coordinateSystem
      {
          origin  (0 0 0);
          rotation { type none; }
      }

- Additional rotation specification 'axisAngle', which is similar
  to the -rotate-angle option for transforming points (issue #660).
  For some cases this can be more intuitive.

  For example,

      rotation
      {
          type    axisAngle;
          axis    (0 1 0);
          angle   30;
      }
  vs.
      rotation
      {
          type    axes;
          e2      (0 1 0);
          e3      (0.5 0 0.866025);
      }

- shorter names (or older longer names) for the coordinate rotation
  specification.

     euler         EulerRotation
     starcd        STARCDRotation
     axes          axesRotation

================
  Coding Style
================
- use Foam::coordSystem namespace for categories of coordinate systems
  (cartesian, cylindrical, indirect). This reduces potential name
  clashes and makes a clearer declaration. Eg,

      coordSystem::cartesian csys_;

  The older names (eg, cartesianCS, etc) remain available via typedefs.

- added coordinateRotations namespace for better organization and
  reduce potential name clashes.

Previously had 3 possibilities for handling exposed internal faces

  1. use default "oldInternalFaces"
  2. specify -patch, to use the specified (existing) patch
  3. specify -patches, to use the geometrically closest patches

Now relaxed the restriction on -patch to allow specification of a new
(not yet existing) patch name. This improves flexibility, but won't
catch typing mistakes.

Harmonize behaviour of -patches and -patch. When -patches is used to
specify a single, non-regex patch name, it now behaves identically to
-patch. Since the getList handling for options already allows special
treatment for single parameter lists, the following will work
identically:

      subsetMesh -patch  patch0
      subsetMesh -patches patch0
      subsetMesh -patches '( patch0 )'

In the future it might be reasonable to fully combine the behaviour of
'-patch' and '-patches' and treat them as aliases for each other.

ENH: support subsetMesh on a cellZone.

- when the '-zone' option is specified, the command argument is treated
  as the name (or names) of cellZones to be selected instead of as the
  name of the cellSet.

  The command argument can be a single word, regex, or list of
  word/regex.
  Eg,

      subsetMesh -zone -patch mypatch  mixer
      subsetMesh -zone -patch mypatch  '(mixer "moving.*" )'

STYLE: simplify set handling and other code cleanup in subsetMesh

- The test condition

      [ -n "$cur" -a ... ]

  fails if $cur starts with '-le', which bash interprets as a further
  test op. Splitting the test condition solves the problem:

      [ -n "$cur" ] && [ ... ]

- 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.

General:
    * -roots, -hostRoots, -fileHandler

Specific:
    * -to <coordinateSystem> -from <coordinateSystem>

- Display -help-compat when compatibility or ignored options are available

STYLE: capitalization of options text

- instead of   dict.lookup(name) >> val;
  can use      dict.readEntry(name, val);

  for checking of input token sizes.
  This helps catch certain types of input errors:

  {

      key1 ;                // <- Missing value
      key2 1234             // <- Missing ';' terminator
      key3 val;
  }

STYLE: readIfPresent() instead of 'if found ...' in a few more places.

- 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.

- SIGFPE handling, cmake configuration

CONFIG: adjust for simplified Catalyst channel naming

- no sub-channels, select volField output based in the
  (internal | boundary) dictionary switches instead

- corrected the mass based correction and updated the misleading function
  arguments

- moved the option to the optimisation switches, e.g.:

    OptimisationSwitches
    {
        experimentalDdtCorr 1;
    }

- default remains off/no (0)

- bump to ParaView 5.5.1

- in anticipation of future change,
  hard-coded choice within bash_completion

Haakan Nilsson authored 6 years ago and Mark OLESEN committed 6 years ago

- the current working path with replacements for base-level
  OpenFOAM env variables such as FOAM_RUN, WM_PROJECT_DIR,
  WM_PROJECT_USER_DIR etc

  Can be used directly from the command-line or embedded into a
  command prompt. For example,

      PS1='$(foamPwd)\n\u\$ '

- aliases for user solver/utilities located under "$WM_PROJECT_USER_DIR":
  (ufoam, uapp, usol, uutil)

- add some notes about 'git submodule' in modules/README.md

- required if there is no system openmp and libomp or libgomp are
  only found in the clang hierarchy

STYLE: add some notes in the openmp rules.

- the _OPENMP macro is now used in low-level testing files

- The -rotate-angle option allows convenient specification of a
  rotation about an arbitrary axis. Eg, -rotate-angle '((1 1 1) 45)'

- The -origin option can be used to temporarily shift the origin
  for the rotation operations. For example,

      -origin '(0 0 1)' -rotate-angle '((1 0 0) 180)'

  for mirroring.

- include bash completion for paraFoam, and provision for using
  foamEtcFile as well.