On 02.02.22 00:23, Jonathan Corbet wrote: > Thorsten Leemhuis <linux@xxxxxxxxxxxxx> 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@xxxxxxxxxxxxx> >> --- >> .../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
