From: Andrea Parri <andrea.parri@amarulasolutions.com> To: Jonathan Corbet <corbet@lwn.net> Cc: Peter Zijlstra <peterz@infradead.org>, Mauro Carvalho Chehab <mchehab+samsung@kernel.org>, Linux Doc Mailing List <linux-doc@vger.kernel.org>, Mauro Carvalho Chehab <mchehab@infradead.org>, linux-kernel@vger.kernel.org, Ingo Molnar <mingo@redhat.com> Subject: Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings Date: Thu, 10 May 2018 14:23:35 +0200 [thread overview] Message-ID: <20180510122335.GA7704@andrea> (raw) In-Reply-To: <20180509084518.247650e2@lwn.net> On Wed, May 09, 2018 at 08:45:18AM -0600, Jonathan Corbet wrote: > On Wed, 9 May 2018 10:41:20 +0200 > Peter Zijlstra <peterz@infradead.org> wrote: > > > > This is easily done by using "::" instead of just ":". > > > > And I'll voice my objection once again. This makes a regular comment > > worse. This rst stuff is utter shit for making normal text files less > > readable in your favourite text editor. > > > > If this gets merged, I'll simply remove that spurious ':' the next time > > I'm near that comment. > > Seriously, Peter? > > It's a simple colon. It goes along with the /** marker for kerneldoc > comments and the @ markers found within them, both of which you seem to > have found a way to live with. > > The RST work was discussed for a year before we even started. It has > brought in the efforts of a large number of developers, all of whom see > the value in actually caring about our documentation and making it > accessible to a much larger group of readers. And it has all happened > while preserving the primacy of the plain-text documentation. > > You're not the only consumer of the docs. You may not appreciate the > improvements that have come, but others certainly do. I do hope that you > can find it in youself to avoid vandalizing things for everybody else ...? You wrote it: the fact that some people (including its developers) see a value in the RST work or the fact that such work made the kernel doc. accessible to a larger group of readers are not in question here; only remember that other people (including some developers running into the "disadventure" of opening an RST doc. from their preferred text editor and being brought to conclude: "WTH! I need to open a web browser, I guess...") _use_ such doc. and _do care_ about it, and that what might be an improvement for some people might look as "vandalizing" to others. We're talking about readability/accessibility here, but I think similar considerations apply to other aspects of the doc. such as availability/ completeness (yes, I did hear developers arguing "I won't write such a doc., because...") and consistency (w.r.t. the doc. itself and sources). Andrea > > Thanks, > > jon
WARNING: multiple messages have this Message-ID (diff)
From: Andrea Parri <andrea.parri@amarulasolutions.com> To: Jonathan Corbet <corbet@lwn.net> Cc: Peter Zijlstra <peterz@infradead.org>, Mauro Carvalho Chehab <mchehab+samsung@kernel.org>, Linux Doc Mailing List <linux-doc@vger.kernel.org>, Mauro Carvalho Chehab <mchehab@infradead.org>, linux-kernel@vger.kernel.org, Ingo Molnar <mingo@redhat.com> Subject: Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings Date: Thu, 10 May 2018 14:23:35 +0200 [thread overview] Message-ID: <20180510122335.GA7704@andrea> (raw) In-Reply-To: <20180509084518.247650e2@lwn.net> On Wed, May 09, 2018 at 08:45:18AM -0600, Jonathan Corbet wrote: > On Wed, 9 May 2018 10:41:20 +0200 > Peter Zijlstra <peterz@infradead.org> wrote: > > > > This is easily done by using "::" instead of just ":". > > > > And I'll voice my objection once again. This makes a regular comment > > worse. This rst stuff is utter shit for making normal text files less > > readable in your favourite text editor. > > > > If this gets merged, I'll simply remove that spurious ':' the next time > > I'm near that comment. > > Seriously, Peter? > > It's a simple colon. It goes along with the /** marker for kerneldoc > comments and the @ markers found within them, both of which you seem to > have found a way to live with. > > The RST work was discussed for a year before we even started. It has > brought in the efforts of a large number of developers, all of whom see > the value in actually caring about our documentation and making it > accessible to a much larger group of readers. And it has all happened > while preserving the primacy of the plain-text documentation. > > You're not the only consumer of the docs. You may not appreciate the > improvements that have come, but others certainly do. I do hope that you > can find it in youself to avoid vandalizing things for everybody else ...? You wrote it: the fact that some people (including its developers) see a value in the RST work or the fact that such work made the kernel doc. accessible to a larger group of readers are not in question here; only remember that other people (including some developers running into the "disadventure" of opening an RST doc. from their preferred text editor and being brought to conclude: "WTH! I need to open a web browser, I guess...") _use_ such doc. and _do care_ about it, and that what might be an improvement for some people might look as "vandalizing" to others. We're talking about readability/accessibility here, but I think similar considerations apply to other aspects of the doc. such as availability/ completeness (yes, I did hear developers arguing "I won't write such a doc., because...") and consistency (w.r.t. the doc. itself and sources). Andrea > > Thanks, > > jon -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
next prev parent reply other threads:[~2018-05-10 12:23 UTC|newest] Thread overview: 184+ messages / expand[flat|nested] mbox.gz Atom feed top 2018-05-07 9:35 [PATCH 00/18] Fix some build warnings/errors with Sphinx Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 9:35 ` [PATCH 01/18] docs: can.rst: fix a footnote reference Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 18:41 ` Oliver Hartkopp 2018-05-07 18:41 ` Oliver Hartkopp 2018-05-07 9:35 ` [PATCH 02/18] docs: fix location of request_firmware & friends Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-08 3:07 ` Greg Kroah-Hartman 2018-05-08 3:07 ` Greg Kroah-Hartman 2018-05-08 15:49 ` Luis R. Rodriguez 2018-05-08 15:49 ` Luis R. Rodriguez 2018-05-09 12:26 ` Mauro Carvalho Chehab 2018-05-09 12:26 ` Mauro Carvalho Chehab 2018-05-07 9:35 ` [PATCH 03/18] docs: */index.rst: Add newer documents to their respective index.rst Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-08 3:07 ` Greg Kroah-Hartman 2018-05-08 3:07 ` Greg Kroah-Hartman 2018-05-08 15:59 ` Jonathan Corbet 2018-05-08 15:59 ` Jonathan Corbet 2018-05-07 9:35 ` [PATCH 04/18] docs: admin-guide: add bcache documentation Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-08 16:01 ` Jonathan Corbet 2018-05-08 16:01 ` Jonathan Corbet 2018-05-07 9:35 ` [PATCH 05/18] docs: core-api: add cachetlb documentation Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 12:29 ` Andrea Parri 2018-05-07 12:29 ` Andrea Parri 2018-05-08 14:40 ` Jani Nikula 2018-05-08 14:40 ` Jani Nikula 2018-05-08 16:02 ` Andrea Parri 2018-05-08 16:02 ` Andrea Parri 2018-05-08 16:28 ` Andrea Parri 2018-05-08 16:28 ` Andrea Parri 2018-05-08 18:05 ` Mauro Carvalho Chehab 2018-05-08 18:05 ` Mauro Carvalho Chehab 2018-05-08 18:28 ` Mauro Carvalho Chehab 2018-05-08 18:28 ` Mauro Carvalho Chehab 2018-05-08 19:05 ` Andrea Parri 2018-05-08 19:05 ` Andrea Parri 2018-05-08 16:04 ` Jonathan Corbet 2018-05-08 16:04 ` Jonathan Corbet 2018-05-08 16:51 ` Andrea Parri 2018-05-08 16:51 ` Andrea Parri 2018-05-07 9:35 ` [PATCH 06/18] docs: core-api: add cgroup-v2 documentation Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-08 15:51 ` Jonathan Corbet 2018-05-08 15:51 ` Jonathan Corbet 2018-05-09 12:02 ` Mauro Carvalho Chehab 2018-05-09 12:02 ` Mauro Carvalho Chehab 2018-05-07 9:35 ` [PATCH 07/18] docs: core-api: add circular-buffers documentation Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 12:31 ` Andrea Parri 2018-05-07 12:31 ` Andrea Parri 2018-05-08 16:08 ` Jonathan Corbet 2018-05-08 16:08 ` Jonathan Corbet 2018-05-07 9:35 ` [PATCH 08/18] docs: driver-api: add clk documentation Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-08 3:07 ` Greg Kroah-Hartman 2018-05-08 3:07 ` Greg Kroah-Hartman 2018-05-08 16:10 ` Jonathan Corbet 2018-05-08 16:10 ` Jonathan Corbet 2018-05-07 9:35 ` [PATCH 09/18] net: mac80211.h: fix a bad comment line Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 12:37 ` Kalle Valo 2018-05-07 12:37 ` Kalle Valo 2018-05-07 12:38 ` Johannes Berg 2018-05-07 12:38 ` Johannes Berg 2018-05-09 12:04 ` Mauro Carvalho Chehab 2018-05-09 12:04 ` Mauro Carvalho Chehab 2018-05-09 12:04 ` Johannes Berg 2018-05-09 12:04 ` Johannes Berg 2018-05-07 9:35 ` [PATCH 10/18] rcu: rcupdate.h: get rid of Sphinx warnings at rcu_pointer_handoff() Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 14:23 ` Paul E. McKenney 2018-05-07 14:23 ` Paul E. McKenney 2018-05-09 11:55 ` Mauro Carvalho Chehab 2018-05-09 11:55 ` Mauro Carvalho Chehab 2018-05-14 19:40 ` Paul E. McKenney 2018-05-14 19:40 ` Paul E. McKenney 2018-05-07 9:35 ` [PATCH 11/18] docs: crypto_engine.rst: Fix two parse warnings Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 9:35 ` [PATCH 12/18] time: timer.c: adjust a kernel-doc comment Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-13 14:00 ` [tip:timers/core] timers: Adjust " tip-bot for Mauro Carvalho Chehab 2018-05-13 14:00 ` tip-bot for Mauro Carvalho Chehab 2018-05-07 9:35 ` [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-09 8:41 ` Peter Zijlstra 2018-05-09 8:41 ` Peter Zijlstra 2018-05-09 14:45 ` Jonathan Corbet 2018-05-09 14:45 ` Jonathan Corbet 2018-05-09 15:20 ` Peter Zijlstra 2018-05-09 15:20 ` Peter Zijlstra 2018-05-09 18:35 ` Jonathan Corbet 2018-05-09 18:35 ` Jonathan Corbet 2018-05-09 18:50 ` Markus Heiser 2018-05-09 18:50 ` Markus Heiser 2018-05-09 19:31 ` Peter Zijlstra 2018-05-09 19:31 ` Peter Zijlstra 2018-05-10 12:23 ` Andrea Parri [this message] 2018-05-10 12:23 ` Andrea Parri 2018-05-10 13:15 ` Jonathan Corbet 2018-05-10 13:15 ` Jonathan Corbet 2018-05-10 16:52 ` Andrea Parri 2018-05-10 16:52 ` Andrea Parri 2018-05-10 17:45 ` Mauro Carvalho Chehab 2018-05-10 17:45 ` Mauro Carvalho Chehab 2018-05-10 8:38 ` Christoph Hellwig 2018-05-10 8:38 ` Christoph Hellwig 2018-05-10 9:38 ` Mauro Carvalho Chehab 2018-05-10 9:38 ` Mauro Carvalho Chehab 2018-05-10 12:20 ` Peter Zijlstra 2018-05-10 12:20 ` Peter Zijlstra 2018-05-10 13:04 ` Mauro Carvalho Chehab 2018-05-10 13:04 ` Mauro Carvalho Chehab 2018-05-10 13:30 ` Jonathan Corbet 2018-05-10 13:30 ` Jonathan Corbet 2018-05-10 13:31 ` Jonathan Corbet 2018-05-10 13:31 ` Jonathan Corbet 2018-05-10 14:21 ` Mauro Carvalho Chehab 2018-05-10 14:21 ` Mauro Carvalho Chehab 2018-05-10 15:38 ` Jonathan Corbet 2018-05-10 15:38 ` Jonathan Corbet 2018-05-10 16:42 ` Mauro Carvalho Chehab 2018-05-10 16:42 ` Mauro Carvalho Chehab 2018-05-10 17:14 ` Mauro Carvalho Chehab 2018-05-10 17:14 ` Mauro Carvalho Chehab 2018-05-11 7:06 ` Markus Heiser 2018-05-11 7:06 ` Markus Heiser 2018-05-07 9:35 ` [PATCH 14/18] fbdev: modedb.c: fix a kernel-doc markup Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-15 10:22 ` Bartlomiej Zolnierkiewicz 2018-05-15 10:22 ` Bartlomiej Zolnierkiewicz 2018-05-15 10:22 ` Bartlomiej Zolnierkiewicz 2018-05-15 10:22 ` Bartlomiej Zolnierkiewicz 2018-05-07 9:35 ` [PATCH 15/18] iio: iio.h: use nested struct support on " Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 17:08 ` Jonathan Cameron 2018-05-07 17:08 ` Jonathan Cameron 2018-05-09 12:00 ` Mauro Carvalho Chehab 2018-05-09 12:00 ` Mauro Carvalho Chehab 2018-05-07 9:35 ` [PATCH 16/18] mtd: rawnand.h: use nested union kernel-doc markups Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 9:46 ` Boris Brezillon 2018-05-07 9:46 ` Boris Brezillon 2018-05-07 11:32 ` Mauro Carvalho Chehab 2018-05-07 11:32 ` Mauro Carvalho Chehab 2018-05-09 12:02 ` Boris Brezillon 2018-05-09 12:02 ` Boris Brezillon 2018-05-09 12:10 ` Mauro Carvalho Chehab 2018-05-09 12:10 ` Mauro Carvalho Chehab 2018-05-09 12:22 ` Boris Brezillon 2018-05-09 12:22 ` Boris Brezillon 2018-05-09 13:28 ` Mauro Carvalho Chehab 2018-05-09 13:28 ` Mauro Carvalho Chehab 2018-05-09 15:56 ` Boris Brezillon 2018-05-09 15:56 ` Boris Brezillon 2018-05-07 9:35 ` [PATCH 17/18] docs: uio-howto.rst: use a code block to solve a warning Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-08 3:07 ` Greg Kroah-Hartman 2018-05-08 3:07 ` Greg Kroah-Hartman 2018-05-07 9:35 ` [PATCH 18/18] w1: w1_io.c: fix a kernel-doc warning Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-08 11:03 ` Evgeniy Polyakov 2018-05-08 11:03 ` Evgeniy Polyakov 2018-05-09 12:32 ` Mauro Carvalho Chehab 2018-05-09 12:32 ` Mauro Carvalho Chehab 2018-05-09 13:11 ` Jonathan Corbet 2018-05-09 13:11 ` Jonathan Corbet 2018-05-10 10:37 ` Evgeniy Polyakov 2018-05-10 10:37 ` Evgeniy Polyakov 2018-05-08 16:13 ` [PATCH 00/18] Fix some build warnings/errors with Sphinx Jonathan Corbet 2018-05-08 16:13 ` Jonathan Corbet 2018-05-08 16:13 ` Jonathan Corbet 2018-05-08 16:13 ` Jonathan Corbet 2018-05-08 17:36 ` Luis R. Rodriguez 2018-05-08 17:36 ` Luis R. Rodriguez 2018-05-08 17:36 ` Luis R. Rodriguez 2018-05-08 17:36 ` Luis R. Rodriguez
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20180510122335.GA7704@andrea \ --to=andrea.parri@amarulasolutions.com \ --cc=corbet@lwn.net \ --cc=linux-doc@vger.kernel.org \ --cc=linux-kernel@vger.kernel.org \ --cc=mchehab+samsung@kernel.org \ --cc=mchehab@infradead.org \ --cc=mingo@redhat.com \ --cc=peterz@infradead.org \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.