Reading the DocBook files in Linux kernel’s documentation

This is my short saga about my not necessarily intelligent actions for reading a DocBook paper.

So I wanted to read some documentation from my Linux kernel sources. It happened to be in DocBook format.

In the kernel source’s root, I tried

$ make htmldocs

or I could have gone

$ make pdfdocs

Or mandocs. Or sgmldocs. Or psdocs.

But that builds only the DocBook templates in Documentation/DocBook/. I need those in Documentation/sound/alsa/DocBook!

I tried to copy the Makefile to the target directory, and change the assignment of DOCBOOKS to the files I wanted handled. But that didn’t work, because the Makefile couldn’t find the script/ subdirectory. Or as “make” put it:

make: *** No rule to make target `/scripts/kernel-doc', needed by `/alsa-driver-api.tmpl'.  Stop.

OK, this was a bit too much. How about just going…

$ docbook2html writing-an-alsa-driver.tmpl

Works, creates a lot of scattered HTML files. Not so easy to read. Can’t I get it in a single document?

$ docbook2rtf writing-an-alsa-driver.tmpl

Huh? WTF? RTF? Yes, it’s apparently still alive. And hey, one can easily export it to PDF with OpenOffice!

This probably isn’t exactly the way the kernel hackers meant it to be done. On the other hand, it’s by far too much effort for just reading a document by and for the community…

I’m sure someone knowns about the obvious way I missed. Comments below, please…