Re: [docbook-apps] customization layer for DocBook 5.0: The Transition Guide

["Ken Morse" <kenneth.morse@gmail.com>]

Hi Mike,

Thanks for all the good information about the stylesheets. Your response to Brett has prompted me to ask a few, hopefully related, questions:

I notice that the howto.xml file you pointed to at 
https://docbook.svn.sourceforge.net/svnroot/docbook/trunk/docbook/relaxng/docbook/howto/
 is slightly different than the one at http://docbook.org/docs/howto/2006-10-22/howto.xml -- is this intentional?

The Transition Guide talks about moving from DocBook 
4.5 to 5.0, but doesn't really cover changes to how the "ns" stylesheets could be used. Presumable a future version of the document should recommend using the "ns" versions of the stylesheets for DocBook 
5.0 documents and also talk about how customization layers would need to be changed (adding namespace prefixes, etc.)?

The section on stylesheets includes a link to "experimental stylesheets" from 
http://sagehill.net/xml/docbook5ns/ -- perhaps the link should be updated to something like http://docbook.sourceforge.net/release/xsl-ns/current/
 and strike the part about the stylesheets being experimental?

Ken

On 8/29/07, Michael(tm) Smith < smith@sideshowbarker.net> wrote:

Brett Leber < bleber+@cs.cmu.edu>, 2007-08-28 14:25 -0400:

> On 8/25/2007 1:04 AM, Michael(tm) Smith wrote:
>> A customization layer; the sources are here:
>>
>> https://docbook.svn.sourceforge.net/svnroot/docbook/trunk/docbook/relaxng/docbook/howto/
>
> Thanks, Michael. I tried building this document on my local machine, and it
> appears that the customization doesn't work when using the DocBook 5
> stylesheets (docbook-xsl-ns-1.73.1).

Sorry, I didn't understand that you were also using the XSL-NS
stylesheets. The existing HTML and FO customization layers there
are for use with the XSL (non-namespaced) stylesheets. It's
basically not possible to use an unmodified XSL customization
layer with the XSL-NS stylesheets, nor to use an unmodified XSL-NS
one with the XSL stylesheets.

Anyway, I've now added namespace-aware html-ns.xsl and fo-ns.xsl
files to the directory at the URL above. Those files are for use
with the XSL-NS stylesheets.

> Should I use the namespace-stripping stylesheets again, or is
> there an easy fix to make the customization work with the
> namespace-aware stylesheets?

To show what sort of changes you need to make in order to modify
an existing customization layer for use with the XSL-NS
stylesheets, I ran a diff between the html.xsl and html-ns.xsl at
the URL above, and have attached that.

It is mostly just a matter of adding namespace prefixes to all
your template matches, tests, etc. Though there are usually some
other complications; for example, in this case, the non-namespaced
stylesheet was expecting to find an articleinfo element. But it
won't find an articleinfo element in the (non-stripped) DocBook 5
howto.xml file, because articleinfo is not valid in DocBook 5.
It'll find an info element instead. So sometimes it's not enough
to just add a namespace prefix; in this case, I had to modify the
customization layer to look for a d:info instead of d:articleinfo.

By the way, I notice that when I use the original XSL
customization layer, all the links in the HTML output contain
@target=_top attributes. But if I use the XSL-NS customization
layer, they don't. I'm not sure why that is, but I don't think
it's due to any problems in the XSL-NS customization layer itself.
It seems to instead be a difference in the XSL-NS stylesheets.


[on the DocBook XSL "cookbook" idea]
> I'd like to involved in such a project, although my utility as an author
> may be limited. Still, what first steps would you recommend (assuming it's
> easiest to start with a collaboration of DocBook users)? Do you think the
> DocBook wiki is a reasonable place to start notes on such a collaboration?

Yeah, the Wiki is a good place to start. If you don't already have
edit access to, please let me know your username, and I'll add you.

Another way you might be able to get in touch with others that are
interested is by dropping by the #docbook channel on irc.freenode.net.

  --Mike

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