linux-kernel - Re: [PATCH v1 01/30] docs: reporting-issues: mention text is best viewed rendered

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 for Android: free password hash cracker in your pocket

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

Message-ID: <09faee6c-4075-4eb7-bb2b-1c6650e3f053@infradead.org>
Date: Mon, 27 Oct 2025 14:19:54 -0700
From: Randy Dunlap <rdunlap@...radead.org>
To: Thorsten Leemhuis <linux@...mhuis.info>, Jonathan Corbet <corbet@....net>
Cc: workflows@...r.kernel.org, linux-doc@...r.kernel.org,
 regressions@...ts.linux.dev, linux-kernel@...r.kernel.org
Subject: Re: [PATCH v1 01/30] docs: reporting-issues: mention text is best
 viewed rendered



On 10/26/25 5:41 AM, Thorsten Leemhuis wrote:
> Add a comment before the step-by-step guide explaining that the document
> is best viewed in the rendered form, as there the internal links will
> work that later patches will add.
> 
> While at it change the double quotes in the license hint at the end of
> the document into single quotes, which is the preferred style.
> 
> Signed-off-by: Thorsten Leemhuis <linux@...mhuis.info>
> ---
>  Documentation/admin-guide/reporting-issues.rst | 18 ++++++++++++++----
>  1 file changed, 14 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
> index a68e6d90927471..3bc47afaf85ea0 100644
> --- a/Documentation/admin-guide/reporting-issues.rst
> +++ b/Documentation/admin-guide/reporting-issues.rst
> @@ -48,6 +48,16 @@ Once the report is out, answer any questions that come up and help where you
>  can. That includes keeping the ball rolling by occasionally retesting with newer
>  releases and sending a status update afterwards.
>  
> +..
> +   Note: If you see this note, you are reading the text's source file. You
> +   might want to switch to a rendered version: It makes it a lot easier to
> +   read and navigate this document -- especially when you want to look something
> +   up in the reference section, then jump back to where you left off.
> +..
> +   Find the latest rendered version of this text here:
> +   https://docs.kernel.org/admin-guide/reporting-issues.html
> +
> +
>  Step-by-step guide how to report issues to the kernel maintainers
>  =================================================================
>  
> @@ -1748,13 +1758,13 @@ art will lay some groundwork to improve the situation over time.
>     you spot a typo or small mistake, feel free to let him know directly and
>     he'll fix it. You are free to do the same in a mostly informal way if you
>     want to contribute changes to the text, but for copyright reasons please CC
> -   linux-doc@...r.kernel.org and "sign-off" your contribution as
> -   Documentation/process/submitting-patches.rst outlines in the section "Sign
> -   your work - the Developer's Certificate of Origin".
> +   linux-doc@...r.kernel.org and 'sign-off' your contribution as
> +   Documentation/process/submitting-patches.rst outlines in the section 'Sign
> +   your work - the Developer's Certificate of Origin'.

Can you have a single quote (Developer's) inside single quotes?
Anyway, nack on the quote marks changes.

>  ..
>     This text is available under GPL-2.0+ or CC-BY-4.0, as stated at the top
>     of the file. If you want to distribute this text under CC-BY-4.0 only,
> -   please use "The Linux kernel developers" for author attribution and link
> +   please use 'The Linux kernel developers' for author attribution and link
>     this as source:
>     https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-issues.rst
>  ..

-- 
~Randy