[PATCH 1/2] Documentation: bug-hunting.rst: Remove wrong 'file:' syntax

[PATCH 1/2] Documentation: bug-hunting.rst: Remove wrong 'file:' syntax

[Petr Vorel]

Link to another document does not require 'file:', therefore it was
shown in generated html.

Preformatted text requires just ``...``.

Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
 Documentation/admin-guide/bug-hunting.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/admin-guide/bug-hunting.rst b/Documentation/admin-guide/bug-hunting.rst
index 7da0504388ece..32b1b0c3d7ee4 100644
--- a/Documentation/admin-guide/bug-hunting.rst
+++ b/Documentation/admin-guide/bug-hunting.rst
@@ -52,14 +52,14 @@ line is usually required to identify and handle the bug. Along this chapter,
 we'll refer to "Oops" for all kinds of stack traces that need to be analyzed.
 
 If the kernel is compiled with ``CONFIG_DEBUG_INFO``, you can enhance the
-quality of the stack trace by using file:`scripts/decode_stacktrace.sh`.
+quality of the stack trace by using ``scripts/decode_stacktrace.sh``.
 
 Modules linked in
 -----------------
 
 Modules that are tainted or are being loaded or unloaded are marked with
 "(...)", where the taint flags are described in
-file:`Documentation/admin-guide/tainted-kernels.rst`, "being loaded" is
+`Documentation/admin-guide/tainted-kernels.rst`, "being loaded" is
 annotated with "+", and "being unloaded" is annotated with "-".
 
 
@@ -235,7 +235,7 @@ Dave Miller)::
          mov        0x8(%ebp), %ebx         ! %ebx = skb->sk
          mov        0x13c(%ebx), %eax       ! %eax = inet_sk(sk)->opt
 
-file:`scripts/decodecode` can be used to automate most of this, depending
+``scripts/decodecode`` can be used to automate most of this, depending
 on what CPU architecture is being debugged.
 
 Reporting the bug
-- 
2.51.0

[PATCH 2/2] Documentation/trace: Fix links to other documents

[Petr Vorel]

Link to another document does not require 'file:'. Removing it fixes
links in generated html docs.

Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
 Documentation/trace/fprobe.rst      | 2 +-
 Documentation/trace/ftrace-uses.rst | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/trace/fprobe.rst b/Documentation/trace/fprobe.rst
index 06b0edad01796..1d9e0b1693494 100644
--- a/Documentation/trace/fprobe.rst
+++ b/Documentation/trace/fprobe.rst
@@ -79,7 +79,7 @@ The above is defined by including the header::
 
 Same as ftrace, the registered callbacks will start being called some time
 after the register_fprobe() is called and before it returns. See
-:file:`Documentation/trace/ftrace.rst`.
+`Documentation/trace/ftrace.rst`.
 
 Also, the unregister_fprobe() will guarantee that both enter and exit
 handlers are no longer being called by functions after unregister_fprobe()
diff --git a/Documentation/trace/ftrace-uses.rst b/Documentation/trace/ftrace-uses.rst
index e225cc46b71eb..e7cea7b1a74d9 100644
--- a/Documentation/trace/ftrace-uses.rst
+++ b/Documentation/trace/ftrace-uses.rst
@@ -253,7 +253,7 @@ If @buf is NULL and reset is set, all functions will be enabled for tracing.
 The @buf can also be a glob expression to enable all functions that
 match a specific pattern.
 
-See Filter Commands in :file:`Documentation/trace/ftrace.rst`.
+See Filter Commands in `Documentation/trace/ftrace.rst`.
 
 To just trace the schedule function:
 
-- 
2.51.0

Re: [PATCH 1/2] Documentation: bug-hunting.rst: Remove wrong 'file:' syntax

[Jonathan Corbet]

Thanks for working to improve our docs

Petr Vorel <pvorel@suse.cz> writes:

