docs: clarify accept and reject filtering

docs/source/Explanation/CommandLineGuide.rst

@@ -949,7 +949,7 @@ So:
 
  - .*CAP.* means any sequence of characters with CAP somewhere in it. 
 
- - .*cap means any sequence of characters that ends with CAP.  In the case 
+ - .*cap$ means any sequence of characters that ends with CAP.  In the case
    where multiple portions of the string could match, the longest one is selected.
 
  - .*?cap same as above, but *non-greedy*, meaning the shortest match is chosen.
@@ -971,9 +971,10 @@ accept, reject and accept_unmatch
 - **baseUrl_relPath   <boolean> (default: False)**
 
 The  **accept**  and  **reject**  options process regular expressions (regexp).
-The regexp is applied to the the notification message's URL for a match.
+They are interpreted in order, and the first matching **accept** or **reject**
+rule wins.
 
-If the notification message's URL of a file matches a **reject**  pattern, the notification message
+If the filtered value for a notification message matches a **reject**  pattern, the notification message
 is acknowledged as consumed to the broker and skipped.
 
 One that matches an **accept** pattern is processed by the component.
@@ -999,8 +1000,32 @@ sequence #2::
   reject .*\.gif
 
 
-In sequence #1, all files ending in 'gif' are rejected.  In sequence #2, the accept .* (which
-accepts everything) is encountered before the reject statement, so the reject has no effect.
+In sequence #1, all files whose filtered value matches ``.*\.gif`` are rejected. In sequence #2, the
+``accept .*`` rule is encountered first and accepts everything, so the later reject statement has no effect.
+
+Python flows build a temporary filtering string from ``baseUrl + relPath``. When
+a ``sundew_extension`` header is present, and the URL has fewer than three
+colons, that temporary filtering string may have ``:<sundew_extension>``
+appended for legacy compatibility. The notification URL itself is not modified.
+The C components do not append the separate ``sundew_extension`` header:
+``cpost`` filters the pathname and ``cpump`` filters ``relPath``.
+
+Because Python flow matching starts at the beginning of the filtering string,
+filters that look for text anywhere in that string usually begin with ``.*``.
+There is no implicit ``.*`` at the end of the pattern. For example::
+
+  accept .*\.csv$
+  # matches only a filtered value ending in .csv
+
+  accept .*\.csv:.*
+  # matches a Python flow filtering string with a Sundew extension after .csv
+
+  accept .*\.csv$|.*\.csv:
+  # matches either a plain .csv ending or a .csv followed by an extension boundary
+
+Prefer filtering on the path when possible. Treat ``sundew_extension`` as legacy
+compatibility metadata and include it in filters only when the path alone is not
+specific enough.
 
 It is best practice to use server side filtering to reduce the number of notification messages sent
 to the component to a small superset of what is relevant, and perform only a fine-tuning with the
@@ -1136,10 +1161,10 @@ The option *path*  defines where to get the files on the server.
 Combined with  **accept** / **reject**  options, the user can select the
 files of interest and their directories of residence.
 
-The  **accept**  and  **reject**  options use regular expressions (regexp) to match URL.
+The  **accept**  and  **reject**  options use regular expressions (regexp) to match the filtered value.
 These options are processed sequentially.
-The URL of a file that matches a  **reject**  pattern is not published.
-Files matching an  **accept**  pattern are published.
+Files whose filtered value matches a  **reject**  pattern are not published.
+Files whose filtered value matches an  **accept**  pattern are published.
 
 The path can have some patterns. These supported patterns concern date/time .
 They are fixed...
