Re: Kernel docs: muddying the waters a bit

[Mauro Carvalho Chehab <mchehab@osg.samsung.com>]

Em Fri, 6 May 2016 18:26:10 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> Hi Mauro,
> 
> Am 06.05.2016 um 13:03 schrieb Mauro Carvalho Chehab <mchehab@osg.samsung.com>:
> > 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.

OK.

> > 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.

Ok, that's what I was thinking. Ok, this can be fixed later manually,
where needed. Of course one way would be to disable grids on those
tables, but I would instead fix it.

> 
> > 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.

Hmm... Then there's something deadly wrong at CSS template, as it is
shown texts only at half of my horizontal res (1920).

Probably this is the culpit:

      .container { margin: 50px auto 40px auto; width: 600px; text-align: center; }

width is set to 600px, instead of using a percentage, like 100%
(or 90%).

> 
> > 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.

Ok.

>  
> > 
> > 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.

Yeah, we should not try to fix everything via auto-scripts, and
spending time right now with manual fixes will be wasted, as we need
to run it at the latest media documentation, as changes might have
happened upstream.

> 
> 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--
> 
> 
> 
> 
> 


-- 
Thanks,
Mauro