The RTLA common options documentation uses several Sphinx substitution
placeholders (|threshold|, |tool|, |thresharg|, |tracer|, |actionsperf|)
that are not defined anywhere in the tree. This causes the htmldocs
build to fail with multiple "Undefined substitution" errors.

Replace these undefined substitutions with plain text or generic
placeholders (<tool>, <threshold-option>, <tracer>) to ensure the
documentation builds cleanly while preserving the intended meaning of
the examples.

Signed-off-by: Sameeksha Sankpal <sameekshasankpal@gmail.com>
---
 Documentation/tools/rtla/common_options.rst | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/tools/rtla/common_options.rst b/Documentation/tools/rtla/common_options.rst
index 77ef35d3f831..bd5a6f32f5bf 100644
--- a/Documentation/tools/rtla/common_options.rst
+++ b/Documentation/tools/rtla/common_options.rst
@@ -56,7 +56,7 @@
 **--on-threshold** *action*
 
         Defines an action to be executed when tracing is stopped on a latency threshold
-        specified by |threshold|.
+        specified by the threshold value.
 
         Multiple --on-threshold actions may be specified, and they will be executed in
         the order they are provided. If any action fails, subsequent actions in the list
@@ -85,17 +85,17 @@
 
         Example:
 
-        $ rtla |tool| |thresharg| 20 --on-threshold trace
-        --on-threshold shell,command="grep ipi_send |tracer|\_trace.txt"
+        $ rtla <tool> <threshold-option> 20 --on-threshold trace
+        --on-threshold shell,command="grep ipi_send <tracer>\_trace.txt"
         --on-threshold signal,num=2,pid=parent
 
-        This will save a trace with the default filename "|tracer|\_trace.txt", print its
+        This will save a trace with the default filename "<tracer>\_trace.txt", print its
         lines that contain the text "ipi_send" on standard output, and send signal 2
         (SIGINT) to the parent process.
 
         Performance Considerations:
 
-        |actionsperf|
+        Note: Executing actions during tracing may introduce additional performance overhead depending on system load, system configuration, and the number of actions triggered.
 
 **--on-end** *action*
 
@@ -110,7 +110,7 @@
 
         Example:
 
-        $ rtla |tool| -d 5s --on-end trace
+        $ rtla <tool> -d 5s --on-end trace
 
         This runs rtla with the default options, and saves trace output at the end.
 
-- 
2.43.0

Hi,

On 11/28/25 7:18 AM, Sameeksha Sankpal wrote:
> The RTLA common options documentation uses several Sphinx substitution
> placeholders (|threshold|, |tool|, |thresharg|, |tracer|, |actionsperf|)
> that are not defined anywhere in the tree. This causes the htmldocs
> build to fail with multiple "Undefined substitution" errors.
> 
> Replace these undefined substitutions with plain text or generic
> placeholders (<tool>, <threshold-option>, <tracer>) to ensure the
> documentation builds cleanly while preserving the intended meaning of
> the examples.
> 
> Signed-off-by: Sameeksha Sankpal <sameekshasankpal@gmail.com>
> ---
>  Documentation/tools/rtla/common_options.rst | 12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/tools/rtla/common_options.rst b/Documentation/tools/rtla/common_options.rst
> index 77ef35d3f831..bd5a6f32f5bf 100644
> --- a/Documentation/tools/rtla/common_options.rst
> +++ b/Documentation/tools/rtla/common_options.rst

Does this patch apply to the mainline (Linus) kernel?
This is already fixed in linux-next or docs-next.
You should usually check -next trees for fixes like this.

See:

commit 96b546c241b1
Author: Gopi Krishna Menon <krishnagopi487@gmail.com>
Date:   Mon Oct 13 16:27:20 2025 +0700
    Documentation/rtla: rename common_xxx.rst files to common_xxx.txt

Thanks.
-- 
~Randy

On Fri, Nov 28, 2025 at 01:43:41PM -0800, Randy Dunlap wrote:
> Hi,
> 
> On 11/28/25 7:18 AM, Sameeksha Sankpal wrote:
> > The RTLA common options documentation uses several Sphinx substitution
> > placeholders (|threshold|, |tool|, |thresharg|, |tracer|, |actionsperf|)
> > that are not defined anywhere in the tree. This causes the htmldocs
> > build to fail with multiple "Undefined substitution" errors.
> > 
> > Replace these undefined substitutions with plain text or generic
> > placeholders (<tool>, <threshold-option>, <tracer>) to ensure the
> > documentation builds cleanly while preserving the intended meaning of
> > the examples.
> > 
> > Signed-off-by: Sameeksha Sankpal <sameekshasankpal@gmail.com>
> > ---
> >  Documentation/tools/rtla/common_options.rst | 12 ++++++------
> >  1 file changed, 6 insertions(+), 6 deletions(-)
> > 
> > diff --git a/Documentation/tools/rtla/common_options.rst b/Documentation/tools/rtla/common_options.rst
> > index 77ef35d3f831..bd5a6f32f5bf 100644
> > --- a/Documentation/tools/rtla/common_options.rst
> > +++ b/Documentation/tools/rtla/common_options.rst
> 
> Does this patch apply to the mainline (Linus) kernel?
> This is already fixed in linux-next or docs-next.
> You should usually check -next trees for fixes like this.
> 
> See:
> 
> commit 96b546c241b1
> Author: Gopi Krishna Menon <krishnagopi487@gmail.com>
> Date:   Mon Oct 13 16:27:20 2025 +0700
>     Documentation/rtla: rename common_xxx.rst files to common_xxx.txt

The warnings are found on master, though, yet 96b546c241b1 is in docs-next
instead. I guess I can stable-backport it to 6.18 once it is released (in next
week).

Thanks.

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