linux-kernel - Re: Kernel docs: muddying the waters a bit

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20160218100427.6471cb22@recife.lan>
Date:	Thu, 18 Feb 2016 10:04:27 -0200
From:	Mauro Carvalho Chehab <mchehab@....samsung.com>
To:	Jani Nikula <jani.nikula@...el.com>
Cc:	Daniel Vetter <daniel.vetter@...ll.ch>,
	Jonathan Corbet <corbet@....net>,
	Keith Packard <keithp@...thp.com>,
	LKML <linux-kernel@...r.kernel.org>, linux-doc@...r.kernel.org,
	linux-media@...r.kernel.org, Hans Verkuil <hverkuil@...all.nl>
Subject: Re: Kernel docs: muddying the waters a bit

Em Thu, 18 Feb 2016 13:23:37 +0200
Jani Nikula <jani.nikula@...el.com> escreveu:

> On Thu, 18 Feb 2016, Mauro Carvalho Chehab <mchehab@....samsung.com> 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.

I had to manually add the nested table, as pandoc conversion sent the
DocBook's nested table to /dev/null.

Thanks,
Mauro