linux-kernel - Re: [PATCH] docs: Fix backticks in README instructions

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] [day] [month] [year] [list]

Message-ID: <87zfjidc0s.fsf@trenco.lwn.net>
Date: Wed, 22 Jan 2025 09:54:59 -0700
From: Jonathan Corbet <corbet@....net>
To: carlodelos90 <carlodelos90@...il.com>, linux-doc@...r.kernel.org
Cc: linux-kernel@...r.kernel.org, carlodelos90 <carlodelos90@...il.com>
Subject: Re: [PATCH] docs: Fix backticks in README instructions

We're getting there.  I'm going to be extra-picky here to point out a
few things that are important for working with the kernel community,
though.

As Akira suggested, please use checkpatch on your patches.  Also, you
should always Cc people who have commented on previous versions.

carlodelos90 <carlodelos90@...il.com> writes:

> The commands 'make pdfdocs' and make 'htmldocs' were formatted with backticks. which caused confusion in some contexts, like GitHub. However, using tripple backticks is not universally compatible.
>
> This patch replaces backticks with normal quotes to ensure clarity and compatibility across all rendering contexts.

Please adhere to the 80-column limit for changelog messages.

Some maintainers will get really annoyed at the "This patch" wording;
changelogs should describe changes in an imperative tense.

> Signed-off-by: Carlo K <carlodelos90@...il.com>

It won't really matter for a non-copyrightable change like this, but we
do want to see a full name in the signoff.

> ---
>  README | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/README b/README
> index fd903645e6de..c1d280c622e9 100644
> --- a/README
> +++ b/README
> @@ -5,8 +5,8 @@ There are several guides for kernel developers and users. These guides can
>  be rendered in a number of formats, like HTML and PDF. Please read
>  Documentation/admin-guide/README.rst first.
>  
> -In order to build the documentation, use ``make htmldocs`` or
> -``make pdfdocs``.  The formatted documentation can also be read online at:
> +In order to build the documentation, use "make htmldocs" or
> +"make pdfdocs".  The formatted documentation can also be read online at:
>  
>      https://www.kernel.org/doc/html/latest/

The change itself is good.

Thanks,

jon