Em Fri, 6 May 2016 18:26:10 +0200 Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu: > 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. 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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
