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

Groups > linux.kernel > #1531240

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

Show all headers | View raw

On Mon, Nov 28, 2016 at 01:16:45PM +0200, Jani Nikula wrote:
> Using rst we can produce decent HTML pages, and make them available at
> [1], in context. You don't have to read that, but it will be a lot more
> discoverable for other people, another important quality of good
> documentation. And perhaps you don't have to tell people to go read it
> so much.
> 
> [1] https://www.kernel.org/doc/html/latest/

*sigh*, basically if I have to touch a browser its broken.

> > 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.
> 
> The goal is to have the best of both worlds, keeping it pretty much
> plain text, but adding just enough consistency in formatting that you
> can generate other formats out of it. We don't have to and we shouldn't
> go overboard with the markup.
> 
> Arguably you could call rst a "coding style" for plain text. We have
> pretty uniform C code, I don't think it's unreasonable to have a little
> bit of consistency in the plain text. And really, it's not much we're
> asking.

With some decidedly daft conventions though; see my email to Mauro.

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