Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > linux.kernel > #1531214
| From | Jani Nikula <jani.nikula@linux.intel.com> |
|---|---|
| Newsgroups | linux.kernel |
| Subject | Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST markup |
| Date | 2016-11-28 12:20 +0100 |
| Message-ID | <sIs8y-1nY-13@gated-at.bofh.it> (permalink) |
| References | (2 earlier) <sHwHf-63k-19@gated-at.bofh.it> <sIhwt-2GQ-13@gated-at.bofh.it> <sIoxY-7ud-11@gated-at.bofh.it> <sIpNo-8es-17@gated-at.bofh.it> <sIrma-Si-25@gated-at.bofh.it> |
| Organization | Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo |
On Mon, 28 Nov 2016, Peter Zijlstra <peterz@infradead.org> 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. > > In any case, I've never had any problems with typing things like: "go > read: Documentation/file.txt for more information.". 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/ > 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. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center
Back to linux.kernel | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll 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