Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1531340

Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST markup

Show all headers | View raw

Hi Peter,

On Mon, Nov 28, 2016 at 11:20:09AM +0100, Peter Zijlstra wrote:
> On Mon, Nov 28, 2016 at 09:44:42AM +0100, Daniel Vetter wrote:
> > > Why change them? What was wrong with txt to begin with?
> > 
> > In my opinion good docs matter, and one of the key things is to be able to
> > cross reference stuff.
> 
> Well, good docs begin with useful content; and many docs lack that.
> Fixing that would be a much more useful thing to do.

Fully agreed, pretty looking docs that don't exist aren't useful at all
;-) Personally I'm pretty happy with typing .rst plain-text, since I
mostly ignore all the fancy stuff. Using .rst has also made the in-source
kerneldoc a lot more useful, e.g. vtables can now be documented in a
reasonable manner and the generated output still looks decent. For an
example see include/drm/drm_modeset_helper_vtables.h.

> In any case, I've never had any problems with typing things like: "go
> read: Documentation/file.txt for more information.".
> 
> Also, what text editor supports cross references at all then? With the
> filename I can use 'gf' in vim to open it up in a new buffer and go read
> that.

Yeah agreed, anything that requires more work for typing docs isn't really
useful. The nice thing about the kernel's sphinx toolchain is that a big
pile of these references (not all of them yet) are autogenerated. That is
of course of 0 use for old hats like us who just browse it all using vim
and gf and ^] and all maybe a quickfix list of hits.

But in my experience having something pretty to click around in is rather
useful for newbies. At least that's been my experience with the drm docs,
I have much less to explain on mails and chat since we've started with
this all. And excessive amounts of cross-references seem to help a lot in
guiding the blind ;-)

Anyway, my goal at least is to keep all the plain-text usage perfectly
fine, while giving newbies something pretty in there browsers.

> > Another concern some core kernel folks raised is that the .rst markup was
> > too heavy-handed, and makes the text much harder to read. Christoph called
> > it "cat spew". That can be fixed with a much lighter-handed conversion
> > (and 2nd patch iteration was acceptable for Christoph).
> 
> Very much agreed, once a file is no longer readable with less or the
> text editor of your choice, it as good doesn't exist at all. So I very
> much worry about RST even supporting such heavy markup that the end
> result is unreadable.
> 
> Basically, if a file isn't usable from within a 'normal' text editor, it
> doesn't exist.

Yup agreed. Personally I prefer a _much_ more light-handed appraoch with
rst markup. Essentially none, except the few things needed to glue all the
various docs into a somewhat coherent whole. And I think that's also
more-or-less the consensus among many core kernel hackers.

Jon, should we document that we want a very light-handed approach to rst
markup in kernel docs? This has come up a few times now, and irrespective
of what exactly we're going to do with atomic_ops.txt I think it would
help with making txt->rst conversions palatable to the core kernel
community. And it's knida my own preference too ...

Thanks, Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

Back to linux.kernel | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

[PATCH v2 0/4] core-api ReST: assoc_array, atomic_ops, local_ops Silvio Fricke <silvio.fricke@gmail.com> - 2016-11-25 11:10 +0100
  [PATCH v3 0/4] core-api ReST: assoc_array, atomic_ops, local_ops Silvio Fricke <silvio.fricke@gmail.com> - 2016-11-25 16:10 +0100
    [PATCH v3 4/4] firmware: remove warning at documentation generation time Silvio Fricke <silvio.fricke@gmail.com> - 2016-11-25 16:10 +0100
      Re: [PATCH v3 4/4] firmware: remove warning at documentation  generation time Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-11-25 22:00 +0100
        Re: [PATCH v3 4/4] firmware: remove warning at documentation  generation time "Luis R. Rodriguez" <mcgrof@kernel.org> - 2016-12-01 17:20 +0100
          Re: [PATCH v3 4/4] firmware: remove warning at documentation  generation time Greg Kroah-Hartman <gregkh@linuxfoundation.org> - 2016-12-01 17:50 +0100
    [PATCH v3 3/4] Documentation/local_ops.txt: convert to ReST markup Silvio Fricke <silvio.fricke@gmail.com> - 2016-11-25 16:10 +0100
      Re: [PATCH v3 3/4] Documentation/local_ops.txt: convert to ReST  markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-11-25 22:20 +0100
    [PATCH v3 1/4] Documentation/assoc_array.txt: convert to ReST markup Silvio Fricke <silvio.fricke@gmail.com> - 2016-11-25 16:10 +0100
      Re: [PATCH v3 1/4] Documentation/assoc_array.txt: convert to ReST  markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-11-25 22:00 +0100
    Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST  markup Peter Zijlstra <peterz@infradead.org> - 2016-11-25 23:00 +0100
      Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST  markup "S. Fricke" <silvio.fricke@gmail.com> - 2016-11-27 16:00 +0100
        Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST markup Jani Nikula <jani.nikula@linux.intel.com> - 2016-11-27 19:40 +0100
      Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST  markup Jonathan Corbet <corbet@lwn.net> - 2016-11-28 01:00 +0100
        Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST  markup Peter Zijlstra <peterz@infradead.org> - 2016-11-28 08:30 +0100
          Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST  markup Daniel Vetter <daniel@ffwll.ch> - 2016-11-28 09:50 +0100
            Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST  markup Peter Zijlstra <peterz@infradead.org> - 2016-11-28 11:30 +0100
              Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST  markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-11-28 12:10 +0100
                Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST  markup Peter Zijlstra <peterz@infradead.org> - 2016-11-28 13:00 +0100
                Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST  markup Daniel Vetter <daniel@ffwll.ch> - 2016-11-28 14:50 +0100
                Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST  markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-11-28 16:20 +0100
              Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST markup Jani Nikula <jani.nikula@linux.intel.com> - 2016-11-28 12:20 +0100
                Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST  markup Peter Zijlstra <peterz@infradead.org> - 2016-11-28 13:00 +0100
                Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST markup Jani Nikula <jani.nikula@linux.intel.com> - 2016-11-28 13:40 +0100
              Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST  markup Daniel Vetter <daniel@ffwll.ch> - 2016-11-28 15:20 +0100
                Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST  markup Jonathan Corbet <corbet@lwn.net> - 2016-11-28 15:30 +0100
    [PATCH v4 0/4] core-api ReST: assoc_array, atomic_ops, local_ops Silvio Fricke <silvio.fricke@gmail.com> - 2016-11-28 18:40 +0100
      [PATCH v4 1/4] Documentation/assoc_array.txt: convert to ReST markup Silvio Fricke <silvio.fricke@gmail.com> - 2016-11-28 18:40 +0100
      Re: [PATCH v4 0/4] core-api ReST: assoc_array, atomic_ops,  local_ops Jonathan Corbet <corbet@lwn.net> - 2016-12-01 02:00 +0100
        Re: [PATCH v4 0/4] core-api ReST: assoc_array, atomic_ops, local_ops "Luis R. Rodriguez" <mcgrof@kernel.org> - 2016-12-01 17:00 +0100

csiph-web