From: Thorsten Leemhuis <linux@leemhuis.info>
To: Jonathan Corbet <corbet@lwn.net>,
linux-doc@vger.kernel.org,
Linus Torvalds <torvalds@linux-foundation.org>
Cc: workflows@vger.kernel.org,
Linux Kernel Mailing List <linux-kernel@vger.kernel.org>,
Randy Dunlap <rdunlap@infradead.org>,
regressions@lists.linux.dev,
Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
Lukas Bulwahn <lukas.bulwahn@gmail.com>
Subject: Re: [PATCH v4 3/3] docs: reporting-issues.rst: link new document about regressions
Date: Wed, 2 Feb 2022 07:08:20 +0100 [thread overview]
Message-ID: <7a1e66cc-a1c5-54c7-ca7d-04a389beb8b2@leemhuis.info> (raw)
In-Reply-To: <87bkzq5fxu.fsf@meer.lwn.net>
On 02.02.22 00:23, Jonathan Corbet wrote:
> Thorsten Leemhuis <linux@leemhuis.info> writes:
>
>> Make Documentation/admin-guide/reporting-issues.rst point to the newly
>> created document about regressions
>> (Documentation/admin-guide/regressions-users.rst). This allows to
>> shorten a few explanations the new document describes better and in more
>> detail.
>>
>> While at it move the copyright hint to the end of the file, as suggested
>> during review of the new documents about regressions.
>>
>> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
>> ---
>> .../admin-guide/reporting-issues.rst | 60 +++++++++----------
>> 1 file changed, 29 insertions(+), 31 deletions(-)
>
> [...]
>
>> +You deal with a regression if some application or practical use case running
>> +fine with one Linux kernel works worse or not at all with a newer version
>> +compiled using a similar configuration. The document
>> +'Documentation/admin-guide/regressions-users.rst' explains this in more detail.
>
> Some of those quotes around file names are still sneaking in.
I did that on purpose here, as the file right now uses single quotes for
doc references almost everywhere and I thought I better stick to its
style -- especially as one such a quoted references is pretty close by
in this case, so it would look odd to quote one but not the other:
```
[...] compiled using a similar configuration. The document
'Documentation/admin-guide/regressions-users.rst' explains this in more
detail.
It also provides a good deal of other information about regressions you
might
want to be aware of; it for example explains how to add your issue to
the list
of tracked regressions, to ensure it won't fall through the cracks.
What qualifies as security issue is left to your judgment. Consider reading
'Documentation/admin-guide/security-bugs.rst' before proceeding, as it
[...]
```
Stupid me just forgot to use single quotes for the second link to
Documentation/admin-guide/regressions-users.rst. Will fix this up :-/
That being said: in a mail on Monday I already raised the issue like
this (slightly reworded):
----
I noticed I quoted internal references in reporting-issues.rst quite
often. IMHO it improves readability sometimes (it depends a lot on the
title of the target document), as can be seen in this example.
The source text looks like this:
```
If your kernel is tainted, study
'Documentation/admin-guide/tainted-kernels.rst' to find out why.
[...]
To find the change there is a process called 'bisection' which the
document 'Documentation/admin-guide/bug-bisect.rst' describes in detail.
```
After processing to HTML the text looks like this:
```
If your kernel is tainted, study ‘Tainted kernels‘ to find out why.
[...]
To find the change there is a process called ‘bisection’ which the
document ‘Bisecting a bug’ describes in detail.
```
Sure, "Tainted kernels" and "Bisecting a bug" are links and hence
displayed differently by the browser, but I think the quotes help. But YMMV.
I sooner or later hope to improve and fix a few things in
reporting-issues.rst anyway. Let me know if I should take the
opportunity to remove the single quotes then.
----
So I'd say: I add two more quoted doc links to the file now and fix this
up later, if you still think removing the quotes is a good idea. Or do
you want me to remove the single quotes now in that patch (or a separate
one?)? It's not a big deal, there are only about 10 docs references.
Ciao, Thorsten
prev parent reply other threads:[~2022-02-02 6:53 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-02-01 10:26 [PATCH v4 0/3] docs: add two texts covering regressions Thorsten Leemhuis
2022-02-01 10:26 ` [PATCH v4 1/3] docs: add two documents about regression handling Thorsten Leemhuis
2022-02-01 23:13 ` Jonathan Corbet
2022-02-02 10:05 ` Thorsten Leemhuis
2022-02-15 18:49 ` Thorsten Leemhuis
2022-02-01 10:26 ` [PATCH v4 2/3] docs: regressions*rst: rules of thumb for handling regressions Thorsten Leemhuis
2022-02-01 23:21 ` Jonathan Corbet
2022-02-02 9:47 ` Thorsten Leemhuis
2022-02-01 10:26 ` [PATCH v4 3/3] docs: reporting-issues.rst: link new document about regressions Thorsten Leemhuis
2022-02-01 23:23 ` Jonathan Corbet
2022-02-02 6:08 ` Thorsten Leemhuis [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=7a1e66cc-a1c5-54c7-ca7d-04a389beb8b2@leemhuis.info \
--to=linux@leemhuis.info \
--cc=corbet@lwn.net \
--cc=gregkh@linuxfoundation.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=lukas.bulwahn@gmail.com \
--cc=rdunlap@infradead.org \
--cc=regressions@lists.linux.dev \
--cc=torvalds@linux-foundation.org \
--cc=workflows@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.