On Wed, May 09, 2018 at 08:45:18AM -0600, Jonathan Corbet wrote: > On Wed, 9 May 2018 10:41:20 +0200 > Peter Zijlstra <peterz@xxxxxxxxxxxxx> wrote: > > > > This is easily done by using "::" instead of just ":". > > > > And I'll voice my objection once again. This makes a regular comment > > worse. This rst stuff is utter shit for making normal text files less > > readable in your favourite text editor. > > > > If this gets merged, I'll simply remove that spurious ':' the next time > > I'm near that comment. > > Seriously, Peter? > > It's a simple colon. It goes along with the /** marker for kerneldoc > comments and the @ markers found within them, both of which you seem to > have found a way to live with. > > The RST work was discussed for a year before we even started. It has > brought in the efforts of a large number of developers, all of whom see > the value in actually caring about our documentation and making it > accessible to a much larger group of readers. And it has all happened > while preserving the primacy of the plain-text documentation. > > You're not the only consumer of the docs. You may not appreciate the > improvements that have come, but others certainly do. I do hope that you > can find it in youself to avoid vandalizing things for everybody else ...? You wrote it: the fact that some people (including its developers) see a value in the RST work or the fact that such work made the kernel doc. accessible to a larger group of readers are not in question here; only remember that other people (including some developers running into the "disadventure" of opening an RST doc. from their preferred text editor and being brought to conclude: "WTH! I need to open a web browser, I guess...") _use_ such doc. and _do care_ about it, and that what might be an improvement for some people might look as "vandalizing" to others. We're talking about readability/accessibility here, but I think similar considerations apply to other aspects of the doc. such as availability/ completeness (yes, I did hear developers arguing "I won't write such a doc., because...") and consistency (w.r.t. the doc. itself and sources). Andrea > > Thanks, > > jon -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
