update of the in-source MusrRoot docu.

src/external/MusrRoot/doc/MusrRootDefinition.tex

@@ -58,6 +58,7 @@
 \newcommand{\tbrowser}{\texttt{TBrowser}\xspace}
 \newcommand{\tfile}{\texttt{TFile}\xspace}
 \newcommand{\tfolder}{\texttt{TFolder}\xspace}
+\newcommand{\tdir}{\texttt{TDirectory}\xspace}
 \newcommand{\tobject}{\texttt{TObject}\xspace}
 \newcommand{\tobjarray}{\texttt{TObjArray}\xspace}
 \newcommand{\tobjstring}{\texttt{TObjString}\xspace}
@@ -115,14 +116,16 @@ The \musr data acquisition systems at PSI are utilizing \midas \cite{Midas}. The
 The \musrroot file format to be described below is only using a small subset of possible \rootcern objects, namely:
 
 \begin{itemize}
- \item \tfolder: This are the top level objects in the \musrroot file.
+ \item \tfolder/\tdir: This are the top level objects in the \musrroot file.
  \item \thonef: Hold the $\mu^\pm$-decay-histograms.
- \item \tobjarray: Holding collection of header information.
+ \item \tobjarray/\tdir: Holding collection of header information.
  \item \tobjstring: Holding the content of any header information.
 \end{itemize}
 
 \noindent Since all these objects are deriving form \tobject, they will be directly accessible via the \tbrowser. For instance, the $\mu^\pm$-decay-histograms can be directly plotted, are even fitted, out of the box.
 
+\noindent \color{red}\textbf{Note Oct.\ 2025:}\color{black}\xspace Since \tfolder has bee marked as \emph{deprecated} from the ROOT team, we will switch gradually over to use \tdir instead. This will have a minimal impact on the following, as you will see. In the description to follow, the term ``folder'' will be used synonymous with ``directory''. Only if necessary it will be distinguished. 
+
 \cleardoublepage
 
 \section{\musrroot: an open $\boldsymbol{\mu}$SR file format}
@@ -172,9 +175,27 @@ RunHeader (TFolder) ---|
 \end{verbatim}
 \end{small}
 
+\newpage
+\noindent In case it is already switched to \tdir, it will look like this (default starting 2026):
+
+\begin{small}
+	\begin{verbatim}
+		RunHeader (TDirectory) ---|
+	                          |- RunInfo (TDirectory)
+	                          |- DetectorInfo (TDirectory)
+	                          |- SampleEnvironmentInfo (TDirectory)
+	                          |- MagneticFieldEnvironmentInfo (TDirectory)
+	                          |- BeamlineInfo (TDirectory)
+	\end{verbatim}
+\end{small}
+
 \noindent In brackets the object type is given. \texttt{RunInfo} contains most information relevant for the user and will be itemized Sec.\,\ref{sec:RunInfo} and \ref{sec:RunInfoRequired}. \texttt{DetectorInfo} contains detector specific information, like detector name, time zero bin, \etc (details in Sec.\,\ref{sec:DetectorInfoRequired}). \texttt{SampleEnvironmentInfo} (details in Sec.\,\ref{sec:SampleEnvironmentInfoRequired}), and \texttt{MagneticFieldEnvironmentInfo} (details in Sec.\,\ref{sec:MagneticFieldEnvironmentInfoRequired}) store additional, more detailed information concerning the sample environment. \texttt{BeamlineInfo} stores beamline relevant information (details in Sec.\,\ref{sec:BeamlineInfoRequired}).
 
-Before elaborating more on the required items within this structure, a few words on the \rootcern types used here: \texttt{RunHeader} is a \tfolder object. All the ``sub-directory'' entries are of type \tobjarray and collect items of type \tobjstring or other \tobjarray (\ie sub-directories and sub-sub-directories, etc.).
+Before elaborating more on the required items within this structure, a few words on the \rootcern types used here: \texttt{RunHeader} is a \tfolder (\emph{deprecated}) or a \tdir object. 
+\begin{itemize}
+  \item[(i)] In case of the \emph{deprected} \tfolder \texttt{RunHeader}, all the ``sub-directory'' entries are of type \tobjarray and collect items of type \tobjstring or other \tobjarray (\ie sub-directories and sub-sub-directories, etc.).
+  \item[(ii)] In case the top entry \texttt{RunHeader} is a \tdir object, all potential ``sub-directories'' are indeed \tdir objects as well. In this case, the data are represented by \tobjstring objects. 
+\end{itemize}
 
 \subsubsection{\texttt{RunInfo}}\label{sec:RunInfo}
 
@@ -314,7 +335,7 @@ header->Set("DetectorInfo/Detector001/Time Zero Bin", 3419.0);
 \end{verbatim}
 \end{shaded}
 
-\noindent To write the whole run header into a file would look something like this:
+\noindent To write the whole run header into a file would look something like this (\emph{deprecated} \tfolder version):
 
 \begin{shaded}
 \begin{verbatim}  
@@ -337,6 +358,30 @@ f->Close();
 \end{verbatim}
 \end{shaded}
 
+\newpage
+\noindent In the \tdir version it will look like this:
+
+\begin{shaded}
+	\begin{verbatim}  
+		std::unique_ptr<TFile> f = std::make_unique<TFile>(fileName, "RECREATE",
+		                                                   "write_musrRoot_runHeader");
+		if (f->IsZombie()) {
+		  return -1;
+		}
+		
+		// create the needed TDirectory object
+		TDirectory* runHeader = f->mkdir("RunHeader");
+		
+		// create the "directory" structure
+		if (header->FillDirectory(runHeader)) {
+		  runHeader->Write(); // write run header to file
+		}
+		
+		f->Close();
+	\end{verbatim}
+\end{shaded}
+
+
 
 \subsubsection{Reading a \musrroot Run Header}\label{sec:UserInterfaceReading}
 
@@ -350,10 +395,11 @@ if (f->IsZombie()) {
   return -1;
 }
 
-TFolder *runHeader = nullptr;
+// TFolder *runHeader = nullptr; // deprecated
+TDirectoryFile *runHeader = nullptr;
 f->GetObject("RunHeader", runHeader);
 if (runHeader == nullptr) {
-  cerr << endl << ">> **ERROR** Couldn't get top folder RunHeader";
+  cerr << endl << ">> **ERROR** Couldn't get top folder/directory RunHeader";
   closeFile(f);
   return -1;
 }
@@ -439,7 +485,7 @@ All validation files need to be open to the community via web-page. The URL from
 \begin{small}
 \begin{tabular}{l|l|l}
 Name           & internal type & Comment \\ \hline\hline
-Version        & \tstring      & SVN version of \tmrh \\
+Version        & \tstring      & GIT hash of \tmrh \\
 Generic Validator URL & \tstring & URL of the generic \musrroot validation xsd-file, \\
                &               & example given below $^1$. \\
 Specific Validator URL & \tstring & URL of the instrument specific validation xsd-file$^2$ \\
@@ -479,6 +525,7 @@ RedGreen Offsets & \tintvec & \eg \verb!0; 20! \\
 \noindent $^2$ \eg \verb!http://lmu.web.psi.ch/facilities/software/MusrRoot/Validation/MusrRootLEM.xsd!
 \end{small}
 
+\newpage
 \section{DetectorInfo --- Required Items} \label{sec:DetectorInfoRequired}
 
 The \texttt{DetectorInfo} is organized in a sub-tree like