From mboxrd@z Thu Jan 1 00:00:00 1970 Return-path: Received: from lists.s-osg.org ([54.187.51.154]:38648 "EHLO lists.s-osg.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752079AbcEDQPo (ORCPT ); Wed, 4 May 2016 12:15:44 -0400 Date: Wed, 4 May 2016 13:15:29 -0300 From: Mauro Carvalho Chehab To: Markus Heiser Cc: Daniel Vetter , Jonathan Corbet , Grant Likely , Jani Nikula , Dan Allen , Russel Winder , Keith Packard , LKML , , Hans Verkuil , "linux-media@vger.kernel.org linux-media" , Graham Whaley Subject: Re: Kernel docs: muddying the waters a bit Message-ID: <20160504131529.0be6a9c3@recife.lan> In-Reply-To: <54CDCFE8-45C3-41F6-9497-E02DB4184048@darmarit.de> References: <20160213145317.247c63c7@lwn.net> <87y49zr74t.fsf@intel.com> <20160303071305.247e30b1@lwn.net> <20160303155037.705f33dd@recife.lan> <86egbrm9hw.fsf@hiro.keithp.com> <1457076530.13171.13.camel@winder.org.uk> <87a8m9qoy8.fsf@intel.com> <20160308082948.4e2e0f82@recife.lan> <20160308103922.48d87d9d@recife.lan> <20160308123921.6f2248ab@recife.lan> <20160309182709.7ab1e5db@recife.lan> <87fuvypr2h.fsf@intel.com> <20160310122101.2fca3d79@recife.lan> <8992F589-5B66-4BDB-807A-79AC8644F006@darmarit.de> <20160412094620.4fbf05c0@lwn.net> <54CDCFE8-45C3-41F6-9497-E02DB4184048@darmarit.de> MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: linux-media-owner@vger.kernel.org List-ID: Em Wed, 4 May 2016 11:34:08 +0200 Markus Heiser escreveu: > Hi all, (hi Jonathan, please take note of my offer below) > > Am 03.05.2016 um 16:31 schrieb Daniel Vetter : > > > Hi all, > > > > So sounds like moving ahead with rst/sphinx is the option that should > > allow us to address everyone's concerns eventually? Of course the > > first one won't have it all (media seems really tricky), ... > > BTW: Mauro mentioned that ASCII-art tables are not diff-friendly ... > > Am 18.04.2016 um 13:16 schrieb Mauro Carvalho Chehab : > > > With that sense, the "List tables" format is also not good, as > > one row addition would generate several hunks (one for each column > > of the table), making harder to review the patch by just looking at > > the diff. > > For this, I wrote the "flat-table" reST-directive, which adds > missing cells automatically: > > doc: http://return42.github.io/sphkerneldoc/articles/table_concerns.html#flat-table > source: https://github.com/return42/sphkerneldoc/blob/master/doc/extensions/rstFlatTable.py Yeah, this should address the lack of a proper way to markup cell/row spans, providing the additional bits for the tables we have at media. Yet, there are some issues with table conversions. See below. > > I used "flat-table" to migrate all DocBook-XML documents to reST. With this > directive, I also managed to migrate the complete media book (no more TODOs) > incl. the large tables like them from subdev-formats: > > https://return42.github.io/sphkerneldoc/books/linux_tv/media/v4l/subdev-formats.html > > (Rendering large tables is a general discussion which should not take place in this MT) Some tables, like the one here: https://return42.github.io/sphkerneldoc/books/linux_tv/media/v4l/control.html are truncated (tested with Mozilla and Chrome), and part of the information is lost due to that. Regards, Mauro