Received: by 2002:a25:4158:0:0:0:0:0 with SMTP id o85csp6176018yba; Thu, 11 Apr 2019 13:46:27 -0700 (PDT) X-Google-Smtp-Source: APXvYqxkX4xJVsAVSh3VD2oWiorRCL5H+o8xs/d3gu65oW+RAlEWEVDb9ztFmLnAqYNpug7K+TVs X-Received: by 2002:a17:902:a706:: with SMTP id w6mr53090304plq.91.1555015587662; Thu, 11 Apr 2019 13:46:27 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1555015587; cv=none; d=google.com; s=arc-20160816; b=fVuIDpJYlMjzUcIS/nN0zIRXUBFui6U5ZcpW516Lac2oAkp48I/V7NbaUPXEqZ99Xa Ft6pHCXSgHoVq90Xx968M/+Q//fZRgsCEgW9HuXd63PO3Yaf2bhjQVc3Gq680HX3dkiQ M9uPLj1VwJ/Nvk4hTeCxcs3FHZh0RwrP3Puot8wosL5nsLKTzJaFz/ZpmLkLXe5pQorQ 38KmqqwsIthUrl+OCz9jCMcDshPpl7Q6vJEvWp5TyM1laqvtjsrKN5YT4CWsa7w/2izG 0n9RlD1gW5EBhUIps7LFOe/536aPEp2fzyc7rA1I2n4r0fJuznJqhS5S2w4yrlEYe163 v3RQ== 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; bh=e9Z/7e3/hRsGnS2IGdT3ZcpPF2Keute9G8FZSvjPYvw=; b=tW4U/N8GmmHpC+4ADI42iexIX4c04SifxnRTctJg84wwR/Gh/Q4KstGuWzYQ8n5NIB 2MrbRKLqSYsryZ+mPj04DRCtFepjPcjeC5ykq5+1YRCRgHnBkRSUT4Z1Ey8X2oNIbFjN 5OTcyNfdjE4vIU8/JnRRuT7TMyJ40YAVIHzG0IvYRhYAUd+rR6QsS4LuBxEgCLdk9/G/ v8prZrjef8CGovRg2uhve2Gbt7F88YQHxcA8N4pcboiCtF+Tsu9ST3DuWgErKofWFsD3 DcMeqaMGoTS9nzMbjX1wSeF3hGhkH1zxYxwLgaW6WzPPHhhdM/OCeFC1Eng+YFAQEbA5 zfiA== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@infradead.org header.s=casper.20170209 header.b=ml67nDSf; 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 k18si35951414pgb.351.2019.04.11.13.46.11; Thu, 11 Apr 2019 13:46:27 -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=casper.20170209 header.b=ml67nDSf; 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 S1726924AbfDKUoO (ORCPT + 99 others); Thu, 11 Apr 2019 16:44:14 -0400 Received: from casper.infradead.org ([85.118.1.10]:37936 "EHLO casper.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726629AbfDKUoO (ORCPT ); Thu, 11 Apr 2019 16:44:14 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=casper.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=e9Z/7e3/hRsGnS2IGdT3ZcpPF2Keute9G8FZSvjPYvw=; b=ml67nDSf8iAwnEALQB1I8vyqA8 TS0UFAHu4F1JxQDfKqgX4khtCfCdm/PNWWp8FlxfUL99uzN2HQOx+4IDNHFU5FGEv9O7sv8yzZEs3 do+3nQvj8OqYxn2AwfvufaI2prXL19tSuh1JOugN7O6qRW/E91lUjXRs5ksYawU06OU7ltn2UDkk9 4drePCv1T5mbCpYRxmqLazFVy6Xrdwfe5A6AaAtdHMTZ93NqEYt29XBKrVkePqBxaNZ5n/E3AiKWp hvktN8LDszwkexr2gk7xY5cJcwmDrZckik1bgoUqT807DsY1VHtEE157AYGNBEBi7oBeGlOCFGBsT +DZPLIaA==; Received: from 201.86.162.146.dynamic.adsl.gvt.net.br ([201.86.162.146] helo=coco.lan) by casper.infradead.org with esmtpsa (Exim 4.90_1 #2 (Red Hat Linux)) id 1hEgYH-0001OQ-If; Thu, 11 Apr 2019 20:44:06 +0000 Date: Thu, 11 Apr 2019 17:43:57 -0300 From: Mauro Carvalho Chehab To: Jonathan Corbet Cc: Linux Doc Mailing List , Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Andrew Jeffery , Benjamin Herrenschmidt , Guenter Roeck , Jean Delvare , Joel Stanley , linux-arm-kernel@lists.infradead.org, linux-aspeed@lists.ozlabs.org, linux-hwmon@vger.kernel.org, linuxppc-dev@lists.ozlabs.org, Liviu Dudau , Lorenzo Pieralisi , Michael Ellerman , Paul Mackerras , Sudeep Holla Subject: Re: [PATCH v2 00/21] Convert hwmon documentation to ReST Message-ID: <20190411174357.251904f5@coco.lan> In-Reply-To: <20190411124324.3ed62fad@lwn.net> References: <20190411124324.3ed62fad@lwn.net> X-Mailer: Claws Mail 3.17.3 (GTK+ 2.24.32; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Em Thu, 11 Apr 2019 12:43:24 -0600 Jonathan Corbet escreveu: > On Wed, 10 Apr 2019 16:22:37 -0300 > Mauro Carvalho Chehab wrote: > > > This series converts the contents of Documentation/hwmon to ReST > > format. > > > > PS.: I opted to group the conversion files per groups of maintainer > > set, as, if I were to generate one patch per file, it would give around > > 160 patches. > > > > I also added those patches to my development tree at: > > https://git.linuxtv.org/mchehab/experimental.git/log/?h=hwmon > > > > If you want to see the results, they're at: > > https://www.infradead.org/~mchehab/hwmon/ > > This set seems generally good and could probably be applied as-is. But I > have to ask...is there a reason to not take the last step and actually > bring this stuff into the Sphinx doc tree? > > We seem to be mostly documenting sysfs files and such. I am *guessing* > that perhaps the set should move to Documentation/admin-guide/hwmon? Or > have I misunderstood the intended audience here? :-) Yeah, I'd say that 80% of the contents there are user-faced. Yet, the main issue with this (and other driver subsystems) is that there's a mix of userspace and Kernelspace stuff. One somewhat simple case is the abituguru: it has a "datasheet" file: abituguru-datasheet This contains programming information for the corresponding drivers, while abituguru and abituguru3 contains mostly userspace stuff (still, it also contains the I2C address, with shouldn't mean anything for the user). However, if you take a look at w83781d, you'll see a mix of both userspace and driver developer info there... it has a chapter called "Data sheet updates", for example, with is probably meaningless for anyone but the hwmon driver developers. That's, btw, a pattern that happens a lot inside device driver documents on almost all subsystems I checked: driver-specific documentation is usually not split into user-facing/kernel-facing. While nobody does such split, IMHO, the best would be to keep the information outside Documentation/admin-guide. But hey! You're the Doc maintainer. If you prefer to move, I'm perfectly fine with that. Thanks, Mauro