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: <FAC968D4-0A71-418C-90A2-3843D46526D0@darmarit.de>
Date:	Fri, 6 May 2016 12:05:30 +0200
From:	Markus Heiser <markus.heiser@...marit.de>
To:	Mauro Carvalho Chehab <mchehab@....samsung.com>
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

Hi Mauro,

Am 04.05.2016 um 18:15 schrieb Mauro Carvalho Chehab <mchehab@....samsung.com>:

> 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 ... 
>> 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.
> 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.

Not a problem of rendering. This was a bug in the magration from DocBook to reST. 
You might remember that we have discussed, that some of the tables are better
marked-up as definition lists. This was (the last) one I forgot to convert to 
a definition list ... I hope it was the last one, if not and you find more 
or other broken parts, please inform me (on the linux-tv mailing, or direct).

--Markus--