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: <20160504131529.0be6a9c3@recife.lan>
Date:	Wed, 4 May 2016 13:15:29 -0300
From:	Mauro Carvalho Chehab <mchehab@....samsung.com>
To:	Markus Heiser <markus.heiser@...marit.de>
Cc:	Daniel Vetter <daniel.vetter@...ll.ch>,
	Jonathan Corbet <corbet@....net>,
	Grant Likely <grant.likely@...retlab.ca>,
	Jani Nikula <jani.nikula@...el.com>,
	Dan Allen <dan@...ndevise.io>,
	Russel Winder <russel@...der.org.uk>,
	Keith Packard <keithp@...thp.com>,
	LKML <linux-kernel@...r.kernel.org>, <linux-doc@...r.kernel.org>,
	Hans Verkuil <hverkuil@...all.nl>,
	"linux-media@...r.kernel.org linux-media" 
	<linux-media@...r.kernel.org>,
	Graham Whaley <graham.whaley@...ux.intel.com>
Subject: Re: Kernel docs: muddying the waters a bit

Em Wed, 4 May 2016 11:34:08 +0200
Markus Heiser <markus.heiser@...marit.de> escreveu:

> Hi all, (hi Jonathan, please take note of my offer below)
> 
> Am 03.05.2016 um 16:31 schrieb Daniel Vetter <daniel.vetter@...ll.ch>:
> 
> > 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 <mchehab@....samsung.com>:
> 
> > 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