Re: Kernel docs: muddying the waters a bit

[Markus Heiser]

Hi Mauro,

Am 06.05.2016 um 13:03 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxx>:
> Yeah, it looks better, however table truncation seem to be
> happening also on other parts, like the tables on this page:
> 
> 	https://return42.github.io/sphkerneldoc/books/linux_tv/media/v4l/pixfmt-packed-rgb.html
> 	(original table: https://linuxtv.org/downloads/v4l-dvb-apis/packed-rgb.html)
> This table should contain 32 bits, but only the first 7 bits are shown
> 
> and those (among others):
> 	https://return42.github.io/sphkerneldoc/books/linux_tv/media/v4l/pixfmt-y41p.html
> 	https://return42.github.io/sphkerneldoc/books/linux_tv/media/v4l/dev-sliced-vbi.html
> 	https://return42.github.io/sphkerneldoc/books/linux_tv/media/v4l/subdev-formats.html
> 
> Hmm... after looking more carefully, it added a horizontal scroll bar.
> That looks ugly, IMHO, and makes harder to understand its contents. The
> last one, in particular (https://return42.github.io/sphkerneldoc/books/linux_tv/media/v4l/subdev-formats.html),
> is a big table on both horiz and vert dimensions. Try to read how the
> bits are packed on a random line in the middle of the table, like
> MEDIA_BUS_FMT_BGR565_2X8_LE and you'll understand what I mean.

I know what you mean ;-) ... I'am also unhappy, but I will address this point
later when it goes to finish the layout.

Currently lets focus on contend and (the two)extensions.

> The table here looks weird (although it is correct):
> 	https://return42.github.io/sphkerneldoc/books/linux_tv/media/v4l/pixfmt-srggb10p.html
> 	(original table: https://linuxtv.org/downloads/v4l-dvb-apis/pixfmt-srggb10p.html)
> 

I validated this and the other tables you mentioned above ... these are 
all correct migrated ... it is 1:1 translated from DocBook ... they
might be show different to this what you know from your docbook
toolchain, because in the docbook-html you have no table grids and 
wrong cellspans are not clear ... sometimes, like in the last example 
you gave:

	    <tgroup cols="5" align="center">
	      <colspec align="left" colwidth="2*" />
	      <tbody valign="top">

a colspec might ambiguous ... so there is no clear role to migrate.

> It seems that Sphinx is assuming something like "A4 portrait" for
> the margins, while those big tables would only fit (in PDF) as
> "A4 landscape".

No, no, no ;-)

Sphinx assumes nothing about the layout, sphinx and the underlying
docutils mostly juggling with nodes and the writers in e.g. the
html-writer, outputs a clear HTML without any style but with classified 
HTML tags. Styling is done in the presentation layer, in HTML, it is 
done in CSS.

> I guess the better would be to not limit the right
> margin or to change it where those big tables happen, in order to
> allow PDF generation.

Generating PDF has nothing to do with generating HTML. To generate
PDF there is a other writer, the latex2e writer, which produce 
LaTeX markup from which you build PDF or other printed-like medias.
 
> 
> There are also some tables that went wrong. See the Color Sample
> Location table at:
> 	https://return42.github.io/sphkerneldoc/books/linux_tv/media/v4l/pixfmt-yuv444m.html
> I'm pretty sure we'll need to fix some cases like that manually.
> I didn't check, but perhaps, in this case, the DocBook were using 
> empty columns just to make the table bigger. If so, this is not a
> problem with the conversion, and should be manually fixed later.

+1

Yes, lets do it manually later ... what I have in my POC is a automated
process, it is hard to consider individuals in an automatic process.
Making details *nicer* and making ambiguous markups clear is manually
done in minutes where I need hours to implement this in a automated
process.

Aside, from:  http://docutils.sourceforge.net/docs/peps/pep-0258.html

Docutils Project Model -- Project components and data flow:

                 +---------------------------+
                 |        Docutils:          |
                 | docutils.core.Publisher,  |
                 | docutils.core.publish_*() |
                 +---------------------------+
                  /            |            \
                 /             |             \
        1,3,5   /        6     |              \ 7
       +--------+       +-------------+       +--------+
       | READER | ----> | TRANSFORMER | ====> | WRITER |
       +--------+       +-------------+       +--------+
        /     \\                                  |
       /       \\                                 |
 2    /      4  \\                             8  |
+-------+   +--------+                        +--------+
| INPUT |   | PARSER |                        | OUTPUT |
+-------+   +--------+                        +--------+


This is a bit simplified, because we use sphinx, which 
has "builders" and sits on top of this architecture.
But it might help to see, that processes like reading,
transforming and writing are discrete.

In short: readers (the reST file reader) are creating node trees,
which are transformed by a transformer (e.g. a HTML transformer),
the writer only writes the output to a file (and copies some files
like CSS files).

If I say "HTML-writer" I address the unity off the HTML-transformer
plus the HTML-writer. In Sphinx terminus/architecture, replace the
word writer with the word "builder" ... there you have (e.g.) a 
"HTML builder" and a "LaTeX builder".

--Markus--