When writing queries to >control, flags are parsed 1st, since they are
the only required field, and they require specific compositions.  So
if the flags draw an error (on those specifics), then keyword errors
aren't reported.  This can be mildly confusing/annoying, so explain it
instead.

cc: linux-doc@vger.kernel.org
Signed-off-by: Jim Cromie <jim.cromie@gmail.com>
Reviewed-by: Louis Chauvet <louis.chauvet@bootlin.com>
---
 Documentation/admin-guide/dynamic-debug-howto.rst | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst
index 4ac18c0a1d95..63a511f2337b 100644
--- a/Documentation/admin-guide/dynamic-debug-howto.rst
+++ b/Documentation/admin-guide/dynamic-debug-howto.rst
@@ -109,9 +109,18 @@ The match-spec's select *prdbgs* from the catalog, upon which to apply
 the flags-spec, all constraints are ANDed together.  An absent keyword
 is the same as keyword "*".
 
-
-A match specification is a keyword, which selects the attribute of
-the callsite to be compared, and a value to compare against.  Possible
+Note: because the match-spec can be empty, the flags are checked 1st,
+then the pairs of keyword values.  Flag errs will hide keyword errs:
+
+  bash-5.2# ddcmd mod bar +foo
+  dyndbg: read 13 bytes from userspace
+  dyndbg: query 0: "mod bar +foo" mod:*
+  dyndbg: unknown flag 'o'
+  dyndbg: flags parse failed
+  dyndbg: processed 1 queries, with 0 matches, 1 errs
+
+So a match-spec is a keyword, which selects the attribute of the
+callsite to be compared, and a value to compare against.  Possible
 keywords are:::
 
   match-spec ::= 'func' string |
-- 
2.51.1

On Tue, Nov 18, 2025 at 01:18:14PM -0700, Jim Cromie wrote:
> -
> -A match specification is a keyword, which selects the attribute of
> -the callsite to be compared, and a value to compare against.  Possible
> +Note: because the match-spec can be empty, the flags are checked 1st,
> +then the pairs of keyword values.  Flag errs will hide keyword errs:
> +
> +  bash-5.2# ddcmd mod bar +foo
> +  dyndbg: read 13 bytes from userspace
> +  dyndbg: query 0: "mod bar +foo" mod:*
> +  dyndbg: unknown flag 'o'
> +  dyndbg: flags parse failed
> +  dyndbg: processed 1 queries, with 0 matches, 1 errs

The snippet above is shown as long-running paragraph instead, so I wrap it
in literal code block:

---- >8 ----
diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst
index fd3dbae00cfc60..7690287cbe0c79 100644
--- a/Documentation/admin-guide/dynamic-debug-howto.rst
+++ b/Documentation/admin-guide/dynamic-debug-howto.rst
@@ -112,8 +112,8 @@ The match-spec's select *prdbgs* from the catalog, upon which to apply
 the flags-spec, all constraints are ANDed together.  An absent keyword
 is the same as keyword "*".
 
-Note: because the match-spec can be empty, the flags are checked 1st,
-then the pairs of keyword values.  Flag errs will hide keyword errs:
+Note that since the match-spec can be empty, the flags are checked first,
+then the pairs of keyword values.  Flag errs will hide keyword errs::
 
   bash-5.2# ddcmd mod bar +foo
   dyndbg: read 13 bytes from userspace
@@ -122,9 +122,9 @@ then the pairs of keyword values.  Flag errs will hide keyword errs:
   dyndbg: flags parse failed
   dyndbg: processed 1 queries, with 0 matches, 1 errs
 
-So a match-spec is a keyword, which selects the attribute of the
+Hence, a match-spec is a keyword, which selects the attribute of the
 callsite to be compared, and a value to compare against.  Possible
-keywords are:::
+keywords are::
 
   match-spec ::= 'func' string |
 		 'file' string |

Thanks.

-- 
An old man doll... just what I always wanted! - Clara