[PATCH] docs: Fix backticks in README instructions

[PATCH] docs: Fix backticks in README instructions

[carlodelos90]

The commands `make pdfdocs` and `make htmldocs` were incorrectly formatted
with only two backticks, which caused confusion and didn't render properly
in some contexts. This change updates the documentation to use triple
backticks for consistency and clarity.

Signed-off-by: carlodelos90 <carlodelos90@gmail.com>
---
 README | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README b/README
index fd903645e6de..21294cc9fd04 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/
 
-- 
2.39.5 (Apple Git-154)

Re: [PATCH] docs: Fix backticks in README instructions

[Akira Yokosawa]

Hello,

carlodelos90 wrote:
> The commands `make pdfdocs` and `make htmldocs` were incorrectly formatted
> with only two backticks, which caused confusion and didn't render properly
> in some contexts.

Do you mean:

... One example is GitHub where top-level README is assumed to be in
the GitHub dialect of Markdown.

???

>                   This change updates the documentation to use triple
> backticks for consistency and clarity.

Obviously, triple backticks don't work in other contexts.

So your "fix" breaks assumption of others.

I think GitHub can render its README pane in reST format if you add a
symlink of README.rst -> README.  No?

> 
> Signed-off-by: carlodelos90 <carlodelos90@gmail.com>

Do You normally sign a contract using the name of "carlodelos90"?

Signed-off-by should be regarded as a formal statement that you
have the right to submit a patch.

See "Sign your work - the Developer’s Certificate of Origin"
in Documentation/process/submitting-patches.rst.

In your future submissions, please use your real name for signing off
unless you have a good reason not to do so.

I'm not sure if adding a symlink for the sake of GitHub compatibility
is acceptable or not.  But it looks to me worth an attempt at least.

        Thanks, Akira

Re: [PATCH] docs: Fix backticks in README instructions

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

> carlodelos90 wrote:
>> The commands `make pdfdocs` and `make htmldocs` were incorrectly formatted
>> with only two backticks, which caused confusion and didn't render properly
>> in some contexts.
>
> Do you mean:
>
> ... One example is GitHub where top-level README is assumed to be in
> the GitHub dialect of Markdown.
>
> ???

Indeed, "some contexts" is a uselessly vague description; please say
what the actual problem is.

>>                   This change updates the documentation to use triple
>> backticks for consistency and clarity.
>
> Obviously, triple backticks don't work in other contexts.
>
> So your "fix" breaks assumption of others.
>
> I think GitHub can render its README pane in reST format if you add a
> symlink of README.rst -> README.  No?

The thing is ... *we* don't render that file as RST either.  So perhaps
the best solution is just to use normal "quotes" rather than any sort of
markup?

Thanks,

jon

[PATCH] docs: Fix backticks in README instructions

[carlodelos90]

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.

Signed-off-by: Carlo K <carlodelos90@gmail.com>
---
 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/
 
-- 
2.39.5 (Apple Git-154)

Re: [PATCH] docs: Fix backticks in README instructions

[Akira Yokosawa]

[+CC: Jon]
Hi,

Not a comment on the patch contents, just nitpicking.

carlodelos90 wrote:
> 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.
> 
> Signed-off-by: Carlo K <carlodelos90@gmail.com>

I'd suggest you to run scripts/checkpatch.pl on your patch.
It is good in catching issues in patches especially from new contributors.

Besides that, you have failed to denote a patch version.

I'd say [PATCH v2] in the subject of this patch.  Next one will be v3.

As we are in the middle of the merge window, I'd suggest you to take
some time and skim through documents under Documentation/process/,
especially submitting-patches.rst and submit-checklist.rst among others,
before submitting a v3.

Questions are always welcome!

Thanks, Akira

Re: [PATCH] docs: Fix backticks in README instructions

[Jonathan Corbet]

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@gmail.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@gmail.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