Jonathan Corbet wrote: > Dan Williams <dan.j.williams@xxxxxxxxx> writes: > > > Matthew Wilcox wrote: > >> On Fri, Mar 22, 2024 at 12:10:38PM -0700, Dan Williams wrote: > >> > Peter Zijlstra wrote: > >> > > So I despise all that RST stuff. It makes what should be trivially > >> > > readable text into a trainwreck. We're coders, we use text editors to > >> > > read comments. > >> > > >> > Ok, I will rip out the RST stuff and just make this a standalone comment. > >> > >> I would rather you ignored Peter's persistent whining about RST and > >> kept the formatting. > > Dealing with that is definitely the least pleasant part of trying to > maintain docs... What is Linux development if not a surprising ongoing discovery of one-off local preferences? FWIW, I think the ability to embed RST markup directly into source code documentation is a slick mechanism. It is something I welcome into any file I maintain. At the same time, for files I do not maintain, maintainer deference indicates "jettison some markup syntax to move the bigger picture forward". > > Hmm, how about split the difference and teach scripts/kernel-doc to treat > > Peter's preferred markup for a C code example as a synonym, i.e. > > effectively a search and replace of a line with only: > > > > Ex. > > > > ...with: > > > > .. code-block:: c > > > > ...within a kernel-doc DOC: section? > > I'm not convinced that "Ex." is a clearer or more readable syntax, and > I'd prefer to avoid adding to the regex hell that kernel-doc already is > or adding more special syntax of our own. How about, as Lukas > suggested, just using the "::" notation? You get a nice literal block, > albeit without the syntax highlighting -- a worthwhile tradeoff, IMO. Sounds reasonable to me, will do that for v2. Lukas, thanks for the help!