@@ -1573,7 +1598,7 @@ at its sendTo.  It is tagged to the **accept** options defined after it.
 If another sequence of **directory**/**accept** follows in the configuration file,
 the second directory is tagged to the following accepts and so on.
 
-The  **accept/reject**  patterns apply to notification message notice url as above.
+The  **accept/reject**  patterns apply to the notification message filtering string as above.
 Here is an example, here some ordered configuration options :
 
 ::
@@ -1856,11 +1881,14 @@ sequence #2::
 
 
 .. note::
-   FIXME: does this match only files ending in 'gif' or should we add a $ to it?
-   will it match something like .gif2 ? is there an assumed .* at the end?
+   Patterns are regular expressions. Python flows use Python ``re`` patterns
+   and call ``Pattern.match()`` against the filtering string. The C components
+   use POSIX regular expressions with ``regexec()``. There is no implicit
+   ``.*`` at the end of a pattern, so use ``$`` when the match must reach the
+   end of the filtered value.
 
 
-In sequence #1, all files ending in 'gif' are rejected. In sequence #2, the 
+In sequence #1, all files whose filtered value matches ``.*\.gif`` are rejected. In sequence #2, the
 accept .* (which accepts everything) is encountered before the reject statement, 
 so the reject has no effect.  Some options have global scope, rather than being
 interpreted in order.  for thoses cases, a second declaration overrides the first.

docs/source/Reference/sr3_options.7.rst

@@ -93,11 +93,14 @@ sequence #2::
 
 
 .. note::
-   FIXME: does this match only files ending in 'gif' or should we add a $ to it?
-   will it match something like .gif2 ? is there an assumed .* at the end?
+   Patterns are regular expressions. Python flows use Python ``re`` patterns
+   and call ``Pattern.match()`` against the filtering string. The C components
+   use POSIX regular expressions with ``regexec()``. There is no implicit
+   ``.*`` at the end of a pattern, so use ``$`` when the match must reach the
+   end of the filtered value.
 
 
-In sequence #1, all files ending in 'gif' are rejected. In sequence #2, the
+In sequence #1, all files whose filtered value matches ``.*\.gif`` are rejected. In sequence #2, the
 accept .* (which accepts everything) is encountered before the reject statement,
 so the reject has no effect. Some options have global scope, rather than being
 interpreted in order. For thoses cases, the last declaration overrides the
@@ -308,9 +311,10 @@ accept, reject and acceptUnmatched
 - **acceptUnmatched   <boolean> (default: True)**
 
 The  **accept**  and  **reject**  options process regular expressions (regexp).
-The regexp is applied to the the notification message's URL for a match.
+They are interpreted in order, and the first matching **accept** or **reject**
+rule wins.
 
-If the notification message's URL of a file matches a **reject**  pattern, the notification message
+If the filtered value for a notification message matches a **reject**  pattern, the notification message
 is acknowledged as consumed to the broker and skipped.
 
 One that matches an **accept** pattern is processed by the component.
@@ -336,18 +340,43 @@ sequence #2::
   reject .*\.gif
 
 
-In sequence #1, all files ending in 'gif' are rejected.  In sequence #2, the accept .* (which
-accepts everything) is encountered before the reject statement, so the reject has no effect.
+In sequence #1, all files whose filtered value matches ``.*\.gif`` are rejected.
+In sequence #2, the ``accept .*`` rule is encountered first and accepts
+everything, so the later reject statement has no effect.
+
+Python flows build a temporary filtering string from ``baseUrl + relPath``. When
+a ``sundew_extension`` header is present, and the URL has fewer than three
+colons, that temporary filtering string may have ``:<sundew_extension>``
+appended for legacy compatibility. The notification URL itself is not modified.
+The C components do not append the separate ``sundew_extension`` header:
+``cpost`` filters the pathname and ``cpump`` filters ``relPath``.
+
+Because Python flow matching starts at the beginning of the filtering string,
+filters that look for text anywhere in that string usually begin with ``.*``.
+There is no implicit ``.*`` at the end of the pattern. For example::
+
+  accept .*\.csv$
+  # matches only a filtered value ending in .csv
+
+  accept .*\.csv:.*
+  # matches a Python flow filtering string with a Sundew extension after .csv
+
+  accept .*\.csv$|.*\.csv:
+  # matches either a plain .csv ending or a .csv followed by an extension boundary
+
+Prefer filtering on the path when possible. Treat ``sundew_extension`` as legacy
+compatibility metadata and include it in filters only when the path alone is not
+specific enough.
 
 It is best practice to use server side filtering to reduce the number of notification messages sent
 to the component to a small superset of what is relevant, and perform only a fine-tuning with the
 client side mechanisms, saving bandwidth and processing for all. More details on how
 to apply the directives follow:
 
-The  **accept**  and  **reject**  options use regular expressions (regexp) to match URL.
+The  **accept**  and  **reject**  options use regular expressions (regexp) to match the filtered value.
 These options are processed sequentially.
-The URL of a file that matches a  **reject**  pattern is not published.
-Files matching an  **accept**  pattern are published.
+Files whose filtered value matches a  **reject**  pattern are not published.
+Files whose filtered value matches an  **accept**  pattern are published.
 Again a *rename*  can be added to the *accept* option... matching products
 for that *accept* option would get renamed as described... unless the *accept* matches
 one file, the *rename* option should describe a directory into which the files
@@ -735,10 +764,10 @@ Combined with  **accept** / **reject**  options, the user can select the
 files of interest and their directories of residence (see the  **mirror**
 option for more directory settings).
 
-The  **accept**  and  **reject**  options use regular expressions (regexp) to match URL.
+The  **accept**  and  **reject**  options use regular expressions (regexp) to match the filtered value.
 These options are processed sequentially.
-The URL of a file that matches a  **reject**  pattern is never downloaded.
-One that matches an  **accept**  pattern is downloaded into the directory
+Files whose filtered value matches a  **reject**  pattern are never downloaded.
+One whose filtered value matches an  **accept**  pattern is downloaded into the directory
 declared by the closest  **directory**  option above the matching  **accept** option.
 **acceptUnmatched** is used to decide what to do when no reject or accept clauses matched.
 

docs/source/fr/Explication/GuideLigneDeCommande.rst

@@ -953,7 +953,7 @@ alors :
    En d'autres termes, faire correspondre n'importe quoi.
  - cap.* signifie toute séquence de caractères commençant par cap.
  - .*CAP.* signifie n'importe quelle séquence de caractères avec CAP quelque part dedans.
- - .*CAP signifie toute séquence de caractères qui se termine par CAP.
+ - .*CAP$ signifie toute séquence de caractères qui se termine par CAP.
  - Dans le cas où plusieurs portions de la chaîne de caractères pourraient correspondre, la plus longue est sélectionnée.
  - .*?CAP comme ci-dessus, mais *non-greedy*, ce qui signifie que le match le plus court est choisi.
  - noter que l'implantaions de regexp en C n'inclu pas le *greediness*, alors certains expressions
@@ -975,9 +975,10 @@ accept, reject and accept_unmatch
 - **baseUrl_relPath   <booléen> (par défaut: False)**
 
 Les options **accept** et **reject** traitent des expressions régulières (regexp).
-La regexp est appliquée à l'URL du message pour détecter une correspondance.
+Elles sont interprétées dans l'ordre, et la première règle **accept** ou
+**reject** qui correspond est appliquée.
 
-Si l'URL du message d'un fichier correspond à un motif **reject**, on informe
+Si la valeur filtrée d'un message correspond à un motif **reject**, on informe
 le courtier que le message a été consommé et on abandonne son traitement.
 
 Celui qui correspond à un motif **accept** est traité par le composant.
@@ -1006,9 +1007,36 @@ sequence #2::
   reject .*\.gif
 
 
-Dans la séquence #1, tous les fichiers se terminant par 'gif' sont rejetés.
-Dans la séquence #2, l'option accept .* (regexp qui veut dire accepte tout) est
-rencontré avant la déclaration de rejet, de sorte que le rejet n'a aucun effet.
+Dans la séquence #1, tous les fichiers dont la valeur filtrée correspond à ``.*\.gif`` sont rejetés.
+Dans la séquence #2, la règle ``accept .*`` est rencontrée en premier et accepte tout,
+de sorte que le rejet n'a aucun effet.
+
+Les flux Python construisent une chaîne de filtrage temporaire à partir de
+``baseUrl + relPath``. Lorsqu'un en-tête ``sundew_extension`` est présent, et
+que l'URL contient moins de trois deux-points, cette chaîne de filtrage
+temporaire peut recevoir ``:<sundew_extension>`` à la fin pour compatibilité
+ancienne. L'URL du message d'annonce elle-même n'est pas modifiée. Les
+composants C n'ajoutent pas l'en-tête séparé ``sundew_extension``: ``cpost``
+filtre le nom de chemin et ``cpump`` filtre ``relPath``.
+
+Comme la correspondance des flux Python commence au début de la chaîne de
+filtrage, les filtres qui cherchent du texte n'importe où dans cette chaîne
+commencent généralement par ``.*``. Il n'y a pas de ``.*`` implicite à la fin
+du modèle. Par exemple::
+
+  accept .*\.csv$
+  # correspond seulement à une valeur filtrée se terminant par .csv
+
+  accept .*\.csv:.*
+  # correspond à une chaîne de filtrage Python avec une extension Sundew après .csv
+
+  accept .*\.csv$|.*\.csv:
+  # correspond soit à une fin .csv simple, soit à .csv suivi d'une limite d'extension
+
+Préférez filtrer sur le chemin lorsque c'est possible. Traitez
+``sundew_extension`` comme une métadonnée de compatibilité ancienne et
+incluez-la dans les filtres seulement lorsque le chemin seul n'est pas assez
+spécifique.
 
 Il est préférable d'utiliser le filtrage côté serveur pour réduire le nombre
 de avis envoyées au composant à un petit sur-ensemble de ce qui est
@@ -1138,10 +1166,10 @@ Combiné avec les options **accept** / **reject**, l’utilisateur peut sélecti
 les fichiers d’intérêt et leurs répertoires de résidence.
 
 Les options **accept** et **reject** utilisent des expressions régulières (regexp) pour trouver
-une correspondance avec l’URL.
+une correspondance avec la valeur filtrée.
 Ces options sont traitées séquentiellement.
-L’URL d’un fichier qui correspond à un modèle **reject** n’est pas publiée.
-Les fichiers correspondant à un modèle **accept** sont publiés.
+Les fichiers dont la valeur filtrée correspond à un modèle **reject** ne sont pas publiés.
+Les fichiers dont la valeur filtrée correspond à un modèle **accept** sont publiés.
 
 Le répertoire peut avoir des modèles. Ces modèles pris en charge concernent la date/l’heure.
 Ils sont fixes...
@@ -1557,7 +1585,7 @@ L’option **répertoire** définit un autre « chemin relatif » pour le produi
 Si une autre séquence de **directory**/**accept** suit dans le fichier de configuration,
 le deuxième répertoire est marqué pour les acceptations suivantes et ainsi de suite.
 
