improve docs on output filtering [skip ci]

docs/g4manual2rst.py

@@ -35,6 +35,7 @@ def remove_whitespace_lines_end(lines: list):
 
 idx = 0
 in_cmdblock = False
+in_guidance = False
 lastlevel = -1
 leveldiff = 0
 
@@ -52,16 +53,23 @@ def remove_whitespace_lines_end(lines: list):
         lastlevel = -1
         leveldiff = 0
     elif in_cmdblock and (line == "Guidance :"):
-        pass
-    elif in_cmdblock and (inlines[idx - 1] == "Guidance :") and not line.startswith(" " * 2):
-        outlines.extend([line, ""])
+        in_guidance = True
+    elif in_cmdblock and in_guidance and not line.startswith(" "):
+        if line.startswith("note: "):
+            outlines.extend([".. note ::", "", (" " * 4) + line[6:], ""])
+        elif line.strip() == "":
+            in_guidance = False
+        elif line != "":
+            outlines.extend([line, ""])
     elif in_cmdblock and line == " Commands : " and not inlines[idx + 1].startswith(" " * 3):
         # ignore directories with no commands.
         pass
     elif in_cmdblock and line == " Sub-directories : " and inlines[idx + 1] == " Commands : ":
         # ignore directories with no commands.
         pass
     elif in_cmdblock and line != "":
+        in_guidance = False
+
         stripped_line = line.lstrip()
         indent = math.ceil((len(line) - len(stripped_line)) / 2)
         if line.startswith(" Range of parameters :"):

src/RMGGermaniumOutputScheme.cc

@@ -207,8 +207,10 @@ void RMGGermaniumOutputScheme::DefineCommands() {
       .SetStates(G4State_Idle);
 
   fMessenger->DeclareProperty("DiscardPhotonsIfNoGermaniumEdep", fDiscardPhotonsIfNoGermaniumEdep)
-      .SetGuidance(
-          "Discard optical photons (before simulating them), if no edep in germanium detectors.")
+      .SetGuidance("Discard optical photons (before simulating them), if no edep in germanium "
+                   "detectors occurred in the same event.")
+      .SetGuidance("note: If another output scheme also requests the photons to be discarded, the "
+                   "germanium edep filter does not force the photons to be simulated.")
       .SetStates(G4State_Idle);
 }
 

src/RMGIsotopeFilterOutputScheme.cc

@@ -87,16 +87,18 @@ void RMGIsotopeFilterOutputScheme::DefineCommands() {
       "Commands for filtering event out by created isotopes.");
 
   fMessenger->DeclareMethod("AddIsotope", &RMGIsotopeFilterOutputScheme::AddIsotope)
-      .SetGuidance("Add an isotope to the list. Only events that have this isotope at any point in "
-                   "time will be persisted.")
+      .SetGuidance("Add an isotope to the list. Only events that have a track with this isotope at "
+                   "any point in time will be persisted.")
       .SetParameterName(0, "A", false, false)
       .SetParameterName(1, "Z", false, false)
       .SetStates(G4State_Idle);
 
   fMessenger
       ->DeclareProperty("DiscardPhotonsIfIsotopeNotProduced", fDiscardPhotonsIfIsotopeNotProduced)
       .SetGuidance("Discard optical photons (before simulating them), if the specified isotopes "
-                   "had not been produced in this event.")
+                   "had not been produced in the same event.")
+      .SetGuidance("note: If another output scheme also requests the photons to be discarded, the "
+                   "isotope filter does not force the photons to be simulated.")
       .SetStates(G4State_Idle);
 }