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

[Thorsten Leemhuis]

On 16.03.21 18:56, Thorsten Leemhuis wrote:
> On 15.03.21 21:20, Jonathan Corbet wrote:
>> Thorsten Leemhuis <linux@xxxxxxxxxxxxx> writes:
>
>>  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@xxxxxxxxxxxxx/

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.

>> 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@xxxxxxxxxxxxx/
) 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