[RFC] Remove row numbers from tables in V4L2 documentation

* [RFC] Remove row numbers from tables in V4L2 documentation
@ 2016-09-21  8:48 Laurent Pinchart
  2016-09-21  9:24 ` Markus Heiser
  2016-09-22 10:05 ` Mauro Carvalho Chehab
  0 siblings, 2 replies; 4+ messages in thread
From: Laurent Pinchart @ 2016-09-21  8:48 UTC (permalink / raw)
  To: linux-media; +Cc: Mauro Carvallo Chehab, Hans Verkuil, Sakari Ailus

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

^ permalink raw reply	[flat|nested] 4+ messages in thread