[PATCH] docs/trace: fix a label of boottime-trace

[PATCH] docs/trace: fix a label of boottime-trace

[Yanteng Si]

Since 559789539255 ("Documentation: tracing: Add histogram syntax to boot-time tracing") which
introduced a warning:

linux/Documentation/trace/boottime-trace.rst:136: WARNING: undefined label: histogram (if the link has no caption the label must precede a section header)

Replace with:
              :xxx: path

Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
 Documentation/trace/boottime-trace.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/trace/boottime-trace.rst b/Documentation/trace/boottime-trace.rst
index 6dcfbc64014d..efb75ec5bf48 100644
--- a/Documentation/trace/boottime-trace.rst
+++ b/Documentation/trace/boottime-trace.rst
@@ -133,7 +133,7 @@ action option, there are tree-style options under per-event 'hist' subkey
 for the histogram actions. For the detail of the each parameter,
 please read the event histogram document [3]_.
 
-.. [3] See :ref:`Documentation/trace/histogram.rst <histogram>`
+.. [3] See :histogram: Documentation/trace/histogram.rst
 
 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]keys = KEY1[, KEY2[...]]
   Set histogram key parameters. (Mandatory)
-- 
2.27.0

Re: [PATCH] docs/trace: fix a label of boottime-trace

[Steven Rostedt]

On Thu,  9 Dec 2021 17:11:33 +0800
Yanteng Si <siyanteng01@gmail.com> wrote:

> diff --git a/Documentation/trace/boottime-trace.rst b/Documentation/trace/boottime-trace.rst
> index 6dcfbc64014d..efb75ec5bf48 100644
> --- a/Documentation/trace/boottime-trace.rst
> +++ b/Documentation/trace/boottime-trace.rst
> @@ -133,7 +133,7 @@ action option, there are tree-style options under per-event 'hist' subkey
>  for the histogram actions. For the detail of the each parameter,
>  please read the event histogram document [3]_.
>  
> -.. [3] See :ref:`Documentation/trace/histogram.rst <histogram>`
> +.. [3] See :histogram: Documentation/trace/histogram.rst
>  
>  ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]keys = KEY1[, KEY2[...]]
>    Set histogram key parameters. (Mandatory)

I have no idea if this works or not, so Jon, if you are fine with it, you
can take it through your tree.

-- Steve

Re: [PATCH] docs/trace: fix a label of boottime-trace

[Akira Yokosawa]

Hi,

On Thu,  9 Dec 2021 17:11:33 +0800, Yanteng Si wrote:
> Since 559789539255 ("Documentation: tracing: Add histogram syntax to boot-time tracing") which
> introduced a warning:
> 
> linux/Documentation/trace/boottime-trace.rst:136: WARNING: undefined label: histogram (if the link has no caption the label must precede a section header)
> 
> Replace with:
>               :xxx: path
> 
> Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
> ---
>  Documentation/trace/boottime-trace.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/trace/boottime-trace.rst b/Documentation/trace/boottime-trace.rst
> index 6dcfbc64014d..efb75ec5bf48 100644
> --- a/Documentation/trace/boottime-trace.rst
> +++ b/Documentation/trace/boottime-trace.rst
> @@ -133,7 +133,7 @@ action option, there are tree-style options under per-event 'hist' subkey
>  for the histogram actions. For the detail of the each parameter,
>  please read the event histogram document [3]_.
>  
> -.. [3] See :ref:`Documentation/trace/histogram.rst <histogram>`
> +.. [3] See :histogram: Documentation/trace/histogram.rst

This does not look like a right change.
Where did that ":histogram:" come from?

        Thanks, Akira

>  
>  ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]keys = KEY1[, KEY2[...]]
>    Set histogram key parameters. (Mandatory)
> -- 
> 2.27.0

Re: [PATCH] docs/trace: fix a label of boottime-trace

[Jonathan Corbet]

Yanteng Si <siyanteng01@gmail.com> writes:

