Messages in this thread | | | Date | Tue, 7 Jul 2020 14:47:42 +0200 | From | Peter Zijlstra <> | 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!
| |