Re: [docbook] linux-kernel doc question/problem

["Michael(tm) Smith" <smith@sideshowbarker.net>]

Randy Dunlap <rdunlap@xenotime.net>, 2008-03-18 14:58 -0700:

> Sometimes (and I don't know precisely when/under what conditions)
> the Linux kernel generated documentation abruptly ends with:
> 
> xmlto: input does not validate (status 1)
> /scsi/linsrc/mmotm-2008-0314-1449/Documentation/DocBook/kernel-api.xml:71468: parser error : Opening and ending tag mismatch: programlisting line 71464 and para
>    </para><para>
>           ^
> /scsi/linsrc/mmotm-2008-0314-1449/Documentation/DocBook/kernel-api.xml:71480: parser error : Opening and ending tag mismatch: para line 71473 and programlisting
> </programlisting></informalexample>
>                  ^
> make[1]: *** [Documentation/DocBook/kernel-api.html] Error 1
> 
> This is caused by the kernel-doc comment in the source file
> linux/drivers/i2c/i2c-core.c:
> 
>  * This routine is used to declare an I2C adapter when its bus number
>  * matters.  Example: for I2C adapters from system-on-chip CPUs, or
>  * otherwise built in to the system's mainboard, and where i2c_board_info
>  * is used to properly configure I2C devices.
> 
> Does the string "Example:" cause any special handing in docbook?
> If not, then I'll know to look somewhere else.

The string "Example:" in DocBook content definitely doesn't cause
any kind of special handling in the DocBook XSL stylesheets (which
is what xmlto is mostly likely trying to use). Nor should most any
other string in element content in DocBook XML source.

The error you're seeing from xmlto appears to be caused by the
kernel-api.xml file not being well-formed XML.

If that kernel-api.xml file is generated in part or in whole from
comments in the i2c-core.c source file, then it seems that
whatever tool is extracting those comments and generating DocBook
XML from them is not doing it correctly for all cases.

I'd be happy to look at the build to try to see if I can help get
it figured out. If you want to try to troubleshoot it in real
time, you can find me on the #docbook channel on irc.freenode.net.

  --Mike

-- 
Michael(tm) Smith
http://people.w3.org/mike/
http://sideshowbarker.net/

smime.p7s