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

Groups > linux.kernel > #1458564

Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools

Show all headers | View raw

On Tue, Aug 9, 2016 at 10:31 AM, Christoph Hellwig <hch@infradead.org> wrote:
> On Tue, Aug 09, 2016 at 10:28:38AM +0200, Daniel Vetter wrote:
>> The point is to make the docs more discoverable by being able to
>> cross-link them. Old hats like us don't need that, but it definitely
>> has value in bringing new folks on board.
>
> But do that in a way that keeps the old hats happy.  The crazy use of
> punctuation and the weird quotes is an absolute no-go.

We've been bikeshedding on the exact kind of light markup since over a
year now. Current one is rst, with pretty much uniform support among
the folks who cared that it's the least offensive of the bunch. I
think it can be made slightly less invasive by trading in a bit of the
noise in the sourc for warnings from the html generators (and less
pretty html output), but that's pretty close to nothing already.

The only other option with less markup is markdown, but the only
reason it's less invasive is that I can't really do anything at all.
Definitely no sensible way to pull in things like kernel-doc or the
uapi headers media needs.

Jon, can you please try to respin the patch with fewer changes, but
(probably) more rst warnings?
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch

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

Thread

[PATCH 00/10] [RFC] Sphinxify and coalesce development-tool documents Jonathan Corbet <corbet@lwn.net> - 2016-08-09 01:40 +0200
  [PATCH 05/10] docs: sphinixfy gcov.txt and move to dev-tools Jonathan Corbet <corbet@lwn.net> - 2016-08-09 01:40 +0200
  [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools Jonathan Corbet <corbet@lwn.net> - 2016-08-09 01:40 +0200
    Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools Christoph Hellwig <hch@infradead.org> - 2016-08-09 10:10 +0200
      Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-08-09 10:30 +0200
        Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools Christoph Hellwig <hch@infradead.org> - 2016-08-09 10:40 +0200
          Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-08-09 12:10 +0200
          Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools Jonathan Corbet <corbet@lwn.net> - 2016-08-10 01:00 +0200
      Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools Christoph Hellwig <hch@infradead.org> - 2016-08-09 10:30 +0200
      Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools Jani Nikula <jani.nikula@intel.com> - 2016-08-09 10:30 +0200
  Re: [PATCH 09/10] docs: sphinxify kmemcheck.txt and move to dev-tools Vegard Nossum <vegard.nossum@gmail.com> - 2016-08-09 09:10 +0200
  Re: [PATCH 00/10] [RFC] Sphinxify and coalesce development-tool documents Jani Nikula <jani.nikula@intel.com> - 2016-08-09 11:00 +0200

csiph-web