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

[Camille Bégnis <camille@neodoc.biz>]

-----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-----
begin:vcard
fn;quoted-printable:Camille B=C3=A9gnis
n;quoted-printable:B=C3=A9gnis;Camille
org:NeoDoc
adr:Domaine du petit Arbois BP 88;;CEEI;Aix en Provence Cedex 4;;13545;France
email;internet:camille@neodoc.biz
tel;work:+33.4.42.22.62.35 
tel;cell:+33.6.33.15.10.23
note;quoted-printable:Rejoignez mon r=C3=A9seau sur viaduc:=0D=0A=
	=0D=0A=
	http://www.viaduc.com/invitationpersonnelle/002lm14bc0jlkfk
x-mozilla-html:FALSE
url:http://neodoc.biz
version:2.1
end:vcard