[Intel-gfx] [PATCH 4/5] Documentation: drm: Convert KMS Properties HTML table to CALS

[Graham Whaley]

On Tue, 2015-09-01 at 14:56 -0300, Danilo Cesar Lemes de Paula wrote:
> On 08/25/2015 01:10 PM, Graham Whaley wrote:
> > On Tue, 2015-08-25 at 16:29 +0200, Daniel Vetter wrote:
> > > On Tue, Aug 25, 2015 at 10:26:44AM +0100, Graham Whaley wrote:
> > > > The KMS Properties table is in HTML format, which is not
> > > > supported
> > > > for building pdfdocs, resulting in the following types of
> > > > errors:
> > > > 
> > > >  jade:/Documentation/DocBook/drm.xml:34413:15:E: there is no
> > > > attribute
> > > >  "border"
> > > >  jade:/Documentation/DocBook/drm.xml:34413:31:E: there is no
> > > > attribute
> > > >  "cellpadding"
> > > >  jade:/Documentation/DocBook/drm.xml:34413:47:E: there is no
> > > > attribute
> > > >  "cellspacing"
> > > >  jade:/Documentation/DocBook/drm.xml:34414:7:E: document type
> > > > does
> > > > not
> > > >  allow element "tbody" here
> > > > 
> > > > Convert the table over to a CALS format table
> > > 
> > > Hm, long-term plan was to move this table into DOC: comments in
> > > the
> > > source-code using markdown, which we now have (at least in
> > > drm-intel-nightly and also planned to be merged into 4.4). Since
> > > this
> > > is
> > > both a lot of churn I'd like to get there in just 1 step ...
> > > -Daniel
> > First - I've just noted an erroneous debug comment (or two) left in
> > this patch as well, so looks like I will have to re-issue the
> > series
> > anyway.
> > 
> > OK. I guess this comes down to a matter of timing...
> > From Danilos patch of: f6d6913 (drm/doc: Convert to markdown)
> > we can see markdown does not natively support tables, and we'd have
> > to
> > make this a fixed width layout like the one in that patch I
> > suspect.
> > Danilo - any advice on how you did that other table conversion? I
> > just
> > did a pandoc docbook->markdown_github and it looks some way there -
> > but
> > of course seems to have not honored the multi-column items, of
> > which
> > there are a few. It's probably not too bad to fix up by hand - I'll
> > see
> > if I can get that to work...
> 
> Hi Graham,
> 
> To be honest I didn't have to do any conversion as that table was
> already in the header file. I just added 4 spaces so it would be
> transformed into fixed width.
> 
> However, there's tool you can use to help you: http://pandoc.org/try/
> I did a lot of translation there. If your table doesn't have any
> spancells, you can put the HTML code there and get the Markdown for
> free.
> 
> Danilo
Thanks,
 I got to have a look at this yesterday. I did a text render from the
html using 'links' that worked surprisingly well, but the table has
many spancells (both vertical and horizontal), and some other issues
arose. I'll do an email later with some details of what I've found, but
right now I'm not hopeful that it will be practical to move that large
KMS Properties table to markdown. More later.

 Graham