On 02/18/16 13:04, Mauro Carvalho Chehab wrote:
> Em Thu, 18 Feb 2016 13:23:37 +0200
> Jani Nikula <jani.nik...@intel.com> escreveu:
>
>> On Thu, 18 Feb 2016, Mauro Carvalho Chehab <mche...@osg.samsung.com> wrote:
>>> For simple documents like the one produced by kernel-doc, I guess
>>> all markup languages would work equally.
>>>
>>> The problem is for complex documents like the media kAPI one, where
>>> the document was written to produce a book. So, it uses some complex
>>> features found at DocBook. One of such features we use extensively
>>> is the capability of having a table with per-line columns. This way,
>>> we can produce things like:
>>>
>>> V4L2_CID_COLOR_KILLER boolean Enable the color killer (i. e. force a
>>> black & white image in case of a weak video signal).
>>> V4L2_CID_COLORFX enum Selects a color effect. The following values
>>> are defined:
>>> V4L2_COLORFX_NONE Color effect is
>>> disabled.
>>> V4L2_COLORFX_ANTIQUE An aging (old
>>> photo) effect.
>>> V4L2_COLORFX_ART_FREEZE Frost color
>>> effect.
>>>
>>> In the above example, we have a main 3 columns table, and we embed
>>> a 2 columns table at the third field of V4L2_CID_COLORFX to represent
>>> possible values for this menu control.
>>>
>>> See https://linuxtv.org/downloads/v4l-dvb-apis/control.html for the
>>> complete output of it.
>>>
>>> This is used extensively inside the media DocBook, and properly
>>> supporting it is one of our major concerns.
>>>
>>> Are there any way to represent those things with the markup
>>> languages currently being analyzed?
>>>
>>> Converting those tables will likely require manual work, as I don't
>>> think automatic tools will properly handle it, specially since we
>>> use some DocBook macros to help creating such tables.
>>
>> Since I've let myself be told that asciidoc handles tables better than
>> reStructuredText, I tested this a bit with the presumably inferior one.
>>
>> rst has two table types, simple tables and grid tables [1]. It seems
>> like grid tables can do pretty much anything, but they can be cumbersome
>> to work with. So I tried to check what can be done with simple tables.
>>
>> Here's a sample, converted using rst2html (Sphinx will be prettier, but
>> rst2html works for simple things like this):
>>
>> https://people.freedesktop.org/~jani/v4l-table-within-table.rst
>> https://people.freedesktop.org/~jani/v4l-table-within-table.html
>
> Yes, this would work. Can we remove the border from the main table?
> I guess it would be nicer.
>
>>
>> Rather than using nested tables, you might want to consider using
>> definition lists within tables:
>>
>> https://people.freedesktop.org/~jani/v4l-definition-list-within-table.rst
>> https://people.freedesktop.org/~jani/v4l-definition-list-within-table.html
>>
>> You be the judge, but I think this is workable.
>
> It is workable, but I guess nested tables produced a better result.
>
> I did myself a test with nested tables with asciidoc too:
>
> https://mchehab.fedorapeople.org/media-kabi-docs-test/pandoc_asciidoc/table.html
> https://mchehab.fedorapeople.org/media-kabi-docs-test/pandoc_asciidoc/table.ascii
>
> With looks very decent to me.
It does, except for the vertical alignment of the third column (at least when
viewed
with google chrome).
Hans
>
> I had to manually add the nested table, as pandoc conversion sent the
> DocBook's nested table to /dev/null.
>
> Thanks,
> Mauro
>
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
