linux-kernel - Re: [PATCH 13/34] docs: dev-tools: testing-overview.rst: avoid using ReSt :doc:`foo` markup

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <CABVgOS=vcZX5w4tyQg9nsDyJ0sKdS-McgVNzVd9mqeLy1NTCFA@mail.gmail.com>
Date:   Sat, 5 Jun 2021 23:43:55 +0800
From:   David Gow <davidgow@...gle.com>
To:     Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc:     Jonathan Corbet <corbet@....net>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Daniel Latypov <dlatypov@...gle.com>,
        Marco Elver <elver@...gle.com>,
        Linux Kernel Mailing List <linux-kernel@...r.kernel.org>
Subject: Re: [PATCH 13/34] docs: dev-tools: testing-overview.rst: avoid using
 ReSt :doc:`foo` markup

On Sat, Jun 5, 2021 at 9:18 PM Mauro Carvalho Chehab
<mchehab+huawei@...nel.org> wrote:
>
> The :doc:`foo` tag is auto-generated via automarkup.py.
> So, use the filename at the sources, instead of :doc:`foo`.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
> ---

Hmm... I'd originally wanted this to read more like the name of the
tool than the path to the doc file, but given the :doc: prefix and
backticks are equally ugly, and no less confusing to the plain-text
reader than the filename, I'm happy to have this changed. Particularly
if we're standardising on this across the kernel documentation.

Reviewed-by: David Gow <davidgow@...gle.com>


-- David

>  Documentation/dev-tools/testing-overview.rst | 16 ++++++++--------
>  1 file changed, 8 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/dev-tools/testing-overview.rst b/Documentation/dev-tools/testing-overview.rst
> index b5b46709969c..65feb81edb14 100644
> --- a/Documentation/dev-tools/testing-overview.rst
> +++ b/Documentation/dev-tools/testing-overview.rst
> @@ -71,15 +71,15 @@ can be used to verify that a test is executing particular functions or lines
>  of code. This is useful for determining how much of the kernel is being tested,
>  and for finding corner-cases which are not covered by the appropriate test.
>
> -:doc:`gcov` is GCC's coverage testing tool, which can be used with the kernel
> -to get global or per-module coverage. Unlike KCOV, it does not record per-task
> -coverage. Coverage data can be read from debugfs, and interpreted using the
> -usual gcov tooling.
> +Documentation/dev-tools/gcov.rst is GCC's coverage testing tool, which can be
> +used with the kernel to get global or per-module coverage. Unlike KCOV, it
> +does not record per-task coverage. Coverage data can be read from debugfs,
> +and interpreted using the usual gcov tooling.
>
> -:doc:`kcov` is a feature which can be built in to the kernel to allow
> -capturing coverage on a per-task level. It's therefore useful for fuzzing and
> -other situations where information about code executed during, for example, a
> -single syscall is useful.
> +Documentation/dev-tools/kcov.rst is a feature which can be built in to the
> +kernel to allow capturing coverage on a per-task level. It's therefore useful
> +for fuzzing and other situations where information about code executed during,
> +for example, a single syscall is useful.
>
>
>  Dynamic Analysis Tools
> --
> 2.31.1
>