Re: DocBook 5 support in yelp/gnome-doc-utils

[Shaun McCance <shaunm gnome org>]

On Fri, 2010-03-05 at 20:35 +0000, brian m. carlson wrote:
> I'm interested in adding DocBook 5 support to yelp and gnome-doc-utils.
> However, before I spend a large amount of time developing code, I'd like
> to know if (at least theoretically) this would be accepted into the main
> repository.

Absolutely.  I have no qualms whatsoever with adding support
for DocBook 5 into Yelp.  It's just not something I can spend
time on right now.

> My rationale for wanting to do so is that I have a very large collection
> of DocBook 5 files (>250) and think it would be useful to have a
> more-or-less general-purpose viewer for them.
> 
> My general plan of attack would be to modify the current XSLT
> stylesheets in gnome-doc-utils to handle DocBook files correctly whether
> they are version 4 or version 5.  I anticipate that most of the DocBook
> 5 handling code would be isolated in a small number of stylesheets.
> Also, this would also include code for handling basic XLink features,
> which are used for linking in DocBook 5.  I don't expect to touch much
> yelp code at all, although currently there are few assumptions in the
> code that don't hold true for DocBook 5 that would need to be fixed.

Some notes:

Gnome 2.30 will be the last release for gnome-doc-utils.  New
development on the stylesheets is in yelp-xsl.  For information
about how Yelp stuff is being split up for 3.0, see here:

http://mail.gnome.org/archives/desktop-devel-list/2010-February/msg00047.html

The API in yelp-xsl has changed some, and it's still unstable,
but it's not drastically different.

Similarly, current Yelp development is on the yelp-3-0 branch.
I don't plan on doing anything with the current master after
2.28.  There is a pre-scanner in the DocBook transformation
code that may need to be adjusted to work with namespaces.

I do think you're going to have to touch every single XSLT file
because of the DocBook namespace.  Fortunately, most changes
will be pretty routine.  Anything that looks like this:

<xsl:template match="abbrev">

will need to look like this instead:

<xsl:template match="abbrev | db:abbrev">

where xmlns:db="http://docbook.org/ns/docbook";.  Almost all
inline elements go through the db2html.inline template, so
you can just add ubiquitous linking there and be 90% of the
way done.  (See, for example, how mal2html.span handles it.)

I have no problems with the stylesheets being loose, by the
way.  I usually avoid lots of checks.  So if XLink ends up
working on DocBook 4 as a side effect, that doesn't bother
me.

I am planning on doing work to support indexes before 3.0.
Yelp has never supported them in the past because we never
use them in Gnome.  But I've had a request from a team I
happen to like a lot.  I don't know if that's important to
you or not.

Feel free to ask questions on the list or pintg me on IRC
(shaunm in #docs on irc.gnome.org).

Thanks,
Shaun