Re: [PATCH v1, RFC] docs: reporting-issues.rst: tone down 'test vanilla mainline' a little

On 16.03.21 18:56, Thorsten Leemhuis wrote:

On 15.03.21 21:20, Jonathan Corbet wrote:

quoted

Thorsten Leemhuis [off-list ref] writes:

quoted

 Anything that could be done to
make it more concise going forward would be more than welcome.

Yeah, will think about it, especially WRT to the other patch you looked
at. Maybe I can come up with something. But no promises, I put a lot of
thought into the problem already.

FWIW, just sent out a new series that IMHO at least is a small step in
the right direction:

https://lore.kernel.org/linux-doc/cover.1616181657.git.linux@leemhuis.info/ (local)

Hard to see in the diffs, might be wise to look at the end result.

I added this patch to the series as things otherwise might get hard to
handle.

quoted

Also, I would stop quoting terms like "mainline", "stable" and "vanilla"
throughout.  It makes the reading experience a bit stranger without
(IMO) adding anything.

Yeah, let me provide a patch to reduce the quoting. If it's okay for you
I'd like to leave the quotes in the section that round about explains
the terms mainline, stable, and longterm. I think it's wise there to
point out that these are terms that have a special meaning in kernel
context. That's why I quoted them in a lot of places – especially those
where the reader might see them for the first time, as "stable" is kind
of ambiguous, which I wanted to avoid somehow.

In the latest patch (
https://lore.kernel.org/linux-doc/652ee20eb36228f5d7ca842299faa4cb472feedb.1616181657.git.linux@leemhuis.info/ (local)
) I removed most of the quoting. I didn't touch other parts of the file
for now. Waiting for an option on this and then will address it in a
septate patch in one go.

Which brings me to another, but related issue. That patch could also fix
an inconsistency I recently noticed: how to spell panic, oops, bug,
warning? I sometimes quoted them  because in kernel context they have
special meaning, as a BUG() is not some random bug... And is it Oops or
oops (I recently noticed I used both spellings, but I found both when I
grepped Documentation/)? Here are some options:

1) panic, oops, bug, warning
2a) 'panic', 'oops', 'bug', 'warning',
2b) *panic*, *oops*, *bug*, *warning*,
3) panic, Oops, BUG, WARNING,
4) panic, Oops, BUG(), WARN()

The problem there is similar with the term 'stable': the words bug and
warning are ambiguous for people that are not familiar with the terms
used by the kernel community. Putting them in quotes at least give a
subtle hint like "this term might have a special meaning". It works for
my subconscious, but I guess won't for many others.

Nevertheless I'd go option 2a or 2b above: doesn't look to ugly (like 3
and 4) and avoids being ambiguous (like 1, which I for one don't like at
all).

What's your opinion on this? Or do you say "ohh, you are overthinking
it, just go with option 1!". :-D

Ciao, Thorsten