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
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
