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