> Link to another document does not require 'file:', therefore it was
> shown in generated html.
>
> Preformatted text requires just ``...``.
>
> Signed-off-by: Petr Vorel <pvorel@suse.cz>
> ---
>  Documentation/admin-guide/bug-hunting.rst | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/admin-guide/bug-hunting.rst b/Documentation/admin-guide/bug-hunting.rst
> index 7da0504388ece..32b1b0c3d7ee4 100644
> --- a/Documentation/admin-guide/bug-hunting.rst
> +++ b/Documentation/admin-guide/bug-hunting.rst
> @@ -52,14 +52,14 @@ line is usually required to identify and handle the bug. Along this chapter,
>  we'll refer to "Oops" for all kinds of stack traces that need to be analyzed.
>  
>  If the kernel is compiled with ``CONFIG_DEBUG_INFO``, you can enhance the
> -quality of the stack trace by using file:`scripts/decode_stacktrace.sh`.
> +quality of the stack trace by using ``scripts/decode_stacktrace.sh``.
>  
>  Modules linked in
>  -----------------
>  
>  Modules that are tainted or are being loaded or unloaded are marked with
>  "(...)", where the taint flags are described in
> -file:`Documentation/admin-guide/tainted-kernels.rst`, "being loaded" is
> +`Documentation/admin-guide/tainted-kernels.rst`, "being loaded" is

Can I ask you to remove the `quotes` too?  They aren't needed and can
prevent the automarkup code from doing its thing.

Thanks,

jon

Re: [PATCH 1/2] Documentation: bug-hunting.rst: Remove wrong 'file:' syntax

[Petr Vorel]

Hi Jonathan, all,

> Thanks for working to improve our docs

> Petr Vorel <pvorel@suse.cz> writes:

> > Link to another document does not require 'file:', therefore it was
> > shown in generated html.

> > Preformatted text requires just ``...``.

> > Signed-off-by: Petr Vorel <pvorel@suse.cz>
> > ---
> >  Documentation/admin-guide/bug-hunting.rst | 6 +++---
> >  1 file changed, 3 insertions(+), 3 deletions(-)

> > diff --git a/Documentation/admin-guide/bug-hunting.rst b/Documentation/admin-guide/bug-hunting.rst
> > index 7da0504388ece..32b1b0c3d7ee4 100644
> > --- a/Documentation/admin-guide/bug-hunting.rst
> > +++ b/Documentation/admin-guide/bug-hunting.rst
> > @@ -52,14 +52,14 @@ line is usually required to identify and handle the bug. Along this chapter,
> >  we'll refer to "Oops" for all kinds of stack traces that need to be analyzed.

> >  If the kernel is compiled with ``CONFIG_DEBUG_INFO``, you can enhance the
> > -quality of the stack trace by using file:`scripts/decode_stacktrace.sh`.
> > +quality of the stack trace by using ``scripts/decode_stacktrace.sh``.

> >  Modules linked in
> >  -----------------

> >  Modules that are tainted or are being loaded or unloaded are marked with
> >  "(...)", where the taint flags are described in
> > -file:`Documentation/admin-guide/tainted-kernels.rst`, "being loaded" is
> > +`Documentation/admin-guide/tainted-kernels.rst`, "being loaded" is

> Can I ask you to remove the `quotes` too?  They aren't needed and can
> prevent the automarkup code from doing its thing.

Do you mean to really show the name of the file (no html link)?

Documentation/admin-guide/tainted-kernels.rst, "being loaded" is

This shows Documentation/admin-guide/tainted-kernels.rst in generated html.

But `Documentation/admin-guide/tainted-kernels.rst` will have link:

Text:
Tainted kernels, “being loaded”

Real XHTML:
<a class="reference internal" href="tainted-kernels.html"><span class="doc">Tainted kernels</span></a>
, “being loaded” is