-Les modèles **accept/reject** s’appliquent à l’URL de notification du message comme ci-dessus.
+Les modèles **accept/reject** s’appliquent à la chaîne de filtrage du message comme ci-dessus.
 Voici un exemple, voici quelques options de configuration ordonnées :
 
 ::
@@ -1846,11 +1874,15 @@ sequence #2::
 
 
 .. Note:
-   FIXME : est-ce que cela ne correspond qu'aux fichiers se terminant par'gif' ou devrions-nous y ajouter un $ ?
-   correspondra-t-il à quelque chose comme.gif2 ? y a-t-il un .* supposé à la fin ?
+   Les modèles sont des expressions régulières. Les flux Python utilisent les
+   expressions régulières Python ``re`` et appellent ``Pattern.match()`` sur la
+   chaîne de filtrage. Les composants C utilisent les expressions régulières
+   POSIX avec ``regexec()``. Il n'y a pas de ``.*`` implicite à la fin d'un
+   modèle; utilisez donc ``$`` lorsque la correspondance doit atteindre la fin
+   de la valeur filtrée.
 
 
-Dans la séquence #1, tous les fichiers se terminant par 'gif' sont rejetés. Dans la séquence #2, le
+Dans la séquence #1, tous les fichiers dont la valeur filtrée correspond à ``.*\.gif`` sont rejetés. Dans la séquence #2, le
 accept .* (qui accepte tout) est lu avant la déclaration du rejet,
 donc le rejet n’a aucun effet. Certaines options ont une portée globale, plutôt que d’être
 interprété dans l’ordre. Dans ces cas, la dernière déclaration remplace celle qu'il y avait plus tôt dans le fichier..