From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1426153AbcBRMHN (ORCPT ); Thu, 18 Feb 2016 07:07:13 -0500 Received: from lb1-smtp-cloud2.xs4all.net ([194.109.24.21]:49005 "EHLO lb1-smtp-cloud2.xs4all.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1426118AbcBRMHL (ORCPT ); Thu, 18 Feb 2016 07:07:11 -0500 Subject: Re: Kernel docs: muddying the waters a bit To: Mauro Carvalho Chehab , Jani Nikula References: <20160213145317.247c63c7@lwn.net> <86fuwwcdmd.fsf@hiro.keithp.com> <20160217151401.3cb82f65@lwn.net> <874md6fkna.fsf@intel.com> <20160218082657.5a1a5b0f@recife.lan> <87r3gadzye.fsf@intel.com> <20160218100427.6471cb22@recife.lan> Cc: Daniel Vetter , Jonathan Corbet , Keith Packard , LKML , linux-doc@vger.kernel.org, linux-media@vger.kernel.org From: Hans Verkuil Message-ID: <56C5B3E7.6030509@xs4all.nl> Date: Thu, 18 Feb 2016 13:07:03 +0100 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Icedove/38.5.0 MIME-Version: 1.0 In-Reply-To: <20160218100427.6471cb22@recife.lan> Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On 02/18/16 13:04, Mauro Carvalho Chehab wrote: > Em Thu, 18 Feb 2016 13:23:37 +0200 > Jani Nikula escreveu: > >> On Thu, 18 Feb 2016, Mauro Carvalho Chehab wrote: >>> For simple documents like the one produced by kernel-doc, I guess >>> all markup languages would work equally. >>> >>> The problem is for complex documents like the media kAPI one, where >>> the document was written to produce a book. So, it uses some complex >>> features found at DocBook. One of such features we use extensively >>> is the capability of having a table with per-line columns. This way, >>> we can produce things like: >>> >>> V4L2_CID_COLOR_KILLER boolean Enable the color killer (i. e. force a black & white image in case of a weak video signal). >>> V4L2_CID_COLORFX enum Selects a color effect. The following values are defined: >>> V4L2_COLORFX_NONE Color effect is disabled. >>> V4L2_COLORFX_ANTIQUE An aging (old photo) effect. >>> V4L2_COLORFX_ART_FREEZE Frost color effect. >>> >>> In the above example, we have a main 3 columns table, and we embed >>> a 2 columns table at the third field of V4L2_CID_COLORFX to represent >>> possible values for this menu control. >>> >>> See https://linuxtv.org/downloads/v4l-dvb-apis/control.html for the >>> complete output of it. >>> >>> This is used extensively inside the media DocBook, and properly >>> supporting it is one of our major concerns. >>> >>> Are there any way to represent those things with the markup >>> languages currently being analyzed? >>> >>> Converting those tables will likely require manual work, as I don't >>> think automatic tools will properly handle it, specially since we >>> use some DocBook macros to help creating such tables. >> >> Since I've let myself be told that asciidoc handles tables better than >> reStructuredText, I tested this a bit with the presumably inferior one. >> >> rst has two table types, simple tables and grid tables [1]. It seems >> like grid tables can do pretty much anything, but they can be cumbersome >> to work with. So I tried to check what can be done with simple tables. >> >> Here's a sample, converted using rst2html (Sphinx will be prettier, but >> rst2html works for simple things like this): >> >> https://people.freedesktop.org/~jani/v4l-table-within-table.rst >> https://people.freedesktop.org/~jani/v4l-table-within-table.html > > Yes, this would work. Can we remove the border from the main table? > I guess it would be nicer. > >> >> Rather than using nested tables, you might want to consider using >> definition lists within tables: >> >> https://people.freedesktop.org/~jani/v4l-definition-list-within-table.rst >> https://people.freedesktop.org/~jani/v4l-definition-list-within-table.html >> >> You be the judge, but I think this is workable. > > It is workable, but I guess nested tables produced a better result. > > I did myself a test with nested tables with asciidoc too: > > https://mchehab.fedorapeople.org/media-kabi-docs-test/pandoc_asciidoc/table.html > https://mchehab.fedorapeople.org/media-kabi-docs-test/pandoc_asciidoc/table.ascii > > With looks very decent to me. It does, except for the vertical alignment of the third column (at least when viewed with google chrome). Hans > > I had to manually add the nested table, as pandoc conversion sent the > DocBook's nested table to /dev/null. > > Thanks, > Mauro >