I think in generated HTML is better to have clickable links than show filename.
And if one clicks to the link (https://docs.kernel.org/admin-guide/tainted-kernels.html)
it will see "Page source" link
(https://docs.kernel.org/_sources/admin-guide/tainted-kernels.rst.txt, just one
needs to remove ".txt" from URL).

Kind regards,
Petr

> Thanks,

> jon

Re: [PATCH 1/2] Documentation: bug-hunting.rst: Remove wrong 'file:' syntax

[Jonathan Corbet]

Petr Vorel <pvorel@suse.cz> writes:

> Hi Jonathan, all,
>
>> Thanks for working to improve our docs
>
>> Petr Vorel <pvorel@suse.cz> writes:
>
>> > Link to another document does not require 'file:', therefore it was
>> > shown in generated html.
>
>> > Preformatted text requires just ``...``.
>
>> > Signed-off-by: Petr Vorel <pvorel@suse.cz>
>> > ---
>> >  Documentation/admin-guide/bug-hunting.rst | 6 +++---
>> >  1 file changed, 3 insertions(+), 3 deletions(-)
>
>> > diff --git a/Documentation/admin-guide/bug-hunting.rst b/Documentation/admin-guide/bug-hunting.rst
>> > index 7da0504388ece..32b1b0c3d7ee4 100644
>> > --- a/Documentation/admin-guide/bug-hunting.rst
>> > +++ b/Documentation/admin-guide/bug-hunting.rst
>> > @@ -52,14 +52,14 @@ line is usually required to identify and handle the bug. Along this chapter,
>> >  we'll refer to "Oops" for all kinds of stack traces that need to be analyzed.
>
>> >  If the kernel is compiled with ``CONFIG_DEBUG_INFO``, you can enhance the
>> > -quality of the stack trace by using file:`scripts/decode_stacktrace.sh`.
>> > +quality of the stack trace by using ``scripts/decode_stacktrace.sh``.
>
>> >  Modules linked in
>> >  -----------------
>
>> >  Modules that are tainted or are being loaded or unloaded are marked with
>> >  "(...)", where the taint flags are described in
>> > -file:`Documentation/admin-guide/tainted-kernels.rst`, "being loaded" is
>> > +`Documentation/admin-guide/tainted-kernels.rst`, "being loaded" is
>
>> Can I ask you to remove the `quotes` too?  They aren't needed and can
>> prevent the automarkup code from doing its thing.
>
> Do you mean to really show the name of the file (no html link)?
>
> Documentation/admin-guide/tainted-kernels.rst, "being loaded" is
>
> This shows Documentation/admin-guide/tainted-kernels.rst in generated html.
>
> But `Documentation/admin-guide/tainted-kernels.rst` will have link:
>
> Text:
> Tainted kernels, “being loaded”

Not true - the quotes are not needed for the automarkup code to do its
thing.  The backticks will just have the effect of setting the title in
italics, and may interfere with the automarkup.  Better to leave them
out.

Thanks,

jon

Re: [PATCH 1/2] Documentation: bug-hunting.rst: Remove wrong 'file:' syntax

[Petr Vorel]

> Petr Vorel <pvorel@suse.cz> writes:

> > Hi Jonathan, all,

> >> Thanks for working to improve our docs

> >> Petr Vorel <pvorel@suse.cz> writes:

> >> > Link to another document does not require 'file:', therefore it was
> >> > shown in generated html.

> >> > Preformatted text requires just ``...``.

> >> > Signed-off-by: Petr Vorel <pvorel@suse.cz>
> >> > ---
> >> >  Documentation/admin-guide/bug-hunting.rst | 6 +++---
> >> >  1 file changed, 3 insertions(+), 3 deletions(-)

> >> > diff --git a/Documentation/admin-guide/bug-hunting.rst b/Documentation/admin-guide/bug-hunting.rst
> >> > index 7da0504388ece..32b1b0c3d7ee4 100644
> >> > --- a/Documentation/admin-guide/bug-hunting.rst
> >> > +++ b/Documentation/admin-guide/bug-hunting.rst
> >> > @@ -52,14 +52,14 @@ line is usually required to identify and handle the bug. Along this chapter,
> >> >  we'll refer to "Oops" for all kinds of stack traces that need to be analyzed.

> >> >  If the kernel is compiled with ``CONFIG_DEBUG_INFO``, you can enhance the
> >> > -quality of the stack trace by using file:`scripts/decode_stacktrace.sh`.
> >> > +quality of the stack trace by using ``scripts/decode_stacktrace.sh``.

> >> >  Modules linked in
> >> >  -----------------

> >> >  Modules that are tainted or are being loaded or unloaded are marked with
> >> >  "(...)", where the taint flags are described in
> >> > -file:`Documentation/admin-guide/tainted-kernels.rst`, "being loaded" is
> >> > +`Documentation/admin-guide/tainted-kernels.rst`, "being loaded" is

> >> Can I ask you to remove the `quotes` too?  They aren't needed and can
> >> prevent the automarkup code from doing its thing.

> > Do you mean to really show the name of the file (no html link)?

> > Documentation/admin-guide/tainted-kernels.rst, "being loaded" is

> > This shows Documentation/admin-guide/tainted-kernels.rst in generated html.

> > But `Documentation/admin-guide/tainted-kernels.rst` will have link:

> > Text:
> > Tainted kernels, “being loaded”

> Not true - the quotes are not needed for the automarkup code to do its
> thing.  The backticks will just have the effect of setting the title in
> italics, and may interfere with the automarkup.  Better to leave them
> out.

I'm sorry, I got confused by doc:`file.rst` syntax. Sure, I'll remove them in
v2.

Kind regards,
Petr

> Thanks,

> jon