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

[Petr Vorel <pvorel@suse.cz>]

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