Em Thu, 18 Feb 2016 13:23:37 +0200 Jani Nikula <jani.nikula@xxxxxxxxx> escreveu: > On Thu, 18 Feb 2016, Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxx> 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. 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-media" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
