align definitions scripts with typical git behavior, add docs

[lukaspie]

This change simplifies and unifies how the definitions submodule is managed by aligning the script behaviour with standard Git concepts.

Summary of changes

Previously, the script distinguished between separate commit and branch commands. These have been replaced by a single

checkout <REV>

operation, where <REV> can be any valid Git revision (commit hash, tag, or branch). This mirrors normal Git usage and removes duplicated logic.

The submodule handling is now based on the resulting repository state rather than the input type:

• If <REV> resolves to a branch, the submodule remains on that branch and the branch is written to .gitmodules, enabling branch tracking.
• If <REV> resolves to a commit or tag, the submodule is left in detached HEAD state and any branch tracking entry is removed.

Behaviour of the commands

The script now clearly separates three operations:

• update: Updates the submodule to the latest commit of the tracked branch using git submodule update --remote.
• checkout <REV>: Checks out an arbitrary revision. Branch checkouts enable tracking via .gitmodules, while commits and tags result in a detached checkout.
  reset: Restores the submodule to the exact commit recorded in the superproject. This explicitly removes branch tracking configuration and forces checkout of the pinned revision, ensuring that reset is independent of the default branch or latest upstream state.

In addition, documentation about the NeXus definitions and how they are integrated in pynxtools is added.

[mkuehbach]

Useful

[mkuehbach]

Comments were addressed appropriately.