From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mauro Carvalho Chehab Subject: Re: [PATCH 00/44] Manually convert filesystem FS documents to ReST Date: Tue, 18 Feb 2020 11:04:06 +0100 Message-ID: <20200218110406.098fdc09@kernel.org> References: <20200218040146.GM7778@bombadil.infradead.org> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Return-path: DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20170209; h=Sender: Content-Transfer-Encoding:Content-Type:Cc:List-Subscribe:List-Help:List-Post: List-Archive:List-Unsubscribe:List-Id:MIME-Version:References:In-Reply-To: Message-ID:Subject:To:From:Date:Reply-To:Content-ID:Content-Description: Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID: List-Owner; bh=2edZqVayklgD493Helxa+CAJTwR0drqPQnZUcTxC1/Y=; b=aTy4GgoJgv+ZHG qd/nUj93ETt5NgAJp7PbSC3RSVVOIdvqan3H4kX8ZPjkVJ6qzZTq7OaOz6qfD1+3Ut0ceEIdJ/rAZ UbThWt8bo5+QJXaAFttYaxo8cRlltwF7voENadBhA+7WI3xD4g09r1tpfdcK3YdADKNOJZCPnXn2a nQoBkQxXEmAeE6T//51U60ySXb43jA7iAr1SwAcRDY4tDl7rOye8b9FZk5ZA4uPiqN4tv5vFySj6w wW7inYjfkaaG4vOfkWtvxJtE7P3Z8AqB6gvRYxe0tz2/IbRotU5t/8AcSeau/C2uoRXOpHQaG5iZl DLxI5f2BJCwGFXmw1cFQ==; In-Reply-To: <20200218040146.GM7778@bombadil.infradead.org> List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: "linux-mtd" Errors-To: linux-mtd-bounces+gldm-linux-mtd-36=m.gmane-mx.org@lists.infradead.org To: Matthew Wilcox Cc: Latchesar Ionkov , Martin Brandenburg , Jan Kara , Linux Doc Mailing List , Dominique Martinet , Amir Goldstein , Bob Copeland , David Howells , Chris Mason , linux-mtd@lists.infradead.org, Ilya Dryomov , linux-afs@lists.infradead.org, Mike Marshall , Naohiro Aota , Christoph Hellwig , linux-nilfs@vger.kernel.org, Andreas Gruenbacher , Sage Weil , Jonathan Corbet , Richard Weinberger , Tyler Hicks , cluster-devel@redhat.com, v9fs-developer@lists.sourceforge.net, Gao Xiang , linux-ext4@vger.kernel.org, Salah Em Mon, 17 Feb 2020 20:01:46 -0800 Matthew Wilcox escreveu: > On Mon, Feb 17, 2020 at 05:11:46PM +0100, Mauro Carvalho Chehab wrote: > > There are lots of plain text documents under Documentation/filesystems. > > > > Manually convert several of those to ReST and add them to the index file. > > I think at least 90% of this material needs to be in admin-guide. Should > we create Documentation/admin-guide/filesystems/ and move most of these > files there? It makes sense to me. Yet, there are some of those files that contains both user-facing and kernel-facing docs at the same place. Btw, I found the same pattern on *several* other subsystems: when someone is documenting some feature, it tends to document both kAPI, uAPI and admin. Right now, what we did so far on most places were to keep the stuff together, as splitting them could sometimes be painful. As we are too close to finish the ReST conversion[1], I would prefer to first finish it. Then, do a second pass at files outside the new directories (like admin-guide), in order to better organize things, eventually splitting some files into kAPI, uAPI and/or admin-guide. [1] Looking at next-20200217, after my last doc patches applied on this tree: https://git.linuxtv.org/mchehab/experimental.git/log/?h=all_docs_merged excluding (most) false positives, we have now only ~50 text files left to convert: $ dirname $(find Documentation/ -type f|grep -vE '\.(rst|svg|dot|py|awk|sh|pl|gitignore|S|yaml|c|inf|vim|modes)'|grep -vE '(Makefile|Kconfig|LICENSE|COPYING-logo|ChangeLog|CREDITS)'|grep -v devicetree/bindings|grep -vE 'Documentation/(ABI|features|output|SubmittingPatches|CodingStyle|logo.gif|dontdiff|sphinx/requirements.txt|admin-guide/kdump/gdbmacros.txt|admin-guide/aoe/udev.txt|EDID/hex|netlabel/draft-ietf-cipso-ipsecurity-01.txt|firmware_class/hotplug-script|target/target-export-device|networking/mac80211-auth-assoc-deauth.txt|sparc/oradax/dax-hv-api.txt)'|grep -v translations)|sort|uniq -c|sort -n $ echo -n "Total: " $ dirname $(find Documentation/ -type f|grep -vE '\.(rst|svg|dot|py|awk|sh|pl|gitignore|S|yaml|c|inf|vim|modes)'|grep -vE '(Makefile|Kconfig|LICENSE|COPYING-logo|ChangeLog|CREDITS)'|grep -v devicetree/bindings|grep -vE 'Documentation/(ABI|features|output|SubmittingPatches|CodingStyle|logo.gif|dontdiff|sphinx/requirements.txt|admin-guide/kdump/gdbmacros.txt|admin-guide/aoe/udev.txt|EDID/hex|netlabel/draft-ietf-cipso-ipsecurity-01.txt|firmware_class/hotplug-script|target/target-export-device|networking/mac80211-auth-assoc-deauth.txt|sparc/oradax/dax-hv-api.txt)'|grep -v translations)|wc -l 1 Documentation/filesystems/cifs 1 Documentation/filesystems/configfs 1 Documentation/scsi 1 Documentation/virt/kvm/devices 2 Documentation/admin-guide 3 Documentation 6 Documentation/devicetree 6 Documentation/filesystems/caching 8 Documentation/RCU 21 Documentation/filesystems Total: 50 Once we get this series merged, I'm planning to prepare and submit a second series doing the conversion for the other ~20 filesystem files. Btw, if you want to look how things will become after my patch series, I'm keeping a html build after all my patch series at: https://www.infradead.org/~mchehab/kernel_docs/ Cheers, Mauro ______________________________________________________ Linux MTD discussion mailing list http://lists.infradead.org/mailman/listinfo/linux-mtd/