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 12:07:38 -0300 Message-ID: <20190423120738.3be8337e@coco.lan> References: <20190423083135.GA11158@hirez.programming.kicks-ass.net> <20190423125519.GA7104@redhat.com> <20190423130132.GT4038@hirez.programming.kicks-ass.net> <20190423132100.GB7132@redhat.com> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Return-path: In-Reply-To: <20190423132100.GB7132-H+wXaHxf7aLQT0dZR+AlfA@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: Mike Snitzer Cc: "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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org, linux-kernel@vger.k List-Id: iommu@lists.linux-foundation.org Em Tue, 23 Apr 2019 09:21:00 -0400 Mike Snitzer escreveu: > On Tue, Apr 23 2019 at 9:01am -0400, > Peter Zijlstra wrote: > > > On Tue, Apr 23, 2019 at 08:55:19AM -0400, Mike Snitzer wrote: > > > On Tue, Apr 23 2019 at 4:31am -0400, > > > Peter Zijlstra wrote: > > > > > > > On Mon, Apr 22, 2019 at 10:27:45AM -0300, Mauro Carvalho Chehab wrote: > > > > > > > > > .../{atomic_bitops.txt => atomic_bitops.rst} | 2 + > > > > > > > > What's happend to atomic_t.txt, also NAK, I still occationally touch > > > > these files. > > > > > > Seems Mauro's point is in the future we need to touch these .rst files > > > in terms of ReST compatible changes. > > > > > > I'm dreading DM documentation changes in the future.. despite Mauro and > > > Jon Corbet informing me that ReST is simple, etc. ReST is simple[1], and neither Jon or me wants to burden developers to use complex documents all over the Kernel tree. ReST is just a way to make the documents with similar visual. The main advantage of ReST is that documents can be better organized, as they will be inside some index.rst file. [1] Ok, as any document, you could write an easy or hard to read stuff. The way we're using on most places is to be just a coding style with benefits. I wrote a quick 101 guide to ReST at the end, with all you probably need to know about it. So, for example, in the specific case of atomic_bitops, all it takes for it to be parsed by Sphinx is to rename it to .rst. With that, it can be added into an index.rst file, like at Documentation/driver-api/index.rst. The document, as is, will be displayed like this: https://www.infradead.org/~mchehab/rst_conversion/driver-api/atomic_bitops.html?highlight=atomic_t And the original text file can also be seen from the output data: https://www.infradead.org/~mchehab/rst_conversion/_sources/driver-api/atomic_bitops.rst.txt > > > > Well, it _can_ be simple, I've seen examples of rst that were not far > > from generated HTML contents. And I must give Jon credit for not > > accepting that atrocious crap. > > > > But yes, I have 0 motivation to learn or abide by rst. It simply doesn't > > give me anything in return. There is no upside, only worse text files :/ > > Right, but these changes aren't meant for our benefit. They are for > users who get cleaner web accessible Linux kernel docs. Seems the > decision has been made that the users' benefit, and broader > modernization of Linux docs, outweighs the inconvenience for engineers > who maintain the content of said documentation. > This kind of thing happens a lot these days: pile on engineers, they can > take it :/ Yes, that's the main goal: ensure that more people will see the documents and write less crappy code. So, overall, reducing the time we spent with reviews of bad code. ---- ================================= My 101 ReST quick reference guide ================================= Basically, a "quick" ReST guide for those that don't want to learn it and like to have an easy to read text document would be 1) to format documents like: ========= Doc Title ========= foo chapter =========== bar section ----------- foobar sub-section ^^^^^^^^^^^^^^^^^^ foobarzeta sub-sub-section .......................... (the actual character used to mark the titles can be different, provided that you use the same character for the same title level - the above is just the way *I* use, as it makes easier for me to remember the title level). 2) remember that ReST considers new lines with same indentation as belonging to the same paragraph. So, foo bar is identical to: foo bar while foo bar will make "foo" bold, and write bar on the next line. So, if you want to have them on two separate lines on its output, it should be either write it as: foo bar or you could use a list: - foo - bar Btw, *a lot* of Kernel documents already have the above format. 3) literal values should be either inside ``foo``, `foo` or on an indented line after a ::, like: example:: # some_command_to_be_typed If you follow those three simple rules, your document will be properly parsed. The above covers 90% of what we normally use. Tables are also easy to write there, as it recognizes two ways to write ascii tables, with are already popular ways to write them. So, those are valid tables: Without a title: === =============== foo foo description bar bar description === =============== +-------+-----------------+ | foo | foo description | +-------+-----------------+ | bar | bar description | +-------+-----------------+ (both will produce exactly the same output) With a title: ===== =============== field description ===== =============== foo foo description bar bar description === =============== +-------+-----------------+ | field | description | +=======+=================+ | foo | foo description | +-------+-----------------+ | bar | bar description | +-------+-----------------+ (both will produce exactly the same output) This is not too different on what we usually do on documents - except that some documents sometimes use UTF8, or a different character set to mark the table lines. So the "conversion" is simply to follow one of the above styles. 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=-0.8 required=3.0 tests=DKIM_INVALID,DKIM_SIGNED, MAILING_LIST_MULTI,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 BD187C10F03 for ; Tue, 23 Apr 2019 15:10:47 +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 8545F2175B for ; Tue, 23 Apr 2019 15:10:47 +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="gyKu5faS" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 8545F2175B 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 5C049C2A; Tue, 23 Apr 2019 15:10:47 +0000 (UTC) Received: from smtp1.linuxfoundation.org (smtp1.linux-foundation.org [172.17.192.35]) by mail.linuxfoundation.org (Postfix) with ESMTPS id 6811EB5F for ; Tue, 23 Apr 2019 15:10:46 +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 83609F4 for ; Tue, 23 Apr 2019 15:10:45 +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=v9zySKYYnsu0nbBdMLtJbdq2RS3FMjAkeykZUsZvTiE=; b=gyKu5faSS8LXZj9XRJouMiBZjU XASolTJePGoBvpLeRtOGD0Jds+L4YqC+8mg1+4Vph7aht+DxgdLkMxSAS2K3rSjLCE/1unPCcHKY8 8CAOq3FvxVhpblpl0otlgX9obPFwANUBjaE2t9wg0sWYYW+hJ+SD7ycBWE9eE1TObd1ngU9LvxnhO N0lZ6kKQx/ikRpAVnOMB2YMjubYbDUC7KXLHGrFGORjQWON1e6rDXUBfbz2NkYEw6XHzvaqT5Mu2F 9O3mBn4OFlBZqhCyQ1xTEMa8W9XVSpJQ3FIjY11bKB5UDyy8Mjbl7Mjm/Dvf5rlA6y1ixusUDLklF 4uUQN6Nw==; 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 1hIx1l-0006YJ-P6; Tue, 23 Apr 2019 15:08:10 +0000 Date: Tue, 23 Apr 2019 12:07:38 -0300 From: Mauro Carvalho Chehab To: Mike Snitzer Subject: Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst Message-ID: <20190423120738.3be8337e@coco.lan> In-Reply-To: <20190423132100.GB7132@redhat.com> References: <20190423083135.GA11158@hirez.programming.kicks-ass.net> <20190423125519.GA7104@redhat.com> <20190423130132.GT4038@hirez.programming.kicks-ass.net> <20190423132100.GB7132@redhat.com> X-Mailer: Claws Mail 3.17.3 (GTK+ 2.24.32; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Cc: "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 , 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 , Borislav Petkov , 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: <20190423150738.xkCBkhS0cGrOPpUQhMfTcrOUAeYnPUdIrZ69Z89QQ0g@z> Em Tue, 23 Apr 2019 09:21:00 -0400 Mike Snitzer escreveu: > On Tue, Apr 23 2019 at 9:01am -0400, > Peter Zijlstra wrote: > > > On Tue, Apr 23, 2019 at 08:55:19AM -0400, Mike Snitzer wrote: > > > On Tue, Apr 23 2019 at 4:31am -0400, > > > Peter Zijlstra wrote: > > > > > > > On Mon, Apr 22, 2019 at 10:27:45AM -0300, Mauro Carvalho Chehab wrote: > > > > > > > > > .../{atomic_bitops.txt => atomic_bitops.rst} | 2 + > > > > > > > > What's happend to atomic_t.txt, also NAK, I still occationally touch > > > > these files. > > > > > > Seems Mauro's point is in the future we need to touch these .rst files > > > in terms of ReST compatible changes. > > > > > > I'm dreading DM documentation changes in the future.. despite Mauro and > > > Jon Corbet informing me that ReST is simple, etc. ReST is simple[1], and neither Jon or me wants to burden developers to use complex documents all over the Kernel tree. ReST is just a way to make the documents with similar visual. The main advantage of ReST is that documents can be better organized, as they will be inside some index.rst file. [1] Ok, as any document, you could write an easy or hard to read stuff. The way we're using on most places is to be just a coding style with benefits. I wrote a quick 101 guide to ReST at the end, with all you probably need to know about it. So, for example, in the specific case of atomic_bitops, all it takes for it to be parsed by Sphinx is to rename it to .rst. With that, it can be added into an index.rst file, like at Documentation/driver-api/index.rst. The document, as is, will be displayed like this: https://www.infradead.org/~mchehab/rst_conversion/driver-api/atomic_bitops.html?highlight=atomic_t And the original text file can also be seen from the output data: https://www.infradead.org/~mchehab/rst_conversion/_sources/driver-api/atomic_bitops.rst.txt > > > > Well, it _can_ be simple, I've seen examples of rst that were not far > > from generated HTML contents. And I must give Jon credit for not > > accepting that atrocious crap. > > > > But yes, I have 0 motivation to learn or abide by rst. It simply doesn't > > give me anything in return. There is no upside, only worse text files :/ > > Right, but these changes aren't meant for our benefit. They are for > users who get cleaner web accessible Linux kernel docs. Seems the > decision has been made that the users' benefit, and broader > modernization of Linux docs, outweighs the inconvenience for engineers > who maintain the content of said documentation. > This kind of thing happens a lot these days: pile on engineers, they can > take it :/ Yes, that's the main goal: ensure that more people will see the documents and write less crappy code. So, overall, reducing the time we spent with reviews of bad code. ---- ================================= My 101 ReST quick reference guide ================================= Basically, a "quick" ReST guide for those that don't want to learn it and like to have an easy to read text document would be 1) to format documents like: ========= Doc Title ========= foo chapter =========== bar section ----------- foobar sub-section ^^^^^^^^^^^^^^^^^^ foobarzeta sub-sub-section .......................... (the actual character used to mark the titles can be different, provided that you use the same character for the same title level - the above is just the way *I* use, as it makes easier for me to remember the title level). 2) remember that ReST considers new lines with same indentation as belonging to the same paragraph. So, foo bar is identical to: foo bar while foo bar will make "foo" bold, and write bar on the next line. So, if you want to have them on two separate lines on its output, it should be either write it as: foo bar or you could use a list: - foo - bar Btw, *a lot* of Kernel documents already have the above format. 3) literal values should be either inside ``foo``, `foo` or on an indented line after a ::, like: example:: # some_command_to_be_typed If you follow those three simple rules, your document will be properly parsed. The above covers 90% of what we normally use. Tables are also easy to write there, as it recognizes two ways to write ascii tables, with are already popular ways to write them. So, those are valid tables: Without a title: === =============== foo foo description bar bar description === =============== +-------+-----------------+ | foo | foo description | +-------+-----------------+ | bar | bar description | +-------+-----------------+ (both will produce exactly the same output) With a title: ===== =============== field description ===== =============== foo foo description bar bar description === =============== +-------+-----------------+ | field | description | +=======+=================+ | foo | foo description | +-------+-----------------+ | bar | bar description | +-------+-----------------+ (both will produce exactly the same output) This is not too different on what we usually do on documents - except that some documents sometimes use UTF8, or a different character set to mark the table lines. So the "conversion" is simply to follow one of the above styles. Thanks, Mauro _______________________________________________ iommu mailing list iommu@lists.linux-foundation.org https://lists.linuxfoundation.org/mailman/listinfo/iommu