[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Date: Tue, 7 Jul 2020 14:47:42 +0200
From: Peter Zijlstra <peterz@...radead.org>
To: "Ahmed S. Darwish" <a.darwish@...utronix.de>
Cc: Ingo Molnar <mingo@...hat.com>, Will Deacon <will@...nel.org>,
Thomas Gleixner <tglx@...utronix.de>,
"Paul E. McKenney" <paulmck@...nel.org>,
"Sebastian A. Siewior" <bigeasy@...utronix.de>,
Steven Rostedt <rostedt@...dmis.org>,
LKML <linux-kernel@...r.kernel.org>,
Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org
Subject: Re: [PATCH v3 01/20] Documentation: locking: Describe seqlock design
and usage
On Tue, Jul 07, 2020 at 12:12:01PM +0200, Ahmed S. Darwish wrote:
> On Mon, Jul 06, 2020 at 11:04:39PM +0200, Peter Zijlstra wrote:
> > On Tue, Jun 30, 2020 at 07:44:33AM +0200, Ahmed S. Darwish wrote:
> > > +Sequence counters (:c:type:`seqcount_t`)
> > > +========================================
> >
> > > +.. code-block:: c
> >
> > I so hate RST, of course it's C. Also, ISTR Jon saying you can leave
> > that all out without issue.
>
> There you go again.
>
> linux$ git grep 'code-block:: c' | wc -l
> ==> 470
>
> linux$ git grep ':ref:' | wc -l
> ==> 3171
>
> linux$ git grep ':c:type:' | wc -l
> ==> 1533
>
> In writing this, Documentation/doc-guide/ was followed, and literally
> the thousands of examples above.
Then this is a very bad guide. Jon, why is it recommending such horrible
crap? Should we add another field to MAINTAINERS to indicate RST/TXT
preference? Because I'm getting fed up trying to fix up all this
unreadable gunk.
I'm >< close to writing an script that will unconditionally and silently
convert everything to txt before committing.
> But honestly, I don't want to block merging documentation because of
> this, and the point of making the docs as readable as possible from text
> editors also has merit.
>
> So... I'll just make that file as "RST-lite" as possible.
Thanks!
Powered by blists - more mailing lists