Remove row numbers from tables in V4L2 documentation

Hello,

While documenting the metadata API I got annoyed by how tables were converted from DocBook to ReST.

The table format currently used by the documentation is as follows:

- .. row 1
- row 1, entry 1
- row 1, entry 2
- .. row 2
- row 2, entry 1
- row 2, entry 2

The comments that include row numbers are not only useless, but make row insertion or deletion painful.

I propose switching to the following format instead:

* - row 1, entry 1
- row 1, entry 2
* - row 2, entry 1
- row 2, entry 2

I've pushed two patches that perform the conversion to

git://linuxtv.org/pinchartl/media.git v4l2/doc

I can't post the patch series to the mailing list due to its size (112 files changed, 15726 insertions(+), 31353 deletions(-)). However, the bulk of the changes are performed by a patch generated by a Python script, which should hopefully be easier to review (I realize that the regexs used in the script are still a bit painful to review, apologies about that).

The first patch in the series performs a few manual small white space changes for odd cases that the Python script can't handle. The second patch is the result of running the script, which follows. I've also included it in the patch's commit message.

I've compared the compiled html documentation before and after the patches. There are no differences, so I'm quite confident that the conversion was done right.

Given the high risk of conflict, I would recommend merging the patches for v4.9 now as no other v4.9 pull request should be queued.

------------------------------------------------------------------------------
#!/usr/bin/python

import io
import re
import sys

def process_table(fname, data):

	if fname.endswith('hist-v4l2.rst'):
		data = re.sub(u'\n{1,2}\t( ?)  -( ?) ?', u'\n\t\\1 -\\2', data, flags = re.MULTILINE)
		data = re.sub(u'\n(\t|       )-  \.\. row [0-9]+\n\t  ?-( ?) ?', u'\\1* -\\2', data, flags = re.MULTILINE)
	else:
		data = re.sub(u'\n{1,2}       -( ?) ?', u'\n      -\\1', data, flags = re.MULTILINE)
		data = re.sub(u'(\n?)(\n\n    -  \.\. row 1\n)', u'\n\\2', data, flags = re.MULTILINE)
		data = re.sub(u'\n    -  \.\. row [0-9]+\n      -( ?) ?', u'    * -\\1', data, flags = re.MULTILINE)
		data = re.sub(u'\n    -  \.\. row [0-9]+\n       \.\. (_[A-Z0-9_`-]*:)', u'\n    -  .. \\1', data, flags = re.MULTILINE)
		data = re.sub(u'\n    -  \.\. (_[A-Z0-9_`-]*:)\n      -', u'    * .. \\1\n\n      -', data, flags = re.MULTILINE)
		data = re.sub(u'^       - ', u'      -', data, flags = re.MULTILINE)
		data = re.sub(u'^(\t{1,2})  ', u'\\1', data, flags = re.MULTILINE)

	return data

def process_file(fname, data):

	buf = io.StringIO(data)
	output = ''
	in_table = False
	table_separator = 0

	for line in buf.readlines():
		if line.find('.. flat-table::') != -1:
			in_table = True
			table = ''
		elif in_table and not re.match('^[\t\n]|(    )', line):
			in_table = False
			output += process_table(fname, table)

		if in_table:
			table += line
		else:
			output += line

	if in_table:
		in_table = False
		output += process_table(fname, table)

	return output

fname = sys.argv[1]

data = file(fname, 'rb').read().decode('utf-8')
data = process_file(fname, data)
file(fname, 'wb').write(data.encode('utf-8'))
------------------------------------------------------------------------------

Regards,

Laurent Pinchart

Am 21.09.2016 um 10:48 schrieb Laurent Pinchart <[email protected]>:

I suggested to drop them, but Mauro wanted to address this later:

https://www.mail-archive.com/[email protected]/msg100971.html

-- Markus --

Hi Markus,

Mauro said he would take care of it for v4.9, these two patches might be our last occasion not to miss the release ;-) Let's see what Mauro says.

Regards,

Laurent Pinchart

Em Wed, 21 Sep 2016 11:48:22 +0300
Laurent Pinchart <[email protected]> escreveu:

Applied. Thanks!
Thanks,
Mauro