[Ptests] updates the documentation

doc/developer/advance.tex

@@ -988,7 +988,7 @@ file, run it only once.
 & \textit{None}
 \\
 & \texttt{FILTER}\nscodeidxdef{Test!Directive}{FILTER}
-& Command used to filter results
+& Command reading the standard input used to filter results. In such a command, the variable \texttt{@PTEST\_ORACLE@} is set to the basename of the oracle.
 & \textit{None}
 \\
 & \texttt{MODULE}\nscodeidxdef{Test!Directive}{MODULE}
@@ -1168,6 +1168,18 @@ or
   the suite. This directive is only
   usable in a \texttt{test\_config}\codeidx{test\_config}
   configuration file.
+\item The \texttt{FILTER}\nscodeidx{Test!Directive}{FILTER} command performs
+  a transformation on the test result files before the comparison from the
+  oracles.
+  The filter command read the result from the standard input and the oracle
+  will be compared from the standard output of that command.
+  In such a command, the  \texttt{@PTEST\_ORACLE@} variable is set to the
+  basename of the oracle.
+  That allows to perform a \texttt{diff} command with the oracle of another
+  test configuration:
+  \begin{code}
+    FILTER: diff --new-file @PTEST_DIR@/oracle_configuration/@PTEST_ORACLE@
+  \end{code}
 \end{itemize}
 
 \begin{important}

ptests/ptests.ml

@@ -325,22 +325,23 @@ let example_msg =
      STDOPT: #<extra>    @[<v 0># Defines a sub-test and prepend the extra to the current option.@]@  \
      EXIT: <number>      @[<v 0># Defines the exit code required for the next sub-test commands.@]@  \
      FILTER: <cmd>       @[<v 0># Performs a transformation on the test result files before the comparison from the oracles.@ \
-     # The oracle will be compared from the standard output of the command: <cmd> <test-output-file>.@ \
+     # The oracle will be compared from the standard output of the command: cat <test-output-file> | <cmd> .@ \
      # Note: in such a command, the @@PTEST_ORACLE@@ variable is set to the basename of the oracle.@ \
      # That allows to perform a 'diff' command with the oracle of another test configuration:@ \
-     #    FILTER: diff ./oracle_configuration/@@PTEST_ORACLE@@ @]@  \
+     #    FILTER: diff --new-file @@PTEST_DIR@@/oracle_configuration/@@PTEST_ORACLE@@ @]@  \
      TIMEOUT: <delay>    @[<v 0># Set a timeout for all sub-test.@]@  \
      NOFRAMAC:           @[<v 0># Drops previous sub-test definitions and considers that there is no defined default sub-test.@]@  \
      GCC:                @[<v 0># Deprecated.@]@  \
      MACRO: <name> <def> @[<v 0># set a definition to the variable @@<name>@@.@]@  \
      @]@ \
      @[<v 1>\
-     Some variables can be used in test command:@ \
-     @@PTEST_CONFIG@@    # Test configuration suffix.@  \
-     @@PTEST_FILE@@      # Substituted by the test filename.@  \
+     Some variables can be used in test command:@  \
      @@PTEST_DIR@@       # Dirname of the test file.@  \
+     @@PTEST_FILE@@      # Substituted by the test filename.@  \
      @@PTEST_NAME@@      # Basename of the test file.@  \
      @@PTEST_NUMBER@@    # Test command number.@  \
+     @@PTEST_CONFIG@@    # Test configuration suffix.@  \
+     @@PTEST_RESULT@@    # Shorthand alias to @@PTEST_DIR@@/result@@PTEST_CONFIG@@ (the result directory dedicated to the tested configuration).@  \
      @@PTEST_ORACLE@@    # Basename of the current oracle file (variable only usable in FILTER directives).@  \
      @[<v 1>\
      Examples:@ \