From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mauro Carvalho Chehab Subject: Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst Date: Tue, 23 Apr 2019 17:05:02 -0300 Message-ID: <20190423170409.7b1370ac@coco.lan> References: <20190423083135.GA11158@hirez.programming.kicks-ass.net> <20190423125519.GA7104@redhat.com> <20190423130132.GT4038@hirez.programming.kicks-ass.net> <20190423103053.07cf2149@lwn.net> <20190423171158.GG12232@hirez.programming.kicks-ass.net> <20190423172006.GD16353@zn.tnic> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Return-path: In-Reply-To: <20190423172006.GD16353-Jj63ApZU6fQ@public.gmane.org> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: iommu-bounces-cunTk1MwBs9QetFLy7KEm3xJsTq8ys+cHZ5vskTnxNA@public.gmane.org Errors-To: iommu-bounces-cunTk1MwBs9QetFLy7KEm3xJsTq8ys+cHZ5vskTnxNA@public.gmane.org To: Borislav Petkov Cc: Mike Snitzer , "Rafael J. Wysocki" , Linus Walleij , Farhan Ali , Will Deacon , dri-devel-PD4FTy7X32lNgt0PjOBp9y5qC8QIuHrW@public.gmane.org, Jaroslav Kysela , kernel-hardening-ZwoEplunGu1jrUoiu81ncdBPR1lH4CV8@public.gmane.org, Christoph Hellwig , linux-arch-u79uwXL29TY76Z2rM5mHXA@public.gmane.org, linux-sh-u79uwXL29TY76Z2rM5mHXA@public.gmane.org, James Morris , Halil Pasic , tboot-devel-5NWGOfrQmneRv+LV9MX5uipxlwaOVQ5f@public.gmane.org, Alan Stern , openipmi-developer-5NWGOfrQmneRv+LV9MX5uipxlwaOVQ5f@public.gmane.org, Guenter Roeck , Boqun Feng , Nicholas Piggin , Alex Williamson , Matt Mackall , Thomas Gleixner , Sean Paul , Greg Kroah-Hartman , linux-wireless@v List-Id: iommu@lists.linux-foundation.org Em Tue, 23 Apr 2019 19:20:06 +0200 Borislav Petkov escreveu: > On Tue, Apr 23, 2019 at 07:11:58PM +0200, Peter Zijlstra wrote: > > I know I'm an odd duck; but no. They're _less_ accessible for me, as > > both a reader and author. They look 'funny' when read as a text file > > (the only way it makes sense to read them; I spend 99% of my time on a > > computer looking at monospace text interfaces; mutt, vim and console, in > > that approximate order). > > +1 > > It is probably fine to stare at them here > https://www.kernel.org/doc/html/latest/ and the end result is good > for showing them in browsers but after this conversion, it is > getting more and more painful to work with those files. For example, > Documentation/x86/x86_64/mm.txt we use a lot. I'd hate it if I had to go > sort out rest muck first just so that I can read it. That's my view about how that specific file would be after converted to ReST: https://git.linuxtv.org/mchehab/experimental.git/tree/Documentation/x86/x86_64/mm.rst?h=convert_rst_renames I don't have any troubles reading/understanding it as a plain text file, and its html output is also nice (although Sphinx 1.7.8 seems to have some issues when parsing some cells - probably due to some bug): https://www.infradead.org/~mchehab/rst_conversion/x86/x86_64/mm.html > > I think we can simply leave some text files be text files and be done > with it. Changbin's approach was somewhat close to what you want. He simply prepended the tables with ::, in order to show them as plain old ascii: https://lore.kernel.org/lkml/20190423162932.21428-60-changbin.du-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org/ Both equally works, from ReST conversion PoV. I'm fine ether way. I prefer my approach, as, IMHO, it is visually nicer on both text and html versions, but his approach is likely easier to maintain, as doing ascii artwork by hand is sometimes painful. Thanks, Mauro From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-5.8 required=3.0 tests=DKIM_INVALID,DKIM_SIGNED, MAILING_LIST_MULTI,MENTIONS_GIT_HOSTING,SPF_PASS,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 02C61C10F03 for ; Tue, 23 Apr 2019 20:08:40 +0000 (UTC) Received: from mail.linuxfoundation.org (mail.linuxfoundation.org [140.211.169.12]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id C5101217D9 for ; Tue, 23 Apr 2019 20:08:39 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="EzZdj0Rn" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org C5101217D9 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=kernel.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=iommu-bounces@lists.linux-foundation.org Received: from mail.linux-foundation.org (localhost [127.0.0.1]) by mail.linuxfoundation.org (Postfix) with ESMTP id 84A9FE4A; Tue, 23 Apr 2019 20:08:39 +0000 (UTC) Received: from smtp1.linuxfoundation.org (smtp1.linux-foundation.org [172.17.192.35]) by mail.linuxfoundation.org (Postfix) with ESMTPS id 51C5FE48 for ; Tue, 23 Apr 2019 20:08:38 +0000 (UTC) X-Greylist: from auto-whitelisted by SQLgrey-1.7.6 Received: from casper.infradead.org (casper.infradead.org [85.118.1.10]) by smtp1.linuxfoundation.org (Postfix) with ESMTPS id 99137829 for ; Tue, 23 Apr 2019 20:08:37 +0000 (UTC) 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=fNfF1Op4WOz9r7cwOGdHULsoKlkdXOaOBxEXTjXZmBQ=; b=EzZdj0RnPoB5TYkqUDXbC7Hbi6 VGvOQBvIr50BQnT5Ib9xJI45NeqyHgiwHBlAWnQKT9BqHt7FpdVaycpvuMj4ZAOmBgChyIzdCxim5 lkQtwTgUzem6ijTQwUPXh7giNeY3oSIAbIPORizYJTM1HW90s1BzyWDJnWdl5e2w2OkUi6QTgbWyS aVvTwV7/eQ4gf1zkdHRKyRH8syMHcOwEfgDBhDV84qIzzn0W1RXWTDxo03OTdjadeWSGvjKatxo51 ns3pI57qs+F7zySmtv7NjvOBZ89lTwO12so3X23ooHVMf7YT1i8z2UNwrb7AqD4tT20npkuHobEqR jOfD5Kgg==; Received: from 177.17.136.231.dynamic.adsl.gvt.net.br ([177.17.136.231] helo=coco.lan) by casper.infradead.org with esmtpsa (Exim 4.90_1 #2 (Red Hat Linux)) id 1hJ1fY-0001BA-Np; Tue, 23 Apr 2019 20:05:33 +0000 Date: Tue, 23 Apr 2019 17:05:02 -0300 From: Mauro Carvalho Chehab To: Borislav Petkov Subject: Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst Message-ID: <20190423170409.7b1370ac@coco.lan> In-Reply-To: <20190423172006.GD16353@zn.tnic> References: <20190423083135.GA11158@hirez.programming.kicks-ass.net> <20190423125519.GA7104@redhat.com> <20190423130132.GT4038@hirez.programming.kicks-ass.net> <20190423103053.07cf2149@lwn.net> <20190423171158.GG12232@hirez.programming.kicks-ass.net> <20190423172006.GD16353@zn.tnic> X-Mailer: Claws Mail 3.17.3 (GTK+ 2.24.32; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Cc: Mike Snitzer , "Rafael J. Wysocki" , Linus Walleij , Farhan Ali , Will Deacon , dri-devel@lists.freedesktop.org, Jaroslav Kysela , kernel-hardening@lists.openwall.com, Christoph Hellwig , linux-arch@vger.kernel.org, linux-sh@vger.kernel.org, James Morris , Halil Pasic , tboot-devel@lists.sourceforge.net, Alan Stern , openipmi-developer@lists.sourceforge.net, Guenter Roeck , Boqun Feng , Nicholas Piggin , Alex Williamson , Matt Mackall , Thomas Gleixner , Sean Paul , Greg Kroah-Hartman , linux-wireless@vger.kernel.org, linux-kernel@vger.kernel.org, linux-crypto@vger.kernel.org, Mark Rutland , linux-fbdev@vger.kernel.org, linux-ia64@vger.kernel.org, Linux Doc Mailing List , David Airlie , "James E.J. Bottomley" , dm-devel@redhat.com, Harry Wei , Manivannan Sadhasivam , Alasdair Kergon , linux-s390@vger.kernel.org, Alex Shi , Yoshinori Sato , Helge Deller , Sumit Semwal , Bartosz Golaszewski , Changbin Du , Eric Farman , linux-watchdog@vger.kernel.org, Corey Minyard , Mauro Carvalho Chehab , linaro-mm-sig@lists.linaro.org, linux-gpio@vger.kernel.org, Bjorn Helgaas , linux-arm-kernel@lists.infradead.org, Tony Luck , Cornelia Huck , "David S. Miller" , Martin Schwidefsky , Andrea Parri , linux-pci@vger.kernel.org, Akira Yokosawa , Heiko Carstens , platform-driver-x86@vger.kernel.org, "Paul E. McKenney" , Jonathan Corbet , Kishon Vijay Abraham I , Peter Zijlstra , Emese Revfy , Darren Hart , Jade Alglave , "Serge E. Hallyn" , Fenghua Yu , Kees Cook , Arnd Bergmann , Bartlomiej Zolnierkiewicz , Ning Sun , Luc Maranget , Kurt Schwemmer , Guan Xuetao , linux-parisc@vger.kernel.org, iommu@lists.linux-foundation.org, Stuart Hayes , Logan Gunthorpe , Andreas =?UTF-8?B?RsOkcmJlcg==?= , Rich Felker , kvm@vger.kernel.org, Maxime Ripard , Jerry Hoemann , David Howells , linux-mm@kvack.org, Kirti Wankhede , "H. Peter Anvin" , sparclinux@vger.kernel.org, Steffen Klassert , Herbert Xu , x86@kernel.org, Russell King , Ingo Molnar , devicetree@vger.kernel.org, Daniel Lustig , Maarten Lankhorst , linux-block@vger.kernel.org, Rob Herring , Wim Van Sebroeck , Jens Axboe , netdev@vger.kernel.org, linux-security-module@vger.kernel.org, Daniel Vetter , Johannes Berg , Robin Murphy , Andy Shevchenko X-BeenThere: iommu@lists.linux-foundation.org X-Mailman-Version: 2.1.12 Precedence: list List-Id: Development issues for Linux IOMMU support List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: 7bit Sender: iommu-bounces@lists.linux-foundation.org Errors-To: iommu-bounces@lists.linux-foundation.org Message-ID: <20190423200502.Hy8cZz-DU8xSAoj-L41iMVU3SjT5SbEYoBeLF-8fbPw@z> Em Tue, 23 Apr 2019 19:20:06 +0200 Borislav Petkov escreveu: > On Tue, Apr 23, 2019 at 07:11:58PM +0200, Peter Zijlstra wrote: > > I know I'm an odd duck; but no. They're _less_ accessible for me, as > > both a reader and author. They look 'funny' when read as a text file > > (the only way it makes sense to read them; I spend 99% of my time on a > > computer looking at monospace text interfaces; mutt, vim and console, in > > that approximate order). > > +1 > > It is probably fine to stare at them here > https://www.kernel.org/doc/html/latest/ and the end result is good > for showing them in browsers but after this conversion, it is > getting more and more painful to work with those files. For example, > Documentation/x86/x86_64/mm.txt we use a lot. I'd hate it if I had to go > sort out rest muck first just so that I can read it. That's my view about how that specific file would be after converted to ReST: https://git.linuxtv.org/mchehab/experimental.git/tree/Documentation/x86/x86_64/mm.rst?h=convert_rst_renames I don't have any troubles reading/understanding it as a plain text file, and its html output is also nice (although Sphinx 1.7.8 seems to have some issues when parsing some cells - probably due to some bug): https://www.infradead.org/~mchehab/rst_conversion/x86/x86_64/mm.html > > I think we can simply leave some text files be text files and be done > with it. Changbin's approach was somewhat close to what you want. He simply prepended the tables with ::, in order to show them as plain old ascii: https://lore.kernel.org/lkml/20190423162932.21428-60-changbin.du@gmail.com/ Both equally works, from ReST conversion PoV. I'm fine ether way. I prefer my approach, as, IMHO, it is visually nicer on both text and html versions, but his approach is likely easier to maintain, as doing ascii artwork by hand is sometimes painful. Thanks, Mauro _______________________________________________ iommu mailing list iommu@lists.linux-foundation.org https://lists.linuxfoundation.org/mailman/listinfo/iommu