> Since 559789539255 ("Documentation: tracing: Add histogram syntax to boot-time tracing") which
> introduced a warning:
>
> linux/Documentation/trace/boottime-trace.rst:136: WARNING: undefined label: histogram (if the link has no caption the label must precede a section header)
>
> Replace with:
>               :xxx: path
>
> Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
> ---
>  Documentation/trace/boottime-trace.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/trace/boottime-trace.rst b/Documentation/trace/boottime-trace.rst
> index 6dcfbc64014d..efb75ec5bf48 100644
> --- a/Documentation/trace/boottime-trace.rst
> +++ b/Documentation/trace/boottime-trace.rst
> @@ -133,7 +133,7 @@ action option, there are tree-style options under per-event 'hist' subkey
>  for the histogram actions. For the detail of the each parameter,
>  please read the event histogram document [3]_.
>  
> -.. [3] See :ref:`Documentation/trace/histogram.rst <histogram>`
> +.. [3] See :histogram: Documentation/trace/histogram.rst

I don't see that this is going to work either.  Is there any reason not
to just make the text read:

   please read the event histogram document Documentation/trace/histogram.rst

and let automarkup link it in?

Thanks,

jon

Re: [PATCH] docs/trace: fix a label of boottime-trace

[Steven Rostedt]

On Thu, 9 Dec 2021 23:37:16 +0900
Akira Yokosawa <akiyks@gmail.com> wrote:

> > --- a/Documentation/trace/boottime-trace.rst
> > +++ b/Documentation/trace/boottime-trace.rst
> > @@ -133,7 +133,7 @@ action option, there are tree-style options under per-event 'hist' subkey
> >  for the histogram actions. For the detail of the each parameter,
> >  please read the event histogram document [3]_.
> >  
> > -.. [3] See :ref:`Documentation/trace/histogram.rst <histogram>`
> > +.. [3] See :histogram: Documentation/trace/histogram.rst  
> 
> This does not look like a right change.
> Where did that ":histogram:" come from?

I'm guessing from "<histogram>" that's in the line being deleted.

-- Steve

Re: [PATCH] docs/trace: fix a label of boottime-trace

[Masami Hiramatsu]

On Thu, 09 Dec 2021 07:50:07 -0700
Jonathan Corbet <corbet@lwn.net> wrote:

> Yanteng Si <siyanteng01@gmail.com> writes:
> 
> > Since 559789539255 ("Documentation: tracing: Add histogram syntax to boot-time tracing") which
> > introduced a warning:
> >
> > linux/Documentation/trace/boottime-trace.rst:136: WARNING: undefined label: histogram (if the link has no caption the label must precede a section header)
> >
> > Replace with:
> >               :xxx: path
> >
> > Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
> > ---
> >  Documentation/trace/boottime-trace.rst | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> >
> > diff --git a/Documentation/trace/boottime-trace.rst b/Documentation/trace/boottime-trace.rst
> > index 6dcfbc64014d..efb75ec5bf48 100644
> > --- a/Documentation/trace/boottime-trace.rst
> > +++ b/Documentation/trace/boottime-trace.rst
> > @@ -133,7 +133,7 @@ action option, there are tree-style options under per-event 'hist' subkey
> >  for the histogram actions. For the detail of the each parameter,
> >  please read the event histogram document [3]_.
> >  
> > -.. [3] See :ref:`Documentation/trace/histogram.rst <histogram>`
> > +.. [3] See :histogram: Documentation/trace/histogram.rst
> 
> I don't see that this is going to work either.  Is there any reason not
> to just make the text read:
> 
>    please read the event histogram document Documentation/trace/histogram.rst
> 
> and let automarkup link it in?

Hmm, I think we need the following change instead of this.
(the label is not in this document, but in the target document.)

diff --git a/Documentation/trace/histogram.rst b/Documentation/trace/histogram.rst
index 859fd1b76c63..ea722eae2810 100644
--- a/Documentation/trace/histogram.rst
+++ b/Documentation/trace/histogram.rst
@@ -1,3 +1,5 @@
+.. _histogram:
+
 ================
 Event Histograms
 ================

-- 
Masami Hiramatsu <mhiramat@kernel.org>

Re: [PATCH] docs/trace: fix a label of boottime-trace

[Jonathan Corbet]

Masami Hiramatsu <mhiramat@kernel.org> writes:

