Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751287AbeAEKWX convert rfc822-to-8bit (ORCPT + 1 other); Fri, 5 Jan 2018 05:22:23 -0500 Received: from smtp2-2.goneo.de ([85.220.129.34]:52345 "EHLO smtp2-2.goneo.de" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1750861AbeAEKWV (ORCPT ); Fri, 5 Jan 2018 05:22:21 -0500 Content-Type: text/plain; charset=us-ascii Mime-Version: 1.0 (Mac OS X Mail 10.3 \(3273\)) Subject: Re: [PATCH] doc: memory-barriers: reStructure Text From: Markus Heiser In-Reply-To: <20180105035245.GA6780@afzalpc> Date: Fri, 5 Jan 2018 11:22:06 +0100 Cc: Boqun Feng , linux-kernel@vger.kernel.org, Linux Doc Mailing List , "Paul E. McKenney" , Will Deacon , Ingo Molnar , Stan Drozd , Palmer Dabbelt , Mauro Carvalho Chehab , Jonathan Corbet Content-Transfer-Encoding: 8BIT Message-Id: <8A12A9DD-5A03-4905-B7CD-4B129D7257F6@darmarit.de> References: <20180103093436.16704-1-afzal.mohd.ma@gmail.com> <20180104014850.GB31392@tardis> <20180104035948.GB3782@afzalpc> <9DBB839D-975D-4E45-A4E2-A8010A55D361@darmarit.de> <20180105035245.GA6780@afzalpc> To: afzal mohammed , Peter Zijlstra X-Mailer: Apple Mail (2.3273) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Return-Path: > Am 05.01.2018 um 04:52 schrieb afzal mohammed : [...] > Initially i was sceptical of rst & once instead of hitting the fly, > hit "make htmldocs" on the keyboard :), and the opinion about it was > changed. Yes, I understand that some of us have a (reasonable) doubt about the reST markup. It is not perfect in any matter, e.g. I don't like the ``monospace`` markup. But this is my home opinion. My hope is, that those of us who have a doubt give reST a chance ... it is a compromise, not as bad as you might think first ... your cooperation and your criticism is needed and welcome. Please let me invite you / read on: There are other plain-text markups e.g. AsciiDoc or Markdown. The reST markup and the Sphinx-builder is a compromise from a evaluation in 2016 (see linux-doc ML subject "muddying the waters" [1]). Jani wrote an article about the evaluation and it results [2]. And there are other articles documenting all the various aspects. - A report from the documentation maintainer [3] - Kernel documentation with Sphinx, part 2: how it works [4] - Kernel documentation update [5] To summarize it with my words: The old DocBook-based toolchain was hard to maintain and of course who want's to write XML? A consistent plain-text markup for articles in /Documentation/* and source-code comments (kernel-doc) was needed. The markup: IMO reST wins that race, because it has a extendable markup specification while others plain-text markups like Markdown have various (HTML) builders with various markup dialects[7] (which is more a mess than a definition). The builder: IMO Sphinx-Doc wins that race, since it is (well) maintained, widely used and has a interface for extensions. I.e. the one extension we wrote: 'kernel-doc' to parse kernel-doc comments from source code and include them in the articles. Perspective: Sphinx-Doc also offers solutions we might use in the future (e.g. building man-pages). Not to end in a mess, extensions should be implemented cautiously and deliberately (be patient). But that should not fool you; yes we have known problems with our toolchain and it is not yet ;) perfect in any matter (e.g. the highlighting in kernel-doc comments or the PDF generation or the sphinx-doc versions shipped with various distributions or ..) Anyway, today we have more than before: The reST learning curve is (compared to DocBook) not hard for newbees and our toolchain is flexible for all the requirements wich might come up in the future. IMO the actual challenge is the content and the organization of the doc-tree and for this [1] https://www.mail-archive.com/search?q=muddying+the+waters&l=linux-doc%40vger.kernel.org [2] https://lwn.net/Articles/692704/ [3] https://lwn.net/Articles/704613/ [4] https://lwn.net/Articles/692705/ [5] https://lwn.net/Articles/705224/ [6] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html [7] http://pandoc.org/MANUAL.html#markdown-variants > It was easy to navigate through various docs & the realized > that various topics (& many) were present (yes, it was there earlier > also, but had to dive inside Documentation & search, while viewing the > toplevel index.html made them standout). It was like earlier you had > to go after docs, but now it was docs coming after you, that is my > opinion. > > Later while fighting with memory-barriers.txt, felt that it might be > good for it as well as to be in that company. > > And the readability as a text is not hurt as well. > > It was thought that rst conversion could be done quickly, but since > this was my first attempt with rst, had to put some effort to get a > not so bad output, even if this patch dies, i am happy to have learnt > rst conversion to some extent. Thats exactly what I mean: give reST a chance :) -- Markus --