Received: by 10.192.165.148 with SMTP id m20csp1446244imm; Thu, 10 May 2018 10:47:53 -0700 (PDT) X-Google-Smtp-Source: AB8JxZpBwMeQMmHpw3FSWK5S/36dcaGehwVY2R1Zldq/3OVzps275o3+OCr4/4pHPG4neQMCDfT3 X-Received: by 2002:a62:9c0d:: with SMTP id f13-v6mr2233097pfe.15.1525974473283; Thu, 10 May 2018 10:47:53 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1525974473; cv=none; d=google.com; s=arc-20160816; b=lupoxrldN1djQW+ae9GNMwxXQ9jK+aJy+LKI0lXp1WjXNv/GulqY54SaiL/5MKelzo t+0g3GS70U7BVna7rmW2bl+ckEEEtgVjXEgNOKU4M1JSyAXQmY0FgmuKiyKeqxqrCwHo gCk+tx0bkXxlmhu8Rf+16JfFNjBDIw2vyqyK5DPE1NHVoKPDZj8zJ+ekCLAOpI/BCge2 t/WRnnxzKg4WfljVgjuB+spkMGFJDKXo3VmF7qtc4QKxF72ShVL+Rv8G90UMVXAnSgb9 FKtV6ucJlfUx64nT2cgc+7cYShFhvad3TpevcjDg4yvg9wlKu+Af9EJIIdMN+CQ2kC/I ToZg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :references:in-reply-to:message-id:subject:cc:to:from:date :dkim-signature:arc-authentication-results; bh=9tmhtva1JNNvRLTwCx36+p7VfpYtIfSU2be9sBC5JmI=; b=Ij1rALo40wczVyBsU7vXDe7GnQJZdKk3/zy6GwL0AHhPR0Q9PVjoOm8ao8/MQIl3v9 sPkzkATIJ0KUUmnN4NAmsUNbsNbd8y9Oy4cTqz3ggo2IQLXrzw6hFZRdRzCDK925z70j YdrGtCT0GvS6CbLyVKBc6eZEbHRBEdUT5plTqjwVNL88JfLOW4KMvnS8QiSVC1gMbhye LNDSYtBSb+pfjCwpgg8ZWvqjnxIeSsr3bw4klp1KQG7lZqyw8XJ7LMCJknhGmii8o9NF unLjIfSNFP8xfDajpls1Enl2Vd7ISehdjWdqoR0+FQkzdXqcZjTVLHuXy+QwR6DfiT+G 0rjg== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@infradead.org header.s=bombadil.20170209 header.b=r0uP6dkS; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id m1-v6si1188094pfe.79.2018.05.10.10.47.36; Thu, 10 May 2018 10:47:53 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; dkim=fail header.i=@infradead.org header.s=bombadil.20170209 header.b=r0uP6dkS; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S966793AbeEJRp4 (ORCPT + 99 others); Thu, 10 May 2018 13:45:56 -0400 Received: from bombadil.infradead.org ([198.137.202.133]:42530 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S966662AbeEJRpx (ORCPT ); Thu, 10 May 2018 13:45:53 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Content-Transfer-Encoding: Content-Type:MIME-Version:References:In-Reply-To:Message-ID:Subject:Cc:To: From:Date:Sender:Reply-To:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id: List-Help:List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=9tmhtva1JNNvRLTwCx36+p7VfpYtIfSU2be9sBC5JmI=; b=r0uP6dkSb3uv+pw4G6WJTt41u hTdWFKGf7dPFa3iAkicffMeZ/wCtvPj3ykF/xE/csnrEqgCiXstUc4XeIQOnnKM+t/Y0Y0aRYROMb lHMnCzvnt7Te2xpJfSDAccEy2uLvUgXCwDxUgQRBLEYqcFO+D6b8GndPDAllc7EdM8TElwZ6azobL hSmNltuhMbphusXBMzbFPgmaM/VcBeIWibcgMPs7iCscJovvBzsFg6TdqqTDJQZDn3tgXuVHvrOts KlFD2ytz9klLOBrunpCre0ZwME1M3XTVw56BOY+Uylh53K5TX3D9bkMoogZkZAGyYdp/Qewr9fHAQ gMsHCpLbw==; Received: from 177.41.96.165.dynamic.adsl.gvt.net.br ([177.41.96.165] helo=vento.lan) by bombadil.infradead.org with esmtpsa (Exim 4.90_1 #2 (Red Hat Linux)) id 1fGpdX-0001sp-Go; Thu, 10 May 2018 17:45:51 +0000 Date: Thu, 10 May 2018 14:45:46 -0300 From: Mauro Carvalho Chehab To: Andrea Parri Cc: Jonathan Corbet , Peter Zijlstra , Linux Doc Mailing List , Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Ingo Molnar Subject: Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings Message-ID: <20180510144546.1d94b771@vento.lan> In-Reply-To: <20180510165220.GA9757@andrea> References: <6b9b3184cbfabab1ad89c974ddf1c61631e8f1bf.1525684985.git.mchehab+samsung@kernel.org> <20180509084120.GF12217@hirez.programming.kicks-ass.net> <20180509084518.247650e2@lwn.net> <20180510122335.GA7704@andrea> <20180510071559.59dcc8cc@lwn.net> <20180510165220.GA9757@andrea> X-Mailer: Claws Mail 3.16.0 (GTK+ 2.24.32; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: quoted-printable Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Em Thu, 10 May 2018 18:52:20 +0200 Andrea Parri escreveu: > On Thu, May 10, 2018 at 07:15:59AM -0600, Jonathan Corbet wrote: > > On Thu, 10 May 2018 14:23:35 +0200 > > Andrea Parri wrote: > > =20 > > > 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 othe= rs. =20 > >=20 > > If you have an example of a place where use of a web browser has been > > made mandatory, please point it out. Avoiding that was at the top of t= he > > list of explicit requirements. =20 >=20 > That's all I need. >=20 >=20 > >Surely an extra colon is not going to > > force you to run screaming to the protective embrace of Firefox...? =20 >=20 > Let me put it in these terms: I believe that that extra colon (or the > "diagram" keywork) is not going to improve/help my use of the doc. ;D No, it won't improve, but, it won't make it harder for a human to understand if a "diagram" or "::" is added at the description. The thing is that we need something that works for the Kernel as a hole, and not just on a few places. On some subsystems, just a text is not good enough to describe things. See, for example: https://www.kernel.org/doc/html/latest/media/uapi/v4l/crop.html https://www.kernel.org/doc/html/latest/media/uapi/v4l/pixfmt-packed-rgb.ht= ml https://www.kernel.org/doc/html/latest/media/uapi/v4l/pixfmt-srggb10-ipu3.= html https://www.kernel.org/doc/html/latest/gpu/drm-kms.html Images, complex tables, etc are sometimes required to show some things. Trying to explain just on text is harder to write, longer and worse for readers. In the past, DocBook was used. ReST made very simple to write documentation. From where I sit, I'm reviewing documentation patches from a lot more people than the usage of a markup language. As a bonus, we can now create cross-references for kernel-doc functions, with is really great when reading documentation for complex hardware. =46rom where I sit at media, the subsystem documentation, if generated in PDF, becomes a book with more than 1,100 pages, full of long tables, images and graphs[1], covering uAPI, kAPI and driver-specific documentation. [1] https://linuxtv.org/downloads/v4l-dvb-apis-new/media.pdf As on all subsystems, developers write documentation directly at .rst or as kernel-doc comments. But for reading it, even developers prefer to read the docs via the html (or pdf) output, as it better shows tables and images. It is also faster to follow the dozen thousands of links inside it. The point is: we shouldn't enforce everyone to use our own view about how to navigate through documentation. People are free to use whatever improves their workflow. Thanks, Mauro