> On Thu, 09 Dec 2021 07:50:07 -0700
> Jonathan Corbet <corbet@lwn.net> wrote:
>
>> I don't see that this is going to work either.  Is there any reason not
>> to just make the text read:
>> 
>>    please read the event histogram document Documentation/trace/histogram.rst
>> 
>> and let automarkup link it in?
>
> Hmm, I think we need the following change instead of this.
> (the label is not in this document, but in the target document.)
>
> diff --git a/Documentation/trace/histogram.rst b/Documentation/trace/histogram.rst
> index 859fd1b76c63..ea722eae2810 100644
> --- a/Documentation/trace/histogram.rst
> +++ b/Documentation/trace/histogram.rst
> @@ -1,3 +1,5 @@
> +.. _histogram:
> +

That would work, but it will have essentially the same effect as what I
suggested while adding extra markup.  I think we can leave the label out
and keep the plain-text a little cleaner.

Thanks,

jon

Re: [PATCH] docs/trace: fix a label of boottime-trace

[Masami Hiramatsu]

On Thu, 09 Dec 2021 09:59:49 -0700
Jonathan Corbet <corbet@lwn.net> wrote:

> Masami Hiramatsu <mhiramat@kernel.org> writes:
> 
> > On Thu, 09 Dec 2021 07:50:07 -0700
> > Jonathan Corbet <corbet@lwn.net> wrote:
> >
> >> I don't see that this is going to work either.  Is there any reason not
> >> to just make the text read:
> >> 
> >>    please read the event histogram document Documentation/trace/histogram.rst
> >> 
> >> and let automarkup link it in?
> >
> > Hmm, I think we need the following change instead of this.
> > (the label is not in this document, but in the target document.)
> >
> > diff --git a/Documentation/trace/histogram.rst b/Documentation/trace/histogram.rst
> > index 859fd1b76c63..ea722eae2810 100644
> > --- a/Documentation/trace/histogram.rst
> > +++ b/Documentation/trace/histogram.rst
> > @@ -1,3 +1,5 @@
> > +.. _histogram:
> > +
> 
> That would work, but it will have essentially the same effect as what I
> suggested while adding extra markup.  I think we can leave the label out
> and keep the plain-text a little cleaner.

Indeed. If automarkup makes a link, we don't need the labels.
BTW, it is nicer to brace it.

    please read the event histogram document (Documentation/trace/histogram.rst)

Then, it will be

    please read the event histogram document (Event Histograms)


Yanteng, can you update this patch just putting the document file
as above?

Thank you,

-- 
Masami Hiramatsu <mhiramat@kernel.org>

Re: [PATCH] docs/trace: fix a label of boottime-trace

[yanteng si]

Masami Hiramatsu <mhiramat@kernel.org> 于2021年12月10日周五 08:09写道：
>
> On Thu, 09 Dec 2021 09:59:49 -0700
> Jonathan Corbet <corbet@lwn.net> wrote:
>
> > Masami Hiramatsu <mhiramat@kernel.org> writes:
> >
> > > On Thu, 09 Dec 2021 07:50:07 -0700
> > > Jonathan Corbet <corbet@lwn.net> wrote:
> > >
> > >> I don't see that this is going to work either.  Is there any reason not
> > >> to just make the text read:
> > >>
> > >>    please read the event histogram document Documentation/trace/histogram.rst
> > >>
> > >> and let automarkup link it in?
> > >
> > > Hmm, I think we need the following change instead of this.
> > > (the label is not in this document, but in the target document.)
> > >
> > > diff --git a/Documentation/trace/histogram.rst b/Documentation/trace/histogram.rst
> > > index 859fd1b76c63..ea722eae2810 100644
> > > --- a/Documentation/trace/histogram.rst
> > > +++ b/Documentation/trace/histogram.rst
> > > @@ -1,3 +1,5 @@
> > > +.. _histogram:
> > > +
> >
> > That would work, but it will have essentially the same effect as what I
> > suggested while adding extra markup.  I think we can leave the label out
> > and keep the plain-text a little cleaner.
>
> Indeed. If automarkup makes a link, we don't need the labels.
> BTW, it is nicer to brace it.
>
>     please read the event histogram document (Documentation/trace/histogram.rst)
>
> Then, it will be
>
>     please read the event histogram document (Event Histograms)
>
>
> Yanteng, can you update this patch just putting the document file
> as above?
Will do!

Thanks,
Yanteng