Re: [docbook-apps] ANNOUNCE: DocBook 5 XSL 1.72.0 released

["Bob Stayton" <bobs@sagehill.net>]

> Would the Perl script you describe be suitable to migrate customization
> layers? If so is it available somewhere?

Well, sort of.  The Perl script is available from the DocBook SourceForge 
SVN tree:

trunk/releasetools/makedb5xsl

It was designed for converting a tree of DocBook XSL release files, and 
applying some special case fixups for certain files, so it is only sort of 
suitable for a customization layer.  You would have to put your 
customization files into a separate directory, and specify a second empty 
directory name for the output (careful: it will delete that second 
directory before remaking it, so don't specify a directory containing any 
significant content).  When you run it:

perl makedb5xsl inputdir outputdir

It will generate a bunch of noise not related to your files, but the end 
result should be a copy of your customization layer files with the 
namespace added in the output directory (along with a few other useless 
files like README, etc.).

I think it would be good to adapt the script for handling a customization 
layer and bundling it with the package.

Bob Stayton
Sagehill Enterprises
DocBook Consulting
bobs@sagehill.net


----- Original Message ----- 
From: "Camille Bégnis" <camille@neodoc.biz>
To: "Bob Stayton" <bobs@sagehill.net>
Cc: "DocBook Apps" <docbook-apps@lists.oasis-open.org>
Sent: Wednesday, January 24, 2007 1:14 AM
Subject: Re: [docbook-apps] ANNOUNCE: DocBook 5 XSL 1.72.0 released


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi all,

Thanks Bob for this extensive explanation.

Would the Perl script you describe be suitable to migrate customization
layers? If so is it available somewhere?

Camille.

Bob Stayton a écrit :
> The DocBook Project announces the first release of the DocBook 5 XSL
> Stylesheets in the SourceForge downloads area. The Docbook 5 XSL 1.72.0
> package is available for download from the project website:
>
>  http://docbook.sf.net/files/docbook5-xsl/latest
>  http://sourceforge.net/projects/docbook
>
> The DocBook 5 XSL Stylesheets are the same as the regular 1.72.0
> stylesheet release except that the templates match on elements in the
> DocBook namespace.  Below is the README included with the package.
>
>
> DocBook 5 XSL stylesheets
> ===========================================
> This package contains a release of XSL stylesheets
> for processing DocBook 5 documents.  The stylesheets are
> the same as the concurrent stylesheet release except that
> the templates match on elements in the DocBook namespace.
>
> Note, the stylesheets in these directories have
> not yet been converted to use the DocBook 5 namespace:
>
>  slides
>  website
>  roundtrip
>
>
> Background
> -------------
> DocBook 5 differs from preceding versions of DocBook because
> its elements are in a namespace "http://docbook.org/ns/docbook";.
> Because the elements are in a namespace, the regular
> DocBook XSL templates do not match on the elements.
> In XSLT, a match attribute must explicitly specify
> the namespace prefix to match an element in that namespace
> (the default namespace does not apply to pattern matches).
>
> The regular stylesheets are able to process DocBook 5
> documents now, because they preprocess a DB5 document to
> remove the namespace.  When the regular stylesheet
> detects that the root element is in the namespace, it
> processes the document with mode="stripNS" to copy all
> the nodes to a variable, but without the DocBook namespace.
> Then it converts the variable to a nodeset, and processes
> the nodeset with the regular templates.
>
> The alternative approach is to create a set of templates
> that match on the native namespace of DocBook 5 documents.
> These stylesheets do that.
>
> These stylesheets completely mimic the behavior of the
> existing stylesheets.  These are not XSLT 2.0 stylesheets,
> and they do not have any other significant changes than handling
> the namespaced elements.
>
> The two main advantages of these stylesheets are:
>
> a. You can write customization layers using the DocBook namespace.
>
> b. The xml:base of the root element is not lost during processing
> (so things like images and the olink database can be found
> more easily).
>
>
> How these stylesheets were produced
> ----------------------------------------
> These stylesheets were created from a DocBook XSL
> snapshot.  Each xsl file was processed with a
> Perl script and its output placed in a parallel
> directory tree.  Any non-xsl files were simply copied
> into place.
>
> Perl was used because of its excellent regular expression
> handling, and because Perl is able to preserve all whitespace.
> This retains the pretty-printed format that makes
> the stylesheets easier to read and understand.
>
> The stylesheet transforms each XSL match, select, test,
> count, from, use, and elements attribute to add a "d:"
> prefix to each element referenced in the attribute.
> For example:
>
>  <xsl:template match="para">
>
> becomes:
>
>  <xsl:template match="d:para">
>
> In addition, each stylesheet file has a namespace declaration
> added in its root element:
>
>  <xsl:stylesheet  xslns:d="http://docbook.org/ns/docbook";
>
> The combination of these two changes means that the templates
> now recognize DocBook 5 elements in their native namespace.
>
>
> How to use these stylesheets
> --------------------------------
> A DocBook 5 document has the DocBook namespace declaration
> in the root element, along with the version attribute:
>
>  <book xslns="http://docbook.org/ns/docbook"; version="5.0">
>
> You can process a DocBook 5 document with these stylesheets
> using any XSLT processor, including xsltproc, Saxon 6 or 8,
> and Xalan.  Use these stylesheets as you would a stylesheet
> from the regular distribution (except for slides, website,
> and roundtrip).
>
> If you happen to process a DocBook document whose root element
> is without the namespace declaration, the stylesheet
> does not fail.  Rather, it detects that the document
> does not have the namespace, and preprocesses it to add the
> namespace declaration to all elements in the document.
> In a manner similar to stripNS, it copies the elements
> to a variable while adding the namespace, converts the
> variable to a nodeset, and then processes the nodeset with
> the namespace-aware templates.
>
> If the stylesheet encounters an element from your file
> for which the stylesheet has no matching template,
> it reports the unmatched element.  In these stylesheets,
> it also reports the namespace URI that the element has.
>
>
> Customizing these stylesheets
> --------------------------------
> These stylesheets are customized with a customization
> layer in the same manner as for the regular stylesheets,
> with two differences.
>
> When you create a customization layer, you must do two things:
>
> a.  Add the namespace declaration (with a prefix of your choice):
>
>  <xsl:stylesheet  xslns:d="http://docbook.org/ns/docbook";
>
> b.  Use the namespace prefix on all DocBook element names:
>
>  <xsl:template match="d:formalpara">
>
> Be sure to include the namespace prefix on all element
> references, including those in match, select, and test
> attributes, even when using an axis specifier.  Here are
> some examples:
>
>  <xsl:if test="d:title">
>
>  <xsl:apply-templates select="d:title" mode="list.title.mode"/>
>
>  <xsl:apply-templates
>       select="*[not(self::d:listitem or self::d:title
>               or self::d:titleabbrev)] |
>               comment()[not(preceding-sibling::d:listitem)] |
>
> processing-instruction()[not(preceding-sibling::d:listitem)]"/>
>
> Failure to add the prefix to an element name will cause
> the stylesheet to silently not match the intended element,
> with consequences that are most likely undesirable.
>
>
> Bob Stayton
> Sagehill Enterprises
> DocBook Consulting
> bobs@sagehill.net
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (GNU/Linux)
Comment: Using GnuPG with Mandriva - http://enigmail.mozdev.org

iD8DBQFFtyNsjv9P65BfOUMRAjILAKC4suP4bT9Dyixo+I+xLQNguHDUJwCgkMKH
YEQINelkoSUcIYUm7nu7vo8=
=bmVO
-----END PGP SIGNATURE-----



--------------------------------------------------------------------------------


